Doc: Improve QLineEdit documentation
Edited the text based on MS Style Guide, added a few new sections under Detailed Desccription and a link to the Line Edits Example topic. Task-number: QTBUG-119552 Change-Id: Iecaa142628019118e271e392a3e332841a7b5af2 Reviewed-by: Kai Köhne <kai.koehne@qt.io> (cherry picked from commit f6566dd4c6aafa60c134fa40e2c48c6706724363) Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org> (cherry picked from commit 218eec49a740170842ff8a5dbe50c341b9f1de78)
This commit is contained in:
Esa Törmänen
Qt Cherry-pick Bot
parent
2f96047a8c
commit
d19037271c
@ -100,55 +100,66 @@ void QLineEdit::initStyleOption(QStyleOptionFrame *option) const
|
||||
|
||||
\image windows-lineedit.png
|
||||
|
||||
A line edit allows the user to enter and edit a single line of
|
||||
plain text with a useful collection of editing functions,
|
||||
including undo and redo, cut and paste, and drag and drop (see
|
||||
\l setDragEnabled()).
|
||||
A line edit allows users to enter and edit a single line of
|
||||
plain text with useful editing functions, including undo and redo, cut and
|
||||
paste, and drag and drop.
|
||||
|
||||
By changing the echoMode() of a line edit, it can also be used as
|
||||
a "write-only" field, for inputs such as passwords.
|
||||
a write-only field for inputs such as passwords.
|
||||
|
||||
The length of the text can be constrained to maxLength(). The text
|
||||
can be arbitrarily constrained using a validator() or an
|
||||
inputMask(), or both. When switching between a validator and an input mask
|
||||
on the same line edit, it is best to clear the validator or input mask to
|
||||
prevent undefined behavior.
|
||||
|
||||
A related class is QTextEdit which allows multi-line, rich text
|
||||
QTextEdit is a related class that allows multi-line, rich text
|
||||
editing.
|
||||
|
||||
You can change the text with setText() or insert(). The text is
|
||||
retrieved with text(); the displayed text (which may be different,
|
||||
see \l{EchoMode}) is retrieved with displayText(). Text can be
|
||||
selected with setSelection() or selectAll(), and the selection can
|
||||
be cut(), copy()ied and paste()d. The text can be aligned with
|
||||
setAlignment().
|
||||
\section1 Constraining Text
|
||||
|
||||
When the text changes the textChanged() signal is emitted; when
|
||||
the text changes other than by calling setText() the textEdited()
|
||||
signal is emitted; when the cursor is moved the
|
||||
cursorPositionChanged() signal is emitted; and when the Return or
|
||||
Enter key is pressed the returnPressed() signal is emitted.
|
||||
Use \l maxLength to define the maximum permitted length of a text. You can
|
||||
use a \l inputMask and \l setValidator() to further constrain the text
|
||||
content.
|
||||
|
||||
When editing is finished, either because the line edit lost focus
|
||||
or Return/Enter is pressed the editingFinished() signal is
|
||||
emitted. Note that if focus is lost without any changes done,
|
||||
the editingFinished() signal won't be emitted.
|
||||
\section1 Editing Text
|
||||
|
||||
Note that if there is a validator set on the line edit, the
|
||||
returnPressed()/editingFinished() signals will only be emitted if
|
||||
the validator returns QValidator::Acceptable.
|
||||
You can change the text with setText() or insert(). Use text() to retrieve
|
||||
the text and displayText() to retrieve the displayed text (which may be
|
||||
different, see \l{EchoMode}). You can select the text with setSelection() or
|
||||
selectAll(), and you can cut(), copy(), and paste() the selection. To align
|
||||
the text, use setAlignment().
|
||||
|
||||
By default, QLineEdits have a frame as specified by platform
|
||||
style guides; you can turn it off by calling
|
||||
setFrame(false).
|
||||
When the text changes, the textChanged() signal is emitted. When the text
|
||||
changes in some other way than by calling setText(), the textEdited() signal
|
||||
is emitted. When the cursor is moved, the cursorPositionChanged() signal is
|
||||
emitted. And when the Return or Enter key is selected, the returnPressed()
|
||||
signal is emitted.
|
||||
|
||||
When text editing is finished, either because the line edit lost focus
|
||||
or Return/Enter was selected, the editingFinished() signal is emitted.
|
||||
|
||||
If the line edit focus is lost without any text changes, the
|
||||
editingFinished() signal won't be emitted.
|
||||
|
||||
If there is a validator set on the line edit, the
|
||||
returnPressed()/editingFinished() signals will only be emitted if the
|
||||
validator returns QValidator::Acceptable.
|
||||
|
||||
For more information on the many ways that QLineEdit can be used, see
|
||||
\l {Line Edits Example}, which also provides a selection of line edit
|
||||
examples that show the effects of various properties and validators on the
|
||||
input and output supplied by the user.
|
||||
|
||||
\section1 Setting a Frame
|
||||
|
||||
By default, QLineEdits have a frame as specified in the platform
|
||||
style guides. You can turn the frame off by calling setFrame(false).
|
||||
|
||||
\section1 Default Key Bindings
|
||||
|
||||
The table below describes the default key bindings.
|
||||
|
||||
\note The line edit also provides a context menu (usually invoked by a
|
||||
right-click) that presents some of the editing options listed below.
|
||||
|
||||
The default key bindings are described below. The line edit also
|
||||
provides a context menu (usually invoked by a right mouse click)
|
||||
that presents some of these editing options.
|
||||
\target desc
|
||||
\table
|
||||
\header \li Keypress \li Action
|
||||
\header \li Keystroke \li Action
|
||||
\row \li Left Arrow \li Moves the cursor one character to the left.
|
||||
\row \li Shift+Left Arrow \li Moves and selects text one character to the left.
|
||||
\row \li Right Arrow \li Moves the cursor one character to the right.
|
||||
@ -159,7 +170,7 @@ void QLineEdit::initStyleOption(QStyleOptionFrame *option) const
|
||||
\row \li Ctrl+Backspace \li Deletes the word to the left of the cursor.
|
||||
\row \li Delete \li Deletes the character to the right of the cursor.
|
||||
\row \li Ctrl+Delete \li Deletes the word to the right of the cursor.
|
||||
\row \li Ctrl+A \li Select all.
|
||||
\row \li Ctrl+A \li Selects all.
|
||||
\row \li Ctrl+C \li Copies the selected text to the clipboard.
|
||||
\row \li Ctrl+Insert \li Copies the selected text to the clipboard.
|
||||
\row \li Ctrl+K \li Deletes to the end of the line.
|
||||
@ -171,8 +182,8 @@ void QLineEdit::initStyleOption(QStyleOptionFrame *option) const
|
||||
\row \li Ctrl+Y \li Redoes the last undone operation.
|
||||
\endtable
|
||||
|
||||
Any other key sequence that represents a valid character, will
|
||||
cause the character to be inserted into the line edit.
|
||||
Any other keystroke that represents a valid character, will cause the
|
||||
character to be inserted into the line edit.
|
||||
|
||||
\sa QTextEdit, QLabel, QComboBox, {Line Edits Example}
|
||||
*/
|
||||
@ -230,13 +241,11 @@ QLineEdit::QLineEdit(QWidget* parent)
|
||||
}
|
||||
|
||||
/*!
|
||||
Constructs a line edit containing the text \a contents.
|
||||
Constructs a line edit containing the text \a contents as a child of
|
||||
\a parent.
|
||||
|
||||
The cursor position is set to the end of the line and the maximum
|
||||
text length to 32767 characters.
|
||||
|
||||
The \a parent and argument is sent to the QWidget
|
||||
constructor.
|
||||
The cursor position is set to the end of the line and the maximum text
|
||||
length to 32767 characters.
|
||||
|
||||
\sa text(), setMaxLength()
|
||||
*/
|
||||
@ -260,10 +269,10 @@ QLineEdit::~QLineEdit()
|
||||
|
||||
/*!
|
||||
\property QLineEdit::text
|
||||
\brief the line edit's text.
|
||||
\brief The line edit's text.
|
||||
|
||||
Setting this property clears the selection, clears the undo/redo
|
||||
history, moves the cursor to the end of the line and resets the
|
||||
history, moves the cursor to the end of the line, and resets the
|
||||
\l modified property to false. The text is not validated when
|
||||
inserted with setText().
|
||||
|
||||
@ -289,7 +298,7 @@ void QLineEdit::setText(const QString& text)
|
||||
\since 4.7
|
||||
|
||||
\property QLineEdit::placeholderText
|
||||
\brief the line edit's placeholder text.
|
||||
\brief The line edit's placeholder text.
|
||||
|
||||
Setting this property makes the line edit display a grayed-out
|
||||
placeholder text as long as the line edit is empty.
|
||||
@ -321,12 +330,12 @@ void QLineEdit::setPlaceholderText(const QString& placeholderText)
|
||||
|
||||
/*!
|
||||
\property QLineEdit::displayText
|
||||
\brief the displayed text.
|
||||
\brief The displayed text.
|
||||
|
||||
If \l echoMode is \l Normal this returns the same as text(); if
|
||||
\l EchoMode is \l Password or \l PasswordEchoOnEdit it returns a string of
|
||||
platform-dependent password mask characters text().length() in size,
|
||||
e.g. "******"; if \l EchoMode is \l NoEcho returns an empty string, "".
|
||||
If \l echoMode is \l Normal, this returns the same as text(). If
|
||||
\l EchoMode is \l Password or \l PasswordEchoOnEdit, it returns a string of
|
||||
platform-dependent password mask characters (e.g. "******"). If \l EchoMode
|
||||
is \l NoEcho, it returns an empty string.
|
||||
|
||||
By default, this property contains an empty string.
|
||||
|
||||
@ -342,12 +351,12 @@ QString QLineEdit::displayText() const
|
||||
|
||||
/*!
|
||||
\property QLineEdit::maxLength
|
||||
\brief the maximum permitted length of the text.
|
||||
\brief The maximum permitted length of the text.
|
||||
|
||||
If the text is too long, it is truncated at the limit.
|
||||
|
||||
If truncation occurs any selected text will be unselected, the
|
||||
cursor position is set to 0 and the first part of the string is
|
||||
If truncation occurs, any selected text will be unselected, the
|
||||
cursor position is set to 0, and the first part of the string is
|
||||
shown.
|
||||
|
||||
If the line edit has an input mask, the mask defines the maximum
|
||||
@ -372,10 +381,10 @@ void QLineEdit::setMaxLength(int maxLength)
|
||||
|
||||
/*!
|
||||
\property QLineEdit::frame
|
||||
\brief whether the line edit draws itself with a frame.
|
||||
\brief Whether the line edit draws itself with a frame.
|
||||
|
||||
If enabled (the default) the line edit draws itself inside a
|
||||
frame, otherwise the line edit draws itself without any frame.
|
||||
If enabled (the default), the line edit draws itself inside a
|
||||
frame. Otherwise, the line edit draws itself without any frame.
|
||||
*/
|
||||
bool QLineEdit::hasFrame() const
|
||||
{
|
||||
@ -435,9 +444,9 @@ QAction *QLineEdit::addAction(const QIcon &icon, ActionPosition position)
|
||||
\property QLineEdit::clearButtonEnabled
|
||||
\brief Whether the line edit displays a clear button when it is not empty.
|
||||
|
||||
If enabled, the line edit displays a trailing \e clear button when it contains
|
||||
some text, otherwise the line edit does not show a clear button (the
|
||||
default).
|
||||
If enabled, the line edit displays a trailing \uicontrol clear button when
|
||||
it contains some text. Otherwise, the line edit does not show a
|
||||
\uicontrol clear button (the default).
|
||||
|
||||
\sa addAction(), removeAction()
|
||||
\since 5.2
|
||||
@ -501,9 +510,8 @@ void QLineEdit::setFrame(bool enable)
|
||||
password should be kept secret.
|
||||
\value Password Display platform-dependent password mask characters instead
|
||||
of the characters actually entered.
|
||||
\value PasswordEchoOnEdit Display characters as they are entered
|
||||
while editing otherwise display characters as with
|
||||
\c Password.
|
||||
\value PasswordEchoOnEdit Display characters only while they are entered.
|
||||
Otherwise, display characters as with \c Password.
|
||||
|
||||
\sa setEchoMode(), echoMode()
|
||||
*/
|
||||
@ -511,13 +519,13 @@ void QLineEdit::setFrame(bool enable)
|
||||
|
||||
/*!
|
||||
\property QLineEdit::echoMode
|
||||
\brief the line edit's echo mode.
|
||||
\brief The line edit's echo mode.
|
||||
|
||||
The echo mode determines how the text entered in the line edit is
|
||||
displayed (or echoed) to the user.
|
||||
|
||||
The most common setting is \l Normal, in which the text entered by the
|
||||
user is displayed verbatim, but QLineEdit also supports modes that allow
|
||||
user is displayed verbatim. QLineEdit also supports modes that allow
|
||||
the entered text to be suppressed or obscured: these include \l NoEcho,
|
||||
\l Password and \l PasswordEchoOnEdit.
|
||||
|
||||
@ -574,15 +582,15 @@ const QValidator * QLineEdit::validator() const
|
||||
value during editing, but will be prevented from editing the text to a
|
||||
value that \a v validates as \l{QValidator::}{Invalid}.
|
||||
|
||||
This allows you to constrain the text that shall finally be entered when editing is
|
||||
done, while leaving users with enough freedom to edit the text from one valid state
|
||||
to another.
|
||||
This allows you to constrain the text that will be stored when editing is
|
||||
done while leaving users with enough freedom to edit the text from one valid
|
||||
state to another.
|
||||
|
||||
If \a v == 0, setValidator() removes the current input validator.
|
||||
The initial setting is to have no input validator (i.e. any input
|
||||
is accepted up to maxLength()).
|
||||
To remove the current input validator, pass \c nullptr. The initial setting
|
||||
is to have no input validator (any input is accepted up to maxLength()).
|
||||
|
||||
\sa validator(), hasAcceptableInput(), QIntValidator, QDoubleValidator, QRegularExpressionValidator
|
||||
\sa validator(), hasAcceptableInput(), QIntValidator, QDoubleValidator,
|
||||
QRegularExpressionValidator
|
||||
*/
|
||||
|
||||
void QLineEdit::setValidator(const QValidator *v)
|
||||
@ -604,8 +612,7 @@ void QLineEdit::setValidator(const QValidator *v)
|
||||
use the QSortFilterProxyModel to ensure that the QCompleter's model contains
|
||||
only valid entries.
|
||||
|
||||
If \a c == 0, setCompleter() removes the current completer, effectively
|
||||
disabling auto completion.
|
||||
To remove the completer and disable auto-completion, pass a \c nullptr.
|
||||
|
||||
\sa QCompleter
|
||||
*/
|
||||
@ -698,7 +705,7 @@ QSize QLineEdit::minimumSizeHint() const
|
||||
|
||||
/*!
|
||||
\property QLineEdit::cursorPosition
|
||||
\brief the current cursor position for this line edit.
|
||||
\brief The current cursor position for this line edit.
|
||||
|
||||
Setting the cursor position causes a repaint when appropriate.
|
||||
|
||||
@ -731,7 +738,7 @@ int QLineEdit::cursorPositionAt(const QPoint &pos)
|
||||
|
||||
/*!
|
||||
\property QLineEdit::alignment
|
||||
\brief the alignment of the line edit.
|
||||
\brief The alignment of the line edit.
|
||||
|
||||
Both horizontal and vertical alignment is allowed here, Qt::AlignJustify
|
||||
will map to Qt::AlignLeft.
|
||||
@ -756,9 +763,9 @@ void QLineEdit::setAlignment(Qt::Alignment alignment)
|
||||
|
||||
|
||||
/*!
|
||||
Moves the cursor forward \a steps characters. If \a mark is true
|
||||
each character moved over is added to the selection; if \a mark is
|
||||
false the selection is cleared.
|
||||
Moves the cursor forward \a steps characters. If \a mark is true,
|
||||
each character moved over is added to the selection. If \a mark is
|
||||
false, the selection is cleared.
|
||||
|
||||
\sa cursorBackward()
|
||||
*/
|
||||
@ -771,9 +778,9 @@ void QLineEdit::cursorForward(bool mark, int steps)
|
||||
|
||||
|
||||
/*!
|
||||
Moves the cursor back \a steps characters. If \a mark is true each
|
||||
character moved over is added to the selection; if \a mark is
|
||||
false the selection is cleared.
|
||||
Moves the cursor back \a steps characters. If \a mark is true, each
|
||||
character moved over is added to the selection. If \a mark is
|
||||
false, the selection is cleared.
|
||||
|
||||
\sa cursorForward()
|
||||
*/
|
||||
@ -810,9 +817,9 @@ void QLineEdit::cursorWordBackward(bool mark)
|
||||
|
||||
/*!
|
||||
If no text is selected, deletes the character to the left of the
|
||||
text cursor and moves the cursor one position to the left. If any
|
||||
text cursor, and moves the cursor one position to the left. If any
|
||||
text is selected, the cursor is moved to the beginning of the
|
||||
selected text and the selected text is deleted.
|
||||
selected text, and the selected text is deleted.
|
||||
|
||||
\sa del()
|
||||
*/
|
||||
@ -825,7 +832,7 @@ void QLineEdit::backspace()
|
||||
/*!
|
||||
If no text is selected, deletes the character to the right of the
|
||||
text cursor. If any text is selected, the cursor is moved to the
|
||||
beginning of the selected text and the selected text is deleted.
|
||||
beginning of the selected text, and the selected text is deleted.
|
||||
|
||||
\sa backspace()
|
||||
*/
|
||||
@ -839,7 +846,7 @@ void QLineEdit::del()
|
||||
/*!
|
||||
Moves the text cursor to the beginning of the line unless it is
|
||||
already there. If \a mark is true, text is selected towards the
|
||||
first position; otherwise, any selected text is unselected if the
|
||||
first position. Otherwise, any selected text is unselected if the
|
||||
cursor is moved.
|
||||
|
||||
\sa end()
|
||||
@ -854,7 +861,7 @@ void QLineEdit::home(bool mark)
|
||||
/*!
|
||||
Moves the text cursor to the end of the line unless it is already
|
||||
there. If \a mark is true, text is selected towards the last
|
||||
position; otherwise, any selected text is unselected if the cursor
|
||||
position. Otherwise, any selected text is unselected if the cursor
|
||||
is moved.
|
||||
|
||||
\sa home()
|
||||
@ -869,14 +876,14 @@ void QLineEdit::end(bool mark)
|
||||
|
||||
/*!
|
||||
\property QLineEdit::modified
|
||||
\brief whether the line edit's contents has been modified by the user.
|
||||
\brief Whether the line edit's contents has been modified by the user.
|
||||
|
||||
The modified flag is never read by QLineEdit; it has a default value
|
||||
of false and is changed to true whenever the user changes the line
|
||||
edit's contents.
|
||||
|
||||
This is useful for things that need to provide a default value but
|
||||
do not start out knowing what the default should be (perhaps it
|
||||
do not start out knowing what the default should be (for example, it
|
||||
depends on other fields on the form). Start the line edit without
|
||||
the best default, and when the default is known, if modified()
|
||||
returns \c false (the user hasn't entered any text), insert the
|
||||
@ -899,10 +906,10 @@ void QLineEdit::setModified(bool modified)
|
||||
|
||||
/*!
|
||||
\property QLineEdit::hasSelectedText
|
||||
\brief whether there is any text selected.
|
||||
\brief Whether there is any text selected.
|
||||
|
||||
hasSelectedText() returns \c true if some or all of the text has been
|
||||
selected by the user; otherwise returns \c false.
|
||||
selected by the user. Otherwise, it returns \c false.
|
||||
|
||||
By default, this property is \c false.
|
||||
|
||||
@ -918,9 +925,9 @@ bool QLineEdit::hasSelectedText() const
|
||||
|
||||
/*!
|
||||
\property QLineEdit::selectedText
|
||||
\brief the selected text.
|
||||
\brief The selected text.
|
||||
|
||||
If there is no selected text this property's value is
|
||||
If there is no selected text, this property's value is
|
||||
an empty string.
|
||||
|
||||
By default, this property contains an empty string.
|
||||
@ -936,7 +943,7 @@ QString QLineEdit::selectedText() const
|
||||
|
||||
/*!
|
||||
Returns the index of the first selected character in the
|
||||
line edit or -1 if no text is selected.
|
||||
line edit (or -1 if no text is selected).
|
||||
|
||||
\sa selectedText()
|
||||
\sa selectionEnd()
|
||||
@ -951,7 +958,7 @@ int QLineEdit::selectionStart() const
|
||||
|
||||
/*!
|
||||
Returns the index of the character directly after the selection
|
||||
in the line edit or -1 if no text is selected.
|
||||
in the line edit (or -1 if no text is selected).
|
||||
\since 5.10
|
||||
|
||||
\sa selectedText()
|
||||
@ -1005,7 +1012,7 @@ void QLineEdit::setSelection(int start, int length)
|
||||
|
||||
/*!
|
||||
\property QLineEdit::undoAvailable
|
||||
\brief whether undo is available.
|
||||
\brief Whether undo is available.
|
||||
|
||||
Undo becomes available once the user has modified the text in the line edit.
|
||||
|
||||
@ -1020,10 +1027,10 @@ bool QLineEdit::isUndoAvailable() const
|
||||
|
||||
/*!
|
||||
\property QLineEdit::redoAvailable
|
||||
\brief whether redo is available.
|
||||
\brief Whether redo is available.
|
||||
|
||||
Redo becomes available once the user has performed one or more undo operations
|
||||
on text in the line edit.
|
||||
on the text in the line edit.
|
||||
|
||||
By default, this property is \c false.
|
||||
*/
|
||||
@ -1036,7 +1043,7 @@ bool QLineEdit::isRedoAvailable() const
|
||||
|
||||
/*!
|
||||
\property QLineEdit::dragEnabled
|
||||
\brief whether the lineedit starts a drag if the user presses and
|
||||
\brief Whether the line edit starts a drag if the user presses and
|
||||
moves the mouse on some selected text.
|
||||
|
||||
Dragging is disabled by default.
|
||||
@ -1056,17 +1063,18 @@ void QLineEdit::setDragEnabled(bool b)
|
||||
|
||||
/*!
|
||||
\property QLineEdit::cursorMoveStyle
|
||||
\brief the movement style of cursor in this line edit.
|
||||
\brief The movement style of the cursor in this line edit.
|
||||
\since 4.8
|
||||
|
||||
When this property is set to Qt::VisualMoveStyle, the line edit will use visual
|
||||
movement style. Pressing the left arrow key will always cause the cursor to move
|
||||
left, regardless of the text's writing direction. The same behavior applies to
|
||||
right arrow key.
|
||||
When this property is set to Qt::VisualMoveStyle, the line edit will use a
|
||||
visual movement style. Using the left arrow key will always cause the
|
||||
cursor to move left, regardless of the text's writing direction. The same
|
||||
behavior applies to the right arrow key.
|
||||
|
||||
When the property is Qt::LogicalMoveStyle (the default), within a LTR text block,
|
||||
increase cursor position when pressing left arrow key, decrease cursor position
|
||||
when pressing the right arrow key. If the text block is right to left, the opposite
|
||||
When the property is set to Qt::LogicalMoveStyle (the default), within a
|
||||
left-to-right (LTR) text block, using the left arrow key will increase
|
||||
the cursor position, whereas using the right arrow key will decrease the
|
||||
cursor position. If the text block is right-to-left (RTL), the opposite
|
||||
behavior applies.
|
||||
*/
|
||||
|
||||
@ -1084,7 +1092,7 @@ void QLineEdit::setCursorMoveStyle(Qt::CursorMoveStyle style)
|
||||
|
||||
/*!
|
||||
\property QLineEdit::acceptableInput
|
||||
\brief whether the input satisfies the inputMask and the
|
||||
\brief Whether the input satisfies the inputMask and the
|
||||
validator.
|
||||
|
||||
By default, this property is \c true.
|
||||
@ -1098,11 +1106,11 @@ bool QLineEdit::hasAcceptableInput() const
|
||||
}
|
||||
|
||||
/*!
|
||||
\since 4.5
|
||||
Sets the margins around the text inside the frame to have the
|
||||
sizes \a left, \a top, \a right, and \a bottom.
|
||||
\since 4.5
|
||||
|
||||
See also textMargins().
|
||||
\sa textMargins()
|
||||
*/
|
||||
void QLineEdit::setTextMargins(int left, int top, int right, int bottom)
|
||||
{
|
||||
@ -1113,7 +1121,7 @@ void QLineEdit::setTextMargins(int left, int top, int right, int bottom)
|
||||
\since 4.6
|
||||
Sets the \a margins around the text inside the frame.
|
||||
|
||||
See also textMargins().
|
||||
\sa textMargins()
|
||||
*/
|
||||
void QLineEdit::setTextMargins(const QMargins &margins)
|
||||
{
|
||||
@ -1139,41 +1147,47 @@ QMargins QLineEdit::textMargins() const
|
||||
\property QLineEdit::inputMask
|
||||
\brief The validation input mask.
|
||||
|
||||
If no mask is set, inputMask() returns an empty string.
|
||||
|
||||
Sets the QLineEdit's validation mask. Validators can be used
|
||||
instead of, or in conjunction with masks; see setValidator().
|
||||
instead of, or in conjunction with masks; see setValidator(). The default is
|
||||
an empty string, which means that no input mask is used.
|
||||
|
||||
Unset the mask and return to normal QLineEdit operation by passing
|
||||
an empty string ("").
|
||||
To unset the mask and return to normal QLineEdit operation, pass an empty
|
||||
string.
|
||||
|
||||
The input mask is an input template string. It can contain the following elements:
|
||||
The input mask is an input template string. It can contain the following
|
||||
elements:
|
||||
\table
|
||||
\row \li Mask Characters \li Defines the \l {QChar::} {Category} of input characters
|
||||
that are considered valid in this position
|
||||
\row \li Meta Characters \li Various special meanings
|
||||
\row \li Separators \li All other characters are regarded as immutable separators
|
||||
\row \li Mask Characters \li Defines the \l {QChar::} {Category} of input
|
||||
characters that are considered valid in this position.
|
||||
\row \li Meta Characters \li Various special meanings (see details below).
|
||||
\row \li Separators \li All other characters are regarded as immutable
|
||||
separators.
|
||||
\endtable
|
||||
|
||||
The following table shows the mask and meta characters that can be used in an input mask.
|
||||
The following table shows the mask and meta characters that can be used in
|
||||
an input mask.
|
||||
|
||||
\table
|
||||
\header \li Mask Character \li Meaning
|
||||
\row \li \c A \li character of the Letter category required, such as A-Z, a-z.
|
||||
\row \li \c a \li character of the Letter category permitted but not required.
|
||||
\row \li \c N \li character of the Letter or Number category required, such as
|
||||
A-Z, a-z, 0-9.
|
||||
\row \li \c n \li character of the Letter or Number category permitted but not required.
|
||||
\row \li \c A \li Character of the Letter category required, such as A-Z,
|
||||
a-z.
|
||||
\row \li \c a \li Character of the Letter category permitted but not
|
||||
required.
|
||||
\row \li \c N \li Character of the Letter or Number category required, such
|
||||
as A-Z, a-z, 0-9.
|
||||
\row \li \c n \li Character of the Letter or Number category permitted but
|
||||
not required.
|
||||
\row \li \c X \li Any non-blank character required.
|
||||
\row \li \c x \li Any non-blank character permitted but not required.
|
||||
\row \li \c 9 \li character of the Number category required, e.g 0-9.
|
||||
\row \li \c 0 \li character of the Number category permitted but not required.
|
||||
\row \li \c D \li character of the Number category and larger than zero required,
|
||||
such as 1-9
|
||||
\row \li \c d \li character of the Number category and larger than zero permitted but not
|
||||
required, such as 1-9.
|
||||
\row \li \c # \li character of the Number category, or plus/minus sign permitted but not
|
||||
\row \li \c 9 \li Character of the Number category required, such as 0-9.
|
||||
\row \li \c 0 \li Character of the Number category permitted but not
|
||||
required.
|
||||
\row \li \c D \li Character of the Number category and larger than zero
|
||||
required, such as 1-9.
|
||||
\row \li \c d \li Character of the Number category and larger than zero
|
||||
permitted but not required, such as 1-9.
|
||||
\row \li \c # \li Character of the Number category, or plus/minus sign
|
||||
permitted but not required.
|
||||
\row \li \c H \li Hexadecimal character required. A-F, a-f, 0-9.
|
||||
\row \li \c h \li Hexadecimal character permitted but not required.
|
||||
\row \li \c B \li Binary character required. 0-1.
|
||||
@ -1182,11 +1196,11 @@ QMargins QLineEdit::textMargins() const
|
||||
\row \li \c > \li All following alphabetic characters are uppercased.
|
||||
\row \li \c < \li All following alphabetic characters are lowercased.
|
||||
\row \li \c ! \li Switch off case conversion.
|
||||
\row \li \c {;c} \li Terminates the input mask and sets the \e{blank} character to \e{c}.
|
||||
\row \li \c {;c} \li Terminates the input mask and sets the \e{blank}
|
||||
character to \e{c}.
|
||||
\row \li \c {[ ] { }} \li Reserved.
|
||||
\row \li \tt{\\} \li Use \tt{\\} to escape the special
|
||||
characters listed above to use them as
|
||||
separators.
|
||||
\row \li \tt{\\} \li Use \tt{\\} to escape the special characters listed
|
||||
above to use them as separators.
|
||||
\endtable
|
||||
|
||||
When created or cleared, the line edit will be filled with a copy of the
|
||||
@ -1199,7 +1213,7 @@ QMargins QLineEdit::textMargins() const
|
||||
unmodified content can be read using displayText().
|
||||
|
||||
The hasAcceptableInput() method returns false if the current content of the
|
||||
line edit does not fulfil the requirements of the input mask.
|
||||
line edit does not fulfill the requirements of the input mask.
|
||||
|
||||
Examples:
|
||||
\table
|
||||
@ -1230,8 +1244,10 @@ void QLineEdit::setInputMask(const QString &inputMask)
|
||||
}
|
||||
|
||||
/*!
|
||||
Selects all the text (i.e. highlights it) and moves the cursor to
|
||||
the end. This is useful when a default value has been inserted
|
||||
Selects all the text (highlights it) and moves the cursor to
|
||||
the end.
|
||||
|
||||
\note This is useful when a default value has been inserted
|
||||
because if the user types before clicking on the widget, the
|
||||
selected text will be deleted.
|
||||
|
||||
@ -1259,7 +1275,7 @@ void QLineEdit::deselect()
|
||||
|
||||
/*!
|
||||
Deletes any selected text, inserts \a newText, and validates the
|
||||
result. If it is valid, it sets it as the new contents of the line
|
||||
result. If it is valid, it sets the new text as the new contents of the line
|
||||
edit.
|
||||
|
||||
\sa setText(), clear()
|
||||
@ -1308,7 +1324,7 @@ void QLineEdit::redo()
|
||||
|
||||
/*!
|
||||
\property QLineEdit::readOnly
|
||||
\brief whether the line edit is read only.
|
||||
\brief Whether the line edit is read-only.
|
||||
|
||||
In read-only mode, the user can still copy the text to the
|
||||
clipboard, or drag and drop the text (if echoMode() is \l Normal),
|
||||
@ -1647,8 +1663,9 @@ void QLineEdit::mouseDoubleClickEvent(QMouseEvent* e)
|
||||
/*!
|
||||
\fn void QLineEdit::returnPressed()
|
||||
|
||||
This signal is emitted when the Return or Enter key is pressed.
|
||||
Note that if there is a validator() or inputMask() set on the line
|
||||
This signal is emitted when the Return or Enter key is used.
|
||||
|
||||
\note If there is a validator() or inputMask() set on the line
|
||||
edit, the returnPressed() signal will only be emitted if the input
|
||||
follows the inputMask() and the validator() returns
|
||||
QValidator::Acceptable.
|
||||
@ -1657,41 +1674,39 @@ void QLineEdit::mouseDoubleClickEvent(QMouseEvent* e)
|
||||
/*!
|
||||
\fn void QLineEdit::editingFinished()
|
||||
|
||||
This signal is emitted when the Return or Enter key is pressed, or
|
||||
if the line edit loses focus and its contents have changed since the
|
||||
last time this signal was emitted.
|
||||
This signal is emitted when the Return or Enter key is used, or if the line
|
||||
edit loses focus and its contents have changed since the last time this
|
||||
signal was emitted.
|
||||
|
||||
Note that if there is a validator() or
|
||||
inputMask() set on the line edit and enter/return is pressed, the
|
||||
editingFinished() signal will only be emitted if the input follows
|
||||
the inputMask() and the validator() returns QValidator::Acceptable.
|
||||
\note If there is a validator() or inputMask() set on the line edit and
|
||||
enter/return is used, the editingFinished() signal will only be emitted
|
||||
if the input follows the inputMask() and the validator() returns
|
||||
QValidator::Acceptable.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn void QLineEdit::inputRejected()
|
||||
\since 5.12
|
||||
|
||||
This signal is emitted when the user presses a key that is not
|
||||
considered to be acceptable input. For example, if a key press
|
||||
results in a validator's validate() call to return Invalid.
|
||||
Another case is when trying to enter in more characters beyond the
|
||||
maximum length of the line edit.
|
||||
This signal is emitted when the user uses a key that is not
|
||||
considered to be valid input. For example, if using a key results in a
|
||||
validator's \l {QValidator::validate()}{validate()} call to return
|
||||
\l {QValidator::Invalid}{Invalid}. Another case is when trying
|
||||
to enter more characters beyond the maximum length of the line edit.
|
||||
|
||||
Note: This signal will still be emitted in a case where part of
|
||||
the text is accepted but not all of it is. For example, if there
|
||||
is a maximum length set and the clipboard text is longer than the
|
||||
maximum length when it is pasted.
|
||||
\note This signal will still be emitted when only a part of the text is
|
||||
accepted. For example, if there is a maximum length set and the clipboard
|
||||
text is longer than the maximum length when it is pasted.
|
||||
*/
|
||||
|
||||
/*!
|
||||
Converts the given key press \a event into a line edit action.
|
||||
|
||||
If Return or Enter is pressed and the current text is valid (or
|
||||
If Return or Enter is used and the current text is valid (or
|
||||
can be \l{QValidator::fixup()}{made valid} by the
|
||||
validator), the signal returnPressed() is emitted.
|
||||
|
||||
The default key bindings are listed in the class's detailed
|
||||
description.
|
||||
\sa {Default Key Bindings}
|
||||
*/
|
||||
|
||||
void QLineEdit::keyPressEvent(QKeyEvent *event)
|
||||
@ -1759,7 +1774,7 @@ void QLineEdit::keyReleaseEvent(QKeyEvent *e)
|
||||
/*!
|
||||
\since 4.4
|
||||
|
||||
Returns a rectangle that includes the lineedit cursor.
|
||||
Returns a rectangle that includes the line edit cursor.
|
||||
*/
|
||||
QRect QLineEdit::cursorRect() const
|
||||
{
|
||||
@ -2163,10 +2178,10 @@ void QLineEdit::dropEvent(QDropEvent* e)
|
||||
createStandardContextMenu().
|
||||
|
||||
If you do not want the line edit to have a context menu, you can set
|
||||
its \l contextMenuPolicy to Qt::NoContextMenu. If you want to
|
||||
customize the context menu, reimplement this function. If you want
|
||||
to extend the standard context menu, reimplement this function, call
|
||||
createStandardContextMenu() and extend the menu returned.
|
||||
its \l contextMenuPolicy to Qt::NoContextMenu. To customize the context
|
||||
menu, reimplement this function. To extend the standard context menu,
|
||||
reimplement this function, call createStandardContextMenu(), and extend the
|
||||
menu returned.
|
||||
|
||||
\snippet code/src_gui_widgets_qlineedit.cpp 0
|
||||
|
||||
@ -2183,7 +2198,7 @@ void QLineEdit::contextMenuEvent(QContextMenuEvent *event)
|
||||
}
|
||||
}
|
||||
|
||||
/*! This function creates the standard context menu which is shown
|
||||
/*! Creates the standard context menu, which is shown
|
||||
when the user clicks on the line edit with the right mouse
|
||||
button. It is called from the default contextMenuEvent() handler.
|
||||
The popup menu's ownership is transferred to the caller.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user