1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Improve QLineEdit documentation

Browse Source 
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 2023-12-12 14:45:21 +02:00 committed by Qt Cherry-pick Bot
parent 2f96047a8c
commit d19037271c
1 changed files with 188 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

359
src/widgets/widgets/qlineedit.cpp
View File

@ -100,55 +100,66 @@ void QLineEdit::initStyleOption(QStyleOptionFrame *option) const
\image windows-lineedit.png \image windows-lineedit.png
A line edit allows the user to enter and edit a single line of A line edit allows users to enter and edit a single line of
plain text with a useful collection of editing functions, plain text with useful editing functions, including undo and redo, cut and
including undo and redo, cut and paste, and drag and drop (see paste, and drag and drop.
\l setDragEnabled()).
By changing the echoMode() of a line edit, it can also be used as 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 QTextEdit is a related class that allows multi-line, rich 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
editing. editing.
You can change the text with setText() or insert(). The text is \section1 Constraining Text
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().
When the text changes the textChanged() signal is emitted; when Use \l maxLength to define the maximum permitted length of a text. You can
the text changes other than by calling setText() the textEdited() use a \l inputMask and \l setValidator() to further constrain the text
signal is emitted; when the cursor is moved the content.
cursorPositionChanged() signal is emitted; and when the Return or
Enter key is pressed the returnPressed() signal is emitted.
When editing is finished, either because the line edit lost focus \section1 Editing Text
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.
Note that if there is a validator set on the line edit, the You can change the text with setText() or insert(). Use text() to retrieve
returnPressed()/editingFinished() signals will only be emitted if the text and displayText() to retrieve the displayed text (which may be
the validator returns QValidator::Acceptable. 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 When the text changes, the textChanged() signal is emitted. When the text
style guides; you can turn it off by calling changes in some other way than by calling setText(), the textEdited() signal
setFrame(false). 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 \target desc
\table \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 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 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. \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 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 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+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+C \li Copies the selected text to the clipboard.
\row \li Ctrl+Insert \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. \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. \row \li Ctrl+Y \li Redoes the last undone operation.
\endtable \endtable
Any other key sequence that represents a valid character, will Any other keystroke that represents a valid character, will cause the
cause the character to be inserted into the line edit. character to be inserted into the line edit.
\sa QTextEdit, QLabel, QComboBox, {Line Edits Example} \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 The cursor position is set to the end of the line and the maximum text
text length to 32767 characters. length to 32767 characters.
The \a parent and argument is sent to the QWidget
constructor.
\sa text(), setMaxLength() \sa text(), setMaxLength()
*/ */
@ -260,10 +269,10 @@ QLineEdit::~QLineEdit()
/*! /*!
\property QLineEdit::text \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 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 \l modified property to false. The text is not validated when
inserted with setText(). inserted with setText().
@ -289,7 +298,7 @@ void QLineEdit::setText(const QString& text)
\since 4.7 \since 4.7
\property QLineEdit::placeholderText \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 Setting this property makes the line edit display a grayed-out
placeholder text as long as the line edit is empty. placeholder text as long as the line edit is empty.
@ -321,12 +330,12 @@ void QLineEdit::setPlaceholderText(const QString& placeholderText)
/*! /*!
\property QLineEdit::displayText \property QLineEdit::displayText
\brief the displayed text. \brief The displayed text.
If \l echoMode is \l Normal this returns the same as text(); if 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 \l EchoMode is \l Password or \l PasswordEchoOnEdit, it returns a string of
platform-dependent password mask characters text().length() in size, platform-dependent password mask characters (e.g. "******"). If \l EchoMode
e.g. "******"; if \l EchoMode is \l NoEcho returns an empty string, "". is \l NoEcho, it returns an empty string.
By default, this property contains an empty string. By default, this property contains an empty string.
@ -342,12 +351,12 @@ QString QLineEdit::displayText() const
/*! /*!
\property QLineEdit::maxLength \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 the text is too long, it is truncated at the limit.
If truncation occurs any selected text will be unselected, the If truncation occurs, any selected text will be unselected, the
cursor position is set to 0 and the first part of the string is cursor position is set to 0, and the first part of the string is
shown. shown.
If the line edit has an input mask, the mask defines the maximum 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 \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 If enabled (the default), the line edit draws itself inside a
frame, otherwise the line edit draws itself without any frame. frame. Otherwise, the line edit draws itself without any frame.
*/ */
bool QLineEdit::hasFrame() const bool QLineEdit::hasFrame() const
{ {
@ -435,9 +444,9 @@ QAction *QLineEdit::addAction(const QIcon &icon, ActionPosition position)
\property QLineEdit::clearButtonEnabled \property QLineEdit::clearButtonEnabled
\brief Whether the line edit displays a clear button when it is not empty. \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 If enabled, the line edit displays a trailing \uicontrol clear button when
some text, otherwise the line edit does not show a clear button (the it contains some text. Otherwise, the line edit does not show a
default). \uicontrol clear button (the default).
\sa addAction(), removeAction() \sa addAction(), removeAction()
\since 5.2 \since 5.2
@ -501,9 +510,8 @@ void QLineEdit::setFrame(bool enable)
password should be kept secret. password should be kept secret.
\value Password Display platform-dependent password mask characters instead \value Password Display platform-dependent password mask characters instead
of the characters actually entered. of the characters actually entered.
\value PasswordEchoOnEdit Display characters as they are entered \value PasswordEchoOnEdit Display characters only while they are entered.
while editing otherwise display characters as with Otherwise, display characters as with \c Password.
\c Password.
\sa setEchoMode(), echoMode() \sa setEchoMode(), echoMode()
*/ */
@ -511,13 +519,13 @@ void QLineEdit::setFrame(bool enable)
/*! /*!
\property QLineEdit::echoMode \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 The echo mode determines how the text entered in the line edit is
displayed (or echoed) to the user. displayed (or echoed) to the user.
The most common setting is \l Normal, in which the text entered by the 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, the entered text to be suppressed or obscured: these include \l NoEcho,
\l Password and \l PasswordEchoOnEdit. \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 during editing, but will be prevented from editing the text to a
value that \a v validates as \l{QValidator::}{Invalid}. value that \a v validates as \l{QValidator::}{Invalid}.
This allows you to constrain the text that shall finally be entered when editing is 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 done while leaving users with enough freedom to edit the text from one valid
to another. state to another.
If \a v == 0, setValidator() removes the current input validator. To remove the current input validator, pass \c nullptr. The initial setting
The initial setting is to have no input validator (i.e. any input is to have no input validator (any input is accepted up to maxLength()).
is accepted up to maxLength()).
\sa validator(), hasAcceptableInput(), QIntValidator, QDoubleValidator, QRegularExpressionValidator \sa validator(), hasAcceptableInput(), QIntValidator, QDoubleValidator,
QRegularExpressionValidator
*/ */
void QLineEdit::setValidator(const QValidator *v) 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 use the QSortFilterProxyModel to ensure that the QCompleter's model contains
only valid entries. only valid entries.
If \a c == 0, setCompleter() removes the current completer, effectively To remove the completer and disable auto-completion, pass a \c nullptr.
disabling auto completion.
\sa QCompleter \sa QCompleter
*/ */
@ -698,7 +705,7 @@ QSize QLineEdit::minimumSizeHint() const
/*! /*!
\property QLineEdit::cursorPosition \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. Setting the cursor position causes a repaint when appropriate.
@ -731,7 +738,7 @@ int QLineEdit::cursorPositionAt(const QPoint &pos)
/*! /*!
\property QLineEdit::alignment \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 Both horizontal and vertical alignment is allowed here, Qt::AlignJustify
will map to Qt::AlignLeft. 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 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 each character moved over is added to the selection. If \a mark is
false the selection is cleared. false, the selection is cleared.
\sa cursorBackward() \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 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 character moved over is added to the selection. If \a mark is
false the selection is cleared. false, the selection is cleared.
\sa cursorForward() \sa cursorForward()
*/ */
@ -810,9 +817,9 @@ void QLineEdit::cursorWordBackward(bool mark)
/*! /*!
If no text is selected, deletes the character to the left of the 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 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() \sa del()
*/ */
@ -825,7 +832,7 @@ void QLineEdit::backspace()
/*! /*!
If no text is selected, deletes the character to the right of the 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 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() \sa backspace()
*/ */
@ -839,7 +846,7 @@ void QLineEdit::del()
/*! /*!
Moves the text cursor to the beginning of the line unless it is 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 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. cursor is moved.
\sa end() \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 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 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. is moved.
\sa home() \sa home()
@ -869,14 +876,14 @@ void QLineEdit::end(bool mark)
/*! /*!
\property QLineEdit::modified \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 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 of false and is changed to true whenever the user changes the line
edit's contents. edit's contents.
This is useful for things that need to provide a default value but 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 depends on other fields on the form). Start the line edit without
the best default, and when the default is known, if modified() the best default, and when the default is known, if modified()
returns \c false (the user hasn't entered any text), insert the returns \c false (the user hasn't entered any text), insert the
@ -899,10 +906,10 @@ void QLineEdit::setModified(bool modified)
/*! /*!
\property QLineEdit::hasSelectedText \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 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. By default, this property is \c false.
@ -918,9 +925,9 @@ bool QLineEdit::hasSelectedText() const
/*! /*!
\property QLineEdit::selectedText \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. an empty string.
By default, this property contains 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 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 selectedText()
\sa selectionEnd() \sa selectionEnd()
@ -951,7 +958,7 @@ int QLineEdit::selectionStart() const
/*! /*!
Returns the index of the character directly after the selection 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 \since 5.10
\sa selectedText() \sa selectedText()
@ -1005,7 +1012,7 @@ void QLineEdit::setSelection(int start, int length)
/*! /*!
\property QLineEdit::undoAvailable \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. 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 \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 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. By default, this property is \c false.
*/ */
@ -1036,7 +1043,7 @@ bool QLineEdit::isRedoAvailable() const
/*! /*!
\property QLineEdit::dragEnabled \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. moves the mouse on some selected text.
Dragging is disabled by default. Dragging is disabled by default.
@ -1056,17 +1063,18 @@ void QLineEdit::setDragEnabled(bool b)
/*! /*!
\property QLineEdit::cursorMoveStyle \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 \since 4.8
When this property is set to Qt::VisualMoveStyle, the line edit will use visual When this property is set to Qt::VisualMoveStyle, the line edit will use a
movement style. Pressing the left arrow key will always cause the cursor to move visual movement style. Using the left arrow key will always cause the
left, regardless of the text's writing direction. The same behavior applies to cursor to move left, regardless of the text's writing direction. The same
right arrow key. behavior applies to the right arrow key.
When the property is Qt::LogicalMoveStyle (the default), within a LTR text block, When the property is set to Qt::LogicalMoveStyle (the default), within a
increase cursor position when pressing left arrow key, decrease cursor position left-to-right (LTR) text block, using the left arrow key will increase
when pressing the right arrow key. If the text block is right to left, the opposite 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. behavior applies.
*/ */
@ -1084,7 +1092,7 @@ void QLineEdit::setCursorMoveStyle(Qt::CursorMoveStyle style)
/*! /*!
\property QLineEdit::acceptableInput \property QLineEdit::acceptableInput
\brief whether the input satisfies the inputMask and the \brief Whether the input satisfies the inputMask and the
validator. validator.
By default, this property is \c true. 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 Sets the margins around the text inside the frame to have the
sizes \a left, \a top, \a right, and \a bottom. 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) 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 \since 4.6
Sets the \a margins around the text inside the frame. Sets the \a margins around the text inside the frame.
See also textMargins(). \sa textMargins()
*/ */
void QLineEdit::setTextMargins(const QMargins &margins) void QLineEdit::setTextMargins(const QMargins &margins)
{ {
@ -1139,41 +1147,47 @@ QMargins QLineEdit::textMargins() const
\property QLineEdit::inputMask \property QLineEdit::inputMask
\brief The validation input mask. \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 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 To unset the mask and return to normal QLineEdit operation, pass an empty
an empty string (""). 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 \table
\row \li Mask Characters \li Defines the \l {QChar::} {Category} of input characters \row \li Mask Characters \li Defines the \l {QChar::} {Category} of input
that are considered valid in this position characters that are considered valid in this position.
\row \li Meta Characters \li Various special meanings \row \li Meta Characters \li Various special meanings (see details below).
\row \li Separators \li All other characters are regarded as immutable separators \row \li Separators \li All other characters are regarded as immutable
separators.
\endtable \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 \table
\header \li Mask Character \li Meaning \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 required, such as A-Z,
\row \li \c a \li character of the Letter category permitted but not required. a-z.
\row \li \c N \li character of the Letter or Number category required, such as \row \li \c a \li Character of the Letter category permitted but not
A-Z, a-z, 0-9. required.
\row \li \c n \li character of the Letter or Number 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 required.
\row \li \c x \li Any non-blank character permitted but not 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 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 0 \li Character of the Number category permitted but not
\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. 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 required. A-F, a-f, 0-9.
\row \li \c h \li Hexadecimal character permitted but not required. \row \li \c h \li Hexadecimal character permitted but not required.
\row \li \c B \li Binary character required. 0-1. \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 uppercased.
\row \li \c < \li All following alphabetic characters are lowercased. \row \li \c < \li All following alphabetic characters are lowercased.
\row \li \c ! \li Switch off case conversion. \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 \c {[ ] { }} \li Reserved.
\row \li \tt{\\} \li Use \tt{\\} to escape the special \row \li \tt{\\} \li Use \tt{\\} to escape the special characters listed
characters listed above to use them as above to use them as separators.
separators.
\endtable \endtable
When created or cleared, the line edit will be filled with a copy of the 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(). unmodified content can be read using displayText().
The hasAcceptableInput() method returns false if the current content of the 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: Examples:
\table \table
@ -1230,8 +1244,10 @@ void QLineEdit::setInputMask(const QString &inputMask)
} }
/*! /*!
Selects all the text (i.e. highlights it) and moves the cursor to Selects all the text (highlights it) and moves the cursor to
the end. This is useful when a default value has been inserted the end.
\note This is useful when a default value has been inserted
because if the user types before clicking on the widget, the because if the user types before clicking on the widget, the
selected text will be deleted. selected text will be deleted.
@ -1259,7 +1275,7 @@ void QLineEdit::deselect()
/*! /*!
Deletes any selected text, inserts \a newText, and validates the 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. edit.
\sa setText(), clear() \sa setText(), clear()
@ -1308,7 +1324,7 @@ void QLineEdit::redo()
/*! /*!
\property QLineEdit::readOnly \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 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), 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() \fn void QLineEdit::returnPressed()
This signal is emitted when the Return or Enter key is pressed. This signal is emitted when the Return or Enter key is used.
Note that if there is a validator() or inputMask() set on the line
\note If there is a validator() or inputMask() set on the line
edit, the returnPressed() signal will only be emitted if the input edit, the returnPressed() signal will only be emitted if the input
follows the inputMask() and the validator() returns follows the inputMask() and the validator() returns
QValidator::Acceptable. QValidator::Acceptable.
@ -1657,41 +1674,39 @@ void QLineEdit::mouseDoubleClickEvent(QMouseEvent* e)
/*! /*!
\fn void QLineEdit::editingFinished() \fn void QLineEdit::editingFinished()
This signal is emitted when the Return or Enter key is pressed, or This signal is emitted when the Return or Enter key is used, or if the line
if the line edit loses focus and its contents have changed since the edit loses focus and its contents have changed since the last time this
last time this signal was emitted. signal was emitted.
Note that if there is a validator() or \note If there is a validator() or inputMask() set on the line edit and
inputMask() set on the line edit and enter/return is pressed, the enter/return is used, the editingFinished() signal will only be emitted
editingFinished() signal will only be emitted if the input follows if the input follows the inputMask() and the validator() returns
the inputMask() and the validator() returns QValidator::Acceptable. QValidator::Acceptable.
*/ */
/*! /*!
\fn void QLineEdit::inputRejected() \fn void QLineEdit::inputRejected()
\since 5.12 \since 5.12
This signal is emitted when the user presses a key that is not This signal is emitted when the user uses a key that is not
considered to be acceptable input. For example, if a key press considered to be valid input. For example, if using a key results in a
results in a validator's validate() call to return Invalid. validator's \l {QValidator::validate()}{validate()} call to return
Another case is when trying to enter in more characters beyond the \l {QValidator::Invalid}{Invalid}. Another case is when trying
maximum length of the line edit. 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 \note This signal will still be emitted when only a part of the text is
the text is accepted but not all of it is. For example, if there accepted. For example, if there is a maximum length set and the clipboard
is a maximum length set and the clipboard text is longer than the text is longer than the maximum length when it is pasted.
maximum length when it is pasted.
*/ */
/*! /*!
Converts the given key press \a event into a line edit action. 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 can be \l{QValidator::fixup()}{made valid} by the
validator), the signal returnPressed() is emitted. validator), the signal returnPressed() is emitted.
The default key bindings are listed in the class's detailed \sa {Default Key Bindings}
description.
*/ */
void QLineEdit::keyPressEvent(QKeyEvent *event) void QLineEdit::keyPressEvent(QKeyEvent *event)
@ -2163,10 +2178,10 @@ void QLineEdit::dropEvent(QDropEvent* e)
createStandardContextMenu(). createStandardContextMenu().
If you do not want the line edit to have a context menu, you can set 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 its \l contextMenuPolicy to Qt::NoContextMenu. To customize the context
customize the context menu, reimplement this function. If you want menu, reimplement this function. To extend the standard context menu,
to extend the standard context menu, reimplement this function, call reimplement this function, call createStandardContextMenu(), and extend the
createStandardContextMenu() and extend the menu returned. menu returned.
\snippet code/src_gui_widgets_qlineedit.cpp 0 \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 when the user clicks on the line edit with the right mouse
button. It is called from the default contextMenuEvent() handler. button. It is called from the default contextMenuEvent() handler.
The popup menu's ownership is transferred to the caller. The popup menu's ownership is transferred to the caller.