QWizard Class

Member Function Documentation

[explicit] QWizard::QWizard(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())

Constructs a wizard with the given parent and window flags.

See also parent() and windowFlags().

[virtual noexcept] QWizard::~QWizard()

Destroys the wizard and its pages, releasing any allocated resources.

int QWizard::addPage(QWizardPage *page)

Adds the given page to the wizard, and returns the page's ID.

The ID is guaranteed to be larger than any other ID in the QWizard so far.

See also setPage(), page(), and pageAdded().

[slot] void QWizard::back()

Goes back to the previous page.

This is equivalent to pressing the Back button.

See also next(), accept(), reject(), and restart().

QAbstractButton *QWizard::button(QWizard::WizardButton which) const

Returns the button corresponding to role which.

See also setButton() and setButtonText().

QString QWizard::buttonText(QWizard::WizardButton which) const

Returns the text on button which.

If a text has ben set using setButtonText(), this text is returned.

By default, the text on buttons depends on the wizardStyle. For example, on macOS, the Next button is called Continue.

See also button(), setButton(), setButtonText(), QWizardPage::buttonText(), and QWizardPage::setButtonText().

[virtual protected] void QWizard::cleanupPage(int id)

This virtual function is called by QWizard to clean up page id just before the user leaves it by clicking Back (unless the QWizard::IndependentPages option is set).

The default implementation calls QWizardPage::cleanupPage() on page(id).

See also QWizardPage::cleanupPage() and initializePage().

[signal] void QWizard::currentIdChanged(int id)

This signal is emitted when the current page changes, with the new current id.

See also currentId() and currentPage().

QWizardPage *QWizard::currentPage() const

Returns a pointer to the current page, or nullptr if there is no current page (e.g., before the wizard is shown).

This is equivalent to calling page(currentId()).

See also page(), currentId(), and restart().

[signal] void QWizard::customButtonClicked(int which)

This signal is emitted when the user clicks a custom button. which can be CustomButton1, CustomButton2, or CustomButton3.

By default, no custom button is shown. Call setOption() with HaveCustomButton1, HaveCustomButton2, or HaveCustomButton3 to have one, and use setButtonText() or setButton() to configure it.

See also helpRequested().

[override virtual protected] void QWizard::done(int result)

Reimplements: QDialog::done(int r).

[override virtual protected] bool QWizard::event(QEvent *event)

Reimplements: QWidget::event(QEvent *event).

QVariant QWizard::field(const QString &name) const

Returns the value of the field called name.

This function can be used to access fields on any page of the wizard.

See also QWizardPage::registerField(), QWizardPage::field(), and setField().

bool QWizard::hasVisitedPage(int id) const

Returns true if the page history contains page id; otherwise, returns false.

Pressing Back marks the current page as "unvisited" again.

See also visitedIds().

[signal] void QWizard::helpRequested()

This signal is emitted when the user clicks the Help button.

By default, no Help button is shown. Call setOption(HaveHelpButton, true) to have one.

Example:

LicenseWizard::LicenseWizard(QWidget *parent)
    : QWizard(parent)
{
    ...
    setOption(HaveHelpButton, true);
    connect(this, &QWizard::helpRequested, this, &LicenseWizard::showHelp);
    ...
}

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.");
    }

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

}

See also customButtonClicked().

[virtual protected] void QWizard::initializePage(int id)

This virtual function is called by QWizard to prepare page id just before it is shown either as a result of QWizard::restart() being called, or as a result of the user clicking Next. (However, if the QWizard::IndependentPages option is set, this function is only called the first time the page is shown.)

By reimplementing this function, you can ensure that the page's fields are properly initialized based on fields from previous pages.

The default implementation calls QWizardPage::initializePage() on page(id).

See also QWizardPage::initializePage() and cleanupPage().

[override virtual protected] bool QWizard::nativeEvent(const QByteArray &eventType, void *message, qintptr *result)

Reimplements: QWidget::nativeEvent(const QByteArray &eventType, void *message, qintptr *result).

[slot] void QWizard::next()

Advances to the next page.

This is equivalent to pressing the Next or Commit button.

See also nextId(), back(), accept(), reject(), and restart().

[virtual] int QWizard::nextId() const

This virtual function is called by QWizard to find out which page to show when the user clicks the Next button.

The return value is the ID of the next page, or -1 if no page follows.

The default implementation calls QWizardPage::nextId() on the currentPage().

By reimplementing this function, you can specify a dynamic page order.

See also QWizardPage::nextId() and currentPage().

QWizardPage *QWizard::page(int id) const

Returns the page with the given id, or nullptr if there is no such page.

See also addPage() and setPage().

[signal] void QWizard::pageAdded(int id)

This signal is emitted whenever a page is added to the wizard. The page's id is passed as parameter.

See also addPage(), setPage(), and startId().

QList<int> QWizard::pageIds() const

Returns the list of page IDs.

[signal] void QWizard::pageRemoved(int id)

This signal is emitted whenever a page is removed from the wizard. The page's id is passed as parameter.

See also removePage() and startId().

[override virtual protected] void QWizard::paintEvent(QPaintEvent *event)

Reimplements: QWidget::paintEvent(QPaintEvent *event).

QPixmap QWizard::pixmap(QWizard::WizardPixmap which) const

Returns the pixmap set for role which.

By default, the only pixmap that is set is the BackgroundPixmap on macOS.

See also setPixmap(), QWizardPage::pixmap(), and Elements of a Wizard Page.

void QWizard::removePage(int id)

Removes the page with the given id. cleanupPage() will be called if necessary.

See also addPage(), setPage(), pageRemoved(), and startId().

