Doc: Improve explanation of QLineEdit input mask

The explanation of the input mask syntax and behavior was somewhat
unclear.

Task-number: QTBUG-76320
Change-Id: I45dc4a883c491d3dc08125b0f7efad46f2a9a33f
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>

1 files changed, 24 insertions, 9 deletions

diff --git a/src/widgets/widgets/qlineedit.cpp b/src/widgets/widgets/qlineedit.cpp
index fb67936768..658315028a 100644
--- a/src/widgets/widgets/qlineedit.cpp
+++ b/src/widgets/widgets/qlineedit.cpp
@@ -1198,12 +1198,18 @@ QMargins QLineEdit::textMargins() const
     Unset the mask and return to normal QLineEdit operation by passing
     an empty string ("").
 
-    The table below shows the characters that can be used in an input mask.
-    A space character, the default character for a blank, is needed for cases
-    where a character is \e{permitted but not required}.
+    The input mask is an input template string. It can contain the following elements:
+    \table
+    \row \li Mask Characters \li Defines the class 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
+    \endtable
+
+    The following table shows the mask and meta characters that can be used in an input mask.
 
     \table
-    \header \li Character \li Meaning
+    \header \li Mask Character \li Meaning
     \row \li \c A \li ASCII alphabetic character required. A-Z, a-z.
     \row \li \c a \li ASCII alphabetic character permitted but not required.
     \row \li \c N \li ASCII alphanumeric character required. A-Z, a-z, 0-9.
@@ -1219,19 +1225,28 @@ QMargins QLineEdit::textMargins() const
     \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 permitted but not required.
+    \header \li Meta Character \li Meaning
     \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 {[ ] { }} \li Reserved.
     \row \li \tt{\\} \li Use \tt{\\} to escape the special
                            characters listed above to use them as
                            separators.
     \endtable
 
-    The mask consists of a string of mask characters and separators,
-    optionally followed by a semicolon and the character used for
-    blanks. The blank characters are always removed from the text
-    after editing.
+    When created or cleared, the line edit will be filled with a copy of the
+    input mask string where the meta characters have been removed, and the mask
+    characters have been replaced with the \e{blank} character (by default, a
+    \c space).
+
+    When an input mask is set, the text() method returns a modified copy of the
+    line edit content where all the \e{blank} characters have been removed. The
+    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.
 
     Examples:
     \table
@@ -1240,7 +1255,7 @@ QMargins QLineEdit::textMargins() const
     \row \li \c HH:HH:HH:HH:HH:HH;_ \li MAC address
     \row \li \c 0000-00-00 \li ISO Date; blanks are \c space
     \row \li \c >AAAAA-AAAAA-AAAAA-AAAAA-AAAAA;# \li License number;
-    blanks are \c - and all (alphabetic) characters are converted to
+    blanks are \c{#} and all (alphabetic) characters are converted to
     uppercase.
     \endtable