QLineEdit: clarify the impact of using validators

Values that are validated as Intermediate are possible to enter, but
returnPressed and editingFinished signals are not emitted.

Fixes: QTBUG-82915
Change-Id: I3e194cd6ee93b3402090117b67044cf3663a232e
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

2 files changed, 19 insertions, 6 deletions

diff --git a/src/gui/util/qvalidator.cpp b/src/gui/util/qvalidator.cpp
index 54cbb28ffa..6e87faf534 100644
--- a/src/gui/util/qvalidator.cpp
+++ b/src/gui/util/qvalidator.cpp
@@ -370,8 +370,9 @@ QIntValidator::~QIntValidator()
     \fn QValidator::State QIntValidator::validate(QString &input, int &pos) const
 
     Returns \l Acceptable if the \a input is an integer within the
-    valid range, \l Intermediate if the \a input is a prefix of an integer in the
-    valid range, and \l Invalid otherwise.
+    valid range. If \a input has at most as many digits as the top of the range,
+    or is a prefix of an integer in the valid range, returns \l Intermediate.
+    Otherwise, returns \l Invalid.
 
     If the valid range consists of just positive integers (e.g., 32 to 100)
     and \a input is a negative integer, then Invalid is returned. (On the other
@@ -380,6 +381,10 @@ QIntValidator::~QIntValidator()
     the user might be just about to type the minus (especially for right-to-left
     languages).
 
+    Similarly, if the valid range is between 46 and 53, then 41 and 59 will be
+    evaluated as \l Intermediate, as otherwise the user wouldn't be able to
+    change a value from 49 to 51.
+
     \snippet code/src_gui_util_qvalidator.cpp 2
 
     By default, the \a pos parameter is not used by this validator.
diff --git a/src/widgets/widgets/qlineedit.cpp b/src/widgets/widgets/qlineedit.cpp
index c578710f99..401a62aff3 100644
--- a/src/widgets/widgets/qlineedit.cpp
+++ b/src/widgets/widgets/qlineedit.cpp
@@ -599,9 +599,17 @@ const QValidator * QLineEdit::validator() const
 }
 
 /*!
-    Sets this line edit to only accept input that the validator, \a v,
-    will accept. This allows you to place any arbitrary constraints on
-    the text which may be entered.
+    Sets the validator for values of line edit to \a v.
+
+    The line edit's returnPressed() and editingFinished() signals will only
+    be emitted if \a v validates the line edit's content as \l{QValidator::}{Acceptable}.
+    The user may change the content to any \l{QValidator::}{Intermediate}
+    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.
 
     If \a v == 0, setValidator() removes the current input validator.
     The initial setting is to have no input validator (i.e. any input
@@ -1439,7 +1447,7 @@ void QLineEdit::copy() const
     Inserts the clipboard's text at the cursor position, deleting any
     selected text, providing the line edit is not \l{QLineEdit::readOnly}{read-only}.
 
-    If the end result would not be acceptable to the current
+    If the end result would be invalid to the current
     \l{setValidator()}{validator}, nothing happens.
 
     \sa copy(), cut()