[ 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:

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.

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.

[ . . . . ]
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.

[ . . . . ]
MaskTestForm::MaskTestForm(): m_InputMask(new QLineEdit), 
    m_StringEntry(new QLineEdit), m_Result(new QLabel) {
    setupForm();
    move(500, 500); 
}
 
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());
}
[ . . . . ]

Figure 14.1 shows a screenshot of the running application.

Figure 14.1.  Input Masks