Input Dialogs

For simple queries, Qt provides various template input dialogs, consisting of a suit-able input widget and two buttons, OK and Cancel. The relevant QInputDialog class has only ready-made static methods that we will now look at in more detail.

Frequently, you are put in the position of having to ask the user to enter a value. Qt distinguishes here between whole number values and floating-point values, which it provides in double precision.

Accepting Integer Input Values

The following example (Figure 6.13) shows how the getInteger() method of QIn-putDialog is used:

bool ok;

int alter = QInputDialog::getInteger (this, tr("Enter Age"), tr("Please enter year of birth"), 1982, 1850, QDate::currentDate().year(), 1, &ok);

if (ok) {

...

}

Figure 6.13:

QInputDialog::getIn-teger()with preset default value

The first two arguments of this are—as in other dialogs—a pointer to the parent widget and the heading of the dialog. Then getInteger() expects an explanatory text, which it displays above the input widget. This is followed by a default value and then the limits of the allowed input range. This example restricts the upper limit to the current year to avoid input that makes no sense (i.e., specifying a year of birth in the future). To do this we use QDate, a class for processing date details.

The currentDate() static method provides the system time according to the current date, and in turn, year() extracts the year from this and returns it as an integer value. Also, instead of inserting a static lower limit (1850), as is done here, this can be formed dynamically (e.g., with an expression such as QDate::currentDate().year() - 200).

In the next-to-last parameter, getInteger() asks for the amount by which the in-teger value should be increased or decreased if the user clicks on one of the two buttons to the right of the input field to increment or decrement the value (a so-calledspin box).

Since the return value provides no information on whether the user has canceled the dialog or has made a proper data entry, the method expects a pointer to a Boolean variable as the final parameter. If the user cancels the dialog, getInteger() stores the value false in the variable; otherwise, it is set to true.

Accepting Floating-point Numbers as Input Values

In the same way as with getInteger(), you can also prompt the user for real numbers with getDouble(). The dialog in the next example expects the price for a given product. getDouble() also expects the pointer to the parent widget, the dialog heading, and the description of the expected input as its first three parameters.

This is again followed by the default, minimum, and maximum values.

However, for the next-to-last parameter, there is a difference between getInteger() and getDouble(): The floating-point variant here expects the number of places after the decimal point (see Figure 6.14). We use two of them in this example, in order to specify a price.

Figure 6.14:

QInputDialog::getDouble() works here with only

two places after the decimal point.

Once again, you can find out whether the dialog completed normally or was in-terrupted by using an auxilliary variable, the address of which is passed as the last parameter:

double getPrice(const QString& product, bool *ok) {

return QInputDialog::getDouble(this, tr("Price"),

tr("Please enter a price for product ’%1.’").arg(product), 0, 0, 2147483647, 2, &ok);

}

The value 2147483647 is the maximum number here that an integer can display.

Reading in Strings

The most frequent use of QInputDialog is to allow the user to select a string from several predefined strings. For this purpose the static method getItem() is used (Figure 6.15): This expects a QStringList and displays its contents in a drop-down widget.

Figure 6.15:

QInputDialog::getItem() returns the selected string.

Again, the first three parameters specify the pointer to the parent widget, the head-ing, and the user query. This is followed by the list of strings to be displayed. Then comes the index of the list element that the drop-down widget displays at the be-ginning. The next-to-last parameter specifies whether the user can add his own entries to the list. If this is this case, the return value does not have to match one of the predefined entries. The final parameter, as before, is the address of a variable that indicates whether the user has terminated the dialog with OK or Cancel:

QStringList languages;

bool ok;

languages << "English" << "German" << "French" << "Spanish";

QString language = QInputDialog::getItem(this, tr("Select Language"), tr("Please select your language"), languages,

0, false, &ok);

if (ok) { ...

}

Reading in Free Text

Freely written texts are read in with the QInputDialog method getText(). The fol-lowing example introduces probably the most frequent usage of this type of user input: entering a password.

The first three parameters specify the details of the parent widget, dialog head-ing, and dialog text, and are followed by the display form, which is specified by

a value from the EchoMode enumerator of the QLineEdit input widget: QLine-Edit::NormalMode displays the text as it is entered; QLineEdit::NoEcho prints noth-ing at all, so that anybody watchnoth-ing cannot see how many characters getText() accepts; and the QInputDialog::Password value used here causes a placeholder to be printed for each character entered, usually stars or circular icons (Figure 6.16).

Figure 6.16:

QInputDialog::getText() in password mode

Since a default value is normally not specified for input of a password, we pass an empty QString object as the next-to-last parameter.

QString getPassword(const QString& resource) {

QString passwd = QInputDialog::getText(this, tr("Please Enter Password"), tr("Please enter a password for ’%1’").arg(resource),

QLineEdit::Password, QString(), 0);

}

Our final parameter in this example is a 0 (i.e., a null pointer) instead of a pointer to a bool variable, because in the case of the password it is sufficient to check the return value with QString::isEmpty() in order to see whether anything has been entered. Since these last two values match the default values for the fifth and sixth arguments of QInputDialog::getText(), you can shorten the method call in this case as follows:

QString getPassword(const QString& resource) {

QString passwd = QInputDialog::getText(this, tr("Please Enter Password"), tr("Please enter a password for ’%1’").arg(resource),

QLineEdit::Password);

}