input masks and validators
Shows how to apply an input mask or validator to a QLineEdit widget to constrain accepted input values.
By default, QLineEdit widgets let the user enter anything. Sometimes there is a good reason to restrict the input choices though, for instance when the application expects the user to enter a date with a specific pattern, a user-name with specific boundaries and allowed characters, an IP address or similar. This unit explains two features that the QLineEdit class provides that can be used to impose such input constrains.
Also note, that when an input mask or a validator is set on a line edit, they will only emit the editingFinished() and returnPressed() signals when the input value fully matches the input mask or validator, but not while the value is only partial or empty.
- QValidator: Used with QLineEdits and QSpinBoxes to impose constraints. Custom validators can be implemented by inheriting from this class. It provides three states of input values based: Acceptable, Intermediate and Invalid. These are returned when calling it’s validate() method. Acceptable is returned when the input value is considered complete and valid. Intermediate is returned when the input is partial, but can be extended to acceptable values. For example if the input accepts values between 100 and 200, then 10 is a intermediate value, as it can be made valid by simply adding another zero to it. Invalid state is returned when the input value is clearly invalid and cannot be extended to a valid value. In the above example that would be the non digit values like “abc”.
- QIntValidator: Inherits QValidator and checks input to be between the minimum and maximum boundary. It’s commonly used with the QSpinBox widget, but can also be used with line edits.
- QDoubleValidator: Also inherits the QValidator class and acts the same as the int validator, but validates floating point numbers.
- QRegExpValidator: Another validator class. This decides upon the input value’s validity based on a regular expression it has been set up with.
- QRegExp: A regular expression. Qt uses a syntax that is very similar to Perl regular expressions.
- QLocale: Declares a locale (language and country). This has multiple uses. In this unit a locale is applied to the QDoubleValidator. This has an impact on the values that are considered valid. For example in the United States, decimals and fractions are separated with a point while in Germany they are separated with a comma. So depending on which locale is set, the validator returns different states for the same value. If not set, this is read from the system settings.
- QSpacerItem: Connected to the Qt layout system. This is a placeholder that either takes up a fixed amount of horizontal and vertical space or has a size policy to expand when the widget the layout is applied to is resized.
The example application consists of two widgets, one of which is shown exclusively at any time. The two widgets are the InputMaskDemo and the ValidatorDemo widget that are implemented in separate source files. The main creates instances of these, puts them in a vertical layout with two radio buttons at the top that switch the visibility of the demo widgets. The main window also has a spacer item at the bottom, which takes up all free space when the main window is resized, instead of stretching the other widgets.
The first demo widget has a line edit followed by a set of radio buttons that apply an input mask to the line edit. This is followed by a a maximum length input field that shows and sets the maximum allowed characters in the line edit. At the bottom this widget has two signal indicators copied over from the last unit. These monitor the editingFinished() and returnPressed() signals.
When the input mask selection changes, the new mask is applied to the line edit. This also updates the maximum length field, which reflects the number of characters in the input mask. The masks in the example application contain ISO date format only accepting a number based date input, a MAC address that accepts hexadecimal values, a postal code that takes five numbers from one to nine and a fixed mask that sets a constant value and does not let the user change it as it lacks wild-cards.
When removing the input mask from the line edit with the “No Mask” selection, the maximum length of the line edit is reset to the default value, which is 32767 characters.
The maximum length attribute can only be changed with the setMaxLength() method when no mask is applied. If the line edit already has a value that is longer than the new maximum length, it will truncate the content to the new maximum length.
The two signal monitors are connected to the line edit at the top. When no mask is applied, they trigger the same as explained in the last unit. However, if a mask is applied, they only trigger when the input value satisfies the input mask pattern.
The validator demo widget is very similar to the input mask demo widget, with the difference that the radio buttons apply a validator to the line edit instead of an input mask.
There are three basic validators that all inherit the QValidator abstract base class. One for integer values, one for floating point values and one for regular expressions. These also put a constraint on the input values the line edit allows, for example a QIntValidator will not allow letters or non-number punctuation like exclamation marks. It will also not allow more digits than the maximum value has.
The second and third validators are both QDoubleValidators that put a floating point constraint on the line edit and act similar to the integer validator. However, because floating point numbers can have a decimal separator, the system local influences which values are accepted as valid. For example the US locale will accept a point as separator while the DE (German) locale will only accept comma.
The fourth validator is the regular expression validator. Regular expressions can describe a multitude of simple and complex patterns. These are not explained in detail here. More information on regular expressions can be obtained with a web-search for “perl regular expressions”.
Validators are different from input masks in that they don’t set the maximum length of the line edit when applied or removed. The maximum length is still applied to the line edit in addition to the validator.
This is the first unit in which I don’t list all the code in the unit text, only explain it’s structure and working. The reason for this is, that the example application contains a lot of boilerplate code that would make the text long but not insightful. To gain a more detailed insight into what the source code does, it can be downloaded from the link in the header of this article.
This unit moved on with introducing the QLineEdit widget and showed a few of it’s specialty features. This widget is scrutinized more in detail because it’s such a common component of most applications.