14.1.  Input Masks

[ fromfile: validation.xml id: inputmask ]

An input mask is an active pattern that controls what can be typed into an input widget by the user. It can help to prevent certain types of incorrect data from being entered. Each QLineEdit has a QString property for storing a string of mask characters that can be applied to the data that is being typed into it. An inputMask can specify what kinds of characters are allowed in certain positions of a string that is being typed into a QLineEdit. The string consists of special, predefined mask characters and (optional) ordinary characters that occupy corresponding positions in the entered string.

The set of predefined mask characters consists of the following:

Table 14.1. Mask Characters

Character Required Character in That Position
A ASCII alphabetic character - uppercase or lowercase
N ASCII alphanumeric character - uppercase or lowercase
X ASCII any character
D ASCII nonzero digit
9 ASCII digit
H Hexadecimal digit
B Binary digit

Lowercase versions of the mask letters listed in Table 14.1 specify that the corresponding input characters are permitted in that position but not required. Using zero (0) instead of nine (9) indicates that an ASCII digit is permitted in that position but not required. # indicates that an ASCII digit or a plus (+) or a minus (–) is permitted in that position but not required. In addition, there are a few meta characters, shown in Table 14.2.

Table 14.2. Mask Meta Characters

Character Effect
> The following alphabetic characters are uppercased
< The following alphabetic characters are lowercased
! No further case conversion
\ Escape character

To demonstrate the use of the input mask, we present a short application that permits the user to specify the characters of the input mask and then see how the input is restricted.. Example 14.1 shows the class definition.

Example 14.1. src/validate/inputmask/masktestform.h

[ . . . . ]
class MaskTestForm : public QWidget {
   Q_OBJECT
public:
   MaskTestForm();
public slots:  
   void showResult();
   void installMask();
   void again();
private:
   QLineEdit* m_InputMask;
   QLineEdit* m_StringEntry;
   QLabel* m_Result;
   void setupForm();
};
[ . . . . ]

In Example 14.2 we implement the class.

Example 14.2. src/validate/inputmask/masktestform.cpp

[ . . . . ]
MaskTestForm::MaskTestForm(): m_InputMask(new QLineEdit), 
    m_StringEntry(new QLineEdit), m_Result(new QLabel) {
    setupForm();
    move(500, 500); 1
}
 
void MaskTestForm::setupForm() {
    setWindowTitle("Mask Test Demo");
    QPushButton* againButton = new QPushButton("Another Input Mask", this);
    QPushButton* quitButton = new QPushButton("Quit", this);
    QFormLayout *form = new QFormLayout(this);
    form->addRow("Mask String:", m_InputMask);
    form->addRow("Test Input: ", m_StringEntry);
    form->addRow("Result:", m_Result);
    connect(m_InputMask, SIGNAL(returnPressed()),
            this, SLOT(installMask()));
    connect(m_StringEntry, SIGNAL(returnPressed()),
            this, SLOT(showResult()));
[ . . . . ]
}
void MaskTestForm::installMask() {
    m_StringEntry->setInputMask(m_InputMask->text());
}
[ . . . . ]

1

Start in mid screen (approx).


Figure 14.1 shows a screenshot of the running application.

Figure 14.1.  Input Masks

Input Masks