License Wizard Example▲

Screenshot of the License Wizard example

Most wizards have a linear structure, with page 1 followed by page 2 and so on until the last page. The Class Wizard example shows how to create such wizards.

Some wizards are more complex in that they allow different traversal paths based on the information provided by the user. The License Wizard example illustrates this. It provides five wizard pages; depending on which options are selected, the user can reach different pages.

The License Wizard pages

The example consists of the following classes:

  • LicenseWizard inherits QWizard and implements a non-linear five-page wizard that leads the user through the process of choosing a license agreement.

  • IntroPage, EvaluatePage, RegisterPage, DetailsPage, and ConclusionPage are QWizardPage subclasses that implement the wizard pages.

The LicenseWizard Class▲

The LicenseWizard class derives from QWizard and provides a five-page wizard that guides the user through the process of registering their copy of a fictitious software product. Here's the class definition:

 
Sélectionnez
class LicenseWizard : public QWizard
{
    Q_OBJECT

public:
    enum { Page_Intro, Page_Evaluate, Page_Register, Page_Details,
           Page_Conclusion };

    LicenseWizard(QWidget *parent = 0);

private slots:
    void showHelp();
};

The class's public API is limited to a constructor and an enum. The enum defines the IDs associated with the various pages:

Class name

Enum value

Page ID

IntroPage

Page_Intro

0

EvaluatePage

Page_Evaluate

1

RegisterPage

Page_Register

2

DetailsPage

Page_Details

3

ConclusionPage

Page_Conclusion

4

For this example, the IDs are arbitrary. The only constraints are that they must be unique and different from -1. IDs allow us to refer to pages.

 
Sélectionnez
LicenseWizard::LicenseWizard(QWidget *parent)
    : QWizard(parent)
{
    setPage(Page_Intro, new IntroPage);
    setPage(Page_Evaluate, new EvaluatePage);
    setPage(Page_Register, new RegisterPage);
    setPage(Page_Details, new DetailsPage);
    setPage(Page_Conclusion, new ConclusionPage);

    setStartId(Page_Intro);

In the constructor, we create the five pages, insert them into the wizard using QWizard::setPage(), and set Page_Intro to be the first page.

 
Sélectionnez
#ifndef Q_OS_MAC
    setWizardStyle(ModernStyle);
#endif

We set the style to ModernStyle on all platforms except macOS,

 
Sélectionnez
    setOption(HaveHelpButton, true);
    setPixmap(QWizard::LogoPixmap, QPixmap(":/images/logo.png"));

    connect(this, &QWizard::helpRequested, this, &LicenseWizard::showHelp);

    setWindowTitle(tr("License Wizard"));
}

We configure the QWizard to show a Help button, which is connected to our showHelp() slot. We also set the LogoPixmap for all pages that have a header (i.e., EvaluatePage, RegisterPage, and DetailsPage).

 
Sélectionnez
void LicenseWizard::showHelp()
{
    static QString lastHelpMessage;

    QString message;

    switch (currentId()) {
    case Page_Intro:
        message = tr("The decision you make here will affect which page you "
                     "get to see next.");
        break;
    ...
    default:
        message = tr("This help is likely not to be of any help.");
    }

    if (lastHelpMessage == message)
        message = tr("Sorry, I already gave what help I could. "
                     "Maybe you should try asking a human?");

    QMessageBox::information(this, tr("License Wizard Help"), message);

    lastHelpMessage = message;
}

In showHelp(), we display help texts that are appropriate for the current page. If the user clicks Help twice for the same page, we say, "Sorry, I already gave what help I could. Maybe you should try asking a human?"

The IntroPage Class▲

The pages are defined in licensewizard.h and implemented in licensewizard.cpp, together with LicenseWizard.

Here's the definition and implementation of IntroPage:

 
Sélectionnez
class IntroPage : public QWizardPage
{
    Q_OBJECT

public:
    IntroPage(QWidget *parent = 0);