[override virtual protected] void QWizard::resizeEvent(QResizeEvent *event)

Reimplements: QDialog::resizeEvent(QResizeEvent *).

[slot] void QWizard::restart()

Restarts the wizard at the start page. This function is called automatically when the wizard is shown.

See also startId().

void QWizard::setButton(QWizard::WizardButton which, QAbstractButton *button)

Sets the button corresponding to role which to button.

To add extra buttons to the wizard (e.g., a Print button), one way is to call setButton() with CustomButton1 to CustomButton3, and make the buttons visible using the HaveCustomButton1 to HaveCustomButton3 options.

See also button(), setButtonText(), setButtonLayout(), and options.

void QWizard::setButtonLayout(const QList<QWizard::WizardButton> &layout)

Sets the order in which buttons are displayed to layout, where layout is a list of WizardButtons.

The default layout depends on the options (e.g., whether HelpButtonOnRight) that are set. You can call this function if you need more control over the buttons' layout than what options already provides.

You can specify horizontal stretches in the layout using Stretch.

Example:

MyWizard::MyWizard(QWidget *parent)
    : QWizard(parent)
{
    ...
    QList<QWizard::WizardButton> layout;
    layout << QWizard::Stretch << QWizard::BackButton << QWizard::CancelButton
           << QWizard::NextButton << QWizard::FinishButton;
    setButtonLayout(layout);
    ...
}

See also setButton(), setButtonText(), and setOptions().

void QWizard::setButtonText(QWizard::WizardButton which, const QString &text)

Sets the text on button which to be text.

By default, the text on buttons depends on the wizardStyle. For example, on macOS, the Next button is called Continue.

To add extra buttons to the wizard (e.g., a Print button), one way is to call setButtonText() with CustomButton1, CustomButton2, or CustomButton3 to set their text, and make the buttons visible using the HaveCustomButton1, HaveCustomButton2, and/or HaveCustomButton3 options.

Button texts may also be set on a per-page basis using QWizardPage::setButtonText().

See also buttonText(), setButton(), button(), setButtonLayout(), setOptions(), and QWizardPage::setButtonText().

[slot] void QWizard::setCurrentId(int id)

Sets currentId to id, without visiting the pages between currentId and id.

Returns without page change, if

• wizard holds no pages
• current page is invalid
• given page equals currentId()
• given page is out of range

Note: If pages have been forward skipped and id is 0, page visiting history will be deleted

See also currentId().

void QWizard::setDefaultProperty(const char *className, const char *property, const char *changedSignal)

Sets the default property for className to be property, and the associated change signal to be changedSignal.

The default property is used when an instance of className (or of one of its subclasses) is passed to QWizardPage::registerField() and no property is specified.

QWizard knows the most common Qt widgets. For these (or their subclasses), you don't need to specify a property or a changedSignal. The table below lists these widgets:

See also QWizardPage::registerField().

void QWizard::setField(const QString &name, const QVariant &value)

Sets the value of the field called name to value.

This function can be used to set fields on any page of the wizard.

See also QWizardPage::registerField(), QWizardPage::setField(), and field().

void QWizard::setOption(QWizard::WizardOption option, bool on = true)

Sets the given option to be enabled if on is true; otherwise, clears the given option.

See also options, testOption(), and setWizardStyle().

void QWizard::setPage(int id, QWizardPage *page)

Adds the given page to the wizard with the given id.

See also addPage(), page(), and pageAdded().

void QWizard::setPixmap(QWizard::WizardPixmap which, const QPixmap &pixmap)

Sets the pixmap for role which to pixmap.

The pixmaps are used by QWizard when displaying a page. Which pixmaps are actually used depend on the wizard style.

Pixmaps can also be set for a specific page using QWizardPage::setPixmap().

See also pixmap(), QWizardPage::setPixmap(), and Elements of a Wizard Page.

void QWizard::setSideWidget(QWidget *widget)

Sets the given widget to be shown on the left side of the wizard. For styles which use the WatermarkPixmap (ClassicStyle and ModernStyle) the side widget is displayed on top of the watermark, for other styles or when the watermark is not provided the side widget is displayed on the left side of the wizard.

Passing nullptr shows no side widget.

When the widget is not nullptr the wizard reparents it.

Any previous side widget is hidden.

You may call setSideWidget() with the same widget at different times.

All widgets set here will be deleted by the wizard when it is destroyed unless you separately reparent the widget after setting some other side widget (or nullptr).

By default, no side widget is present.

See also sideWidget().

[override virtual] void QWizard::setVisible(bool visible)

Reimplements: QDialog::setVisible(bool visible).

QWidget *QWizard::sideWidget() const

Returns the widget on the left side of the wizard or nullptr.

By default, no side widget is present.

See also setSideWidget().

[override virtual] QSize QWizard::sizeHint() const

Reimplements: QDialog::sizeHint() const.

bool QWizard::testOption(QWizard::WizardOption option) const

Returns true if the given option is enabled; otherwise, returns false.

See also options, setOption(), and setWizardStyle().

[virtual] bool QWizard::validateCurrentPage()

This virtual function is called by QWizard when the user clicks Next or Finish to perform some last-minute validation. If it returns true, the next page is shown (or the wizard finishes); otherwise, the current page stays up.

The default implementation calls QWizardPage::validatePage() on the currentPage().

When possible, it is usually better style to disable the Next or Finish button (by specifying mandatory fields or by reimplementing QWizardPage::isComplete()) than to reimplement validateCurrentPage().

See also QWizardPage::validatePage() and currentPage().

QList<int> QWizard::visitedIds() const

Returns the list of IDs of visited pages, in the order in which the pages were visited.

See also hasVisitedPage().