    int nextId() const override;

private:
    QLabel *topLabel;
    QRadioButton *registerRadioButton;
    QRadioButton *evaluateRadioButton;
};

IntroPage::IntroPage(QWidget *parent)
    : QWizardPage(parent)
{
    setTitle(tr("Introduction"));
    setPixmap(QWizard::WatermarkPixmap, QPixmap(":/images/watermark.png"));

    topLabel = new QLabel(tr("This wizard will help you register your copy of "
                             "<i>Super Product One</i>™ or start "
                             "evaluating the product."));
    topLabel->setWordWrap(true);

    registerRadioButton = new QRadioButton(tr("&Register your copy"));
    evaluateRadioButton = new QRadioButton(tr("&Evaluate the product for 30 "
                                              "days"));
    registerRadioButton->setChecked(true);

    QVBoxLayout *layout = new QVBoxLayout;
    layout->addWidget(topLabel);
    layout->addWidget(registerRadioButton);
    layout->addWidget(evaluateRadioButton);
    setLayout(layout);
}

A page inherits from QWizardPage. We set a title and a watermark pixmap. By not setting any subTitle, we ensure that no header is displayed for this page. (On Windows, it is customary for wizards to display a watermark pixmap on the first and last pages, and to have a header on the other pages.)

 
Sélectionnez
int IntroPage::nextId() const
{
    if (evaluateRadioButton->isChecked()) {
        return LicenseWizard::Page_Evaluate;
    } else {
        return LicenseWizard::Page_Register;
    }
}

The nextId() function returns the ID for EvaluatePage if the Evaluate the product for 30 days option is checked; otherwise it returns the ID for RegisterPage.

The EvaluatePage Class▲

The EvaluatePage is slightly more involved:

 
Sélectionnez
class EvaluatePage : public QWizardPage
{
    Q_OBJECT

public:
    EvaluatePage(QWidget *parent = 0);

    int nextId() const override;

private:
    QLabel *nameLabel;
    QLabel *emailLabel;
    QLineEdit *nameLineEdit;
    QLineEdit *emailLineEdit;
};

EvaluatePage::EvaluatePage(QWidget *parent)
    : QWizardPage(parent)
{
    setTitle(tr("Evaluate <i>Super Product One</i>™"));
    setSubTitle(tr("Please fill both fields. Make sure to provide a valid "
                   "email address (e.g., john.smith@example.com)."));

    nameLabel = new QLabel(tr("N&ame:"));
    nameLineEdit = new QLineEdit;
    ...
    registerField("evaluate.name*", nameLineEdit);
    registerField("evaluate.email*", emailLineEdit);
    ...
}

First, we set the page's title and subTitle.

Then we create the child widgets, create wizard fields associated with them, and put them into layouts. The fields are created with an asterisk (*) next to their name. This makes them mandatory fields, that is, fields that must be filled before the user can press the Next button (Continue on macOS). The fields' values can be accessed from any other page using QWizardPage::field().

Resetting the page amounts to clearing the two text fields.

 
Sélectionnez
int EvaluatePage::nextId() const
{
    return LicenseWizard::Page_Conclusion;
}

The next page is always the ConclusionPage.

The ConclusionPage Class▲

The RegisterPage and DetailsPage are very similar to EvaluatePage. Let's go directly to the ConclusionPage:

 
Sélectionnez
class ConclusionPage : public QWizardPage
{
    Q_OBJECT

public:
    ConclusionPage(QWidget *parent = 0);

    void initializePage() override;
    int nextId() const override;
    void setVisible(bool visible) override;

private slots:
    void printButtonClicked();

private:
    QLabel *bottomLabel;
    QCheckBox *agreeCheckBox;
};

This time, we reimplement QWizardPage::initializePage() and QWidget::setVisible(), in addition to nextId(). We also declare a private slot: printButtonClicked().

 
Sélectionnez
int IntroPage::nextId() const
{
    if (evaluateRadioButton->isChecked()) {
        return LicenseWizard::Page_Evaluate;
    } else {
        return LicenseWizard::Page_Register;
    }
}