QWizard Class Reference

 QWizardPage *createIntroPage()
 {
     QWizardPage *page = new QWizardPage;
     page->setTitle("Introduction");

     QLabel *label = new QLabel("This wizard will help you register your copy "
                                "of Super Product Two.");
     label->setWordWrap(true);

     QVBoxLayout *layout = new QVBoxLayout;
     layout->addWidget(label);
     page->setLayout(layout);

     return page;
 }

 QWizardPage *createRegistrationPage()
 {
     ...
 }

 QWizardPage *createConclusionPage()
 {
     ...
 }

 int main(int argc, char *argv[])
 {
     QApplication app(argc, argv);

     QString translatorFileName = QLatin1String("qt_");
     translatorFileName += QLocale::system().name();
     QTranslator *translator = new QTranslator(&app);
     if (translator->load(translatorFileName, QLibraryInfo::location(QLibraryInfo::TranslationsPath)))
         app.installTranslator(translator);

     QWizard wizard;
     wizard.addPage(createIntroPage());
     wizard.addPage(createRegistrationPage());
     wizard.addPage(createConclusionPage());

     wizard.setWindowTitle("Trivial Wizard");
 #ifdef Q_OS_SYMBIAN
     wizard.showMaximized();
 #else
     wizard.show();
 #endif

     return app.exec();
 }

         wizard()->setButtonText(QWizard::CustomButton1, tr("&Print"));
         wizard()->setOption(QWizard::HaveCustomButton1, true);
         connect(wizard(), SIGNAL(customButtonClicked(int)),
                 this, SLOT(printButtonClicked()));

 ClassInfoPage::ClassInfoPage(QWidget *parent)
     : QWizardPage(parent)
 {
     ...
     classNameLabel = new QLabel(tr("&Class name:"));
     classNameLineEdit = new QLineEdit;
     classNameLabel->setBuddy(classNameLineEdit);

     baseClassLabel = new QLabel(tr("B&ase class:"));
     baseClassLineEdit = new QLineEdit;
     baseClassLabel->setBuddy(baseClassLineEdit);

     qobjectMacroCheckBox = new QCheckBox(tr("Generate Q_OBJECT &macro"));

     registerField("className*", classNameLineEdit);
     registerField("baseClass", baseClassLineEdit);
     registerField("qobjectMacro", qobjectMacroCheckBox);
     ...
 }

 void OutputFilesPage::initializePage()
 {
     QString className = field("className").toString();
     headerLineEdit->setText(className.toLower() + ".h");
     implementationLineEdit->setText(className.toLower() + ".cpp");
     outputDirLineEdit->setText(QDir::convertSeparators(QDir::tempPath()));
 }

 ClassWizard::ClassWizard(QWidget *parent)
     : QWizard(parent)
 {
     addPage(new IntroPage);
     addPage(new ClassInfoPage);
     addPage(new CodeStylePage);
     addPage(new OutputFilesPage);
     addPage(new ConclusionPage);
     ...
 }

 class LicenseWizard : public QWizard
 {
     ...
     enum { Page_Intro, Page_Evaluate, Page_Register, Page_Details,
            Page_Conclusion };
     ...
 };

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

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

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

 int RegisterPage::nextId() const
 {
     if (upgradeKeyLineEdit->text().isEmpty()) {
         return LicenseWizard::Page_Details;
     } else {
         return LicenseWizard::Page_Conclusion;
     }
 }

 int DetailsPage::nextId() const
 {
     return LicenseWizard::Page_Conclusion;
 }

 int ConclusionPage::nextId() const
 {
     return -1;
 }

 int LicenseWizard::nextId() const
 {
     switch (currentId()) {
     case Page_Intro:
         if (field("intro.evaluate").toBool()) {
             return Page_Evaluate;
         } else {
             return Page_Register;
         }
     case Page_Evaluate:
         return Page_Conclusion;
     case Page_Register:
         if (field("register.upgradeKey").toString().isEmpty()) {
             return Page_Details;
         } else {
             return Page_Conclusion;
         }
     case Page_Details:
         return Page_Conclusion;
     case Page_Conclusion:
     default:
         return -1;
     }
 }

 void ConclusionPage::initializePage()
 {
     QString licenseText;

     if (wizard()->hasVisitedPage(LicenseWizard::Page_Evaluate)) {
         licenseText = tr("<u>Evaluation License Agreement:</u> "
                          "You can use this software for 30 days and make one "
                          "backup, but you are not allowed to distribute it.");
     } else if (wizard()->hasVisitedPage(LicenseWizard::Page_Details)) {
         licenseText = tr("<u>First-Time License Agreement:</u> "
                          "You can use this software subject to the license "
                          "you will receive by email.");
     } else {
         licenseText = tr("<u>Upgrade License Agreement:</u> "
                          "This software is licensed under the terms of your "
                          "current license.");
     }
     bottomLabel->setText(licenseText);
 }

Member Function Documentation

QWizard::QWizard ( QWidget * parent = 0, Qt::WindowFlags flags = 0 )

Constructs a wizard with the given parent and window flags.

See also parent() and windowFlags().

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().

void QWizard::back () [slot]

Goes back to the previous page.

This is equivalent to pressing the Back button.

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

QAbstractButton * QWizard::button ( WizardButton which ) const

Returns the button corresponding to role which.

See also setButton() and setButtonText().

QString QWizard::buttonText ( 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 Mac OS X, the Next button is called Continue.

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

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

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().

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

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 0 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().

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

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().

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

Reimplemented from QDialog::done().

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

Reimplemented from QObject::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 visitedPages().

void QWizard::helpRequested () [signal]

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, SIGNAL(helpRequested()), this, SLOT(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().

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

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().

void QWizard::next () [slot]

Advances to the next page.

This is equivalent to pressing the Next or Commit button.

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

int QWizard::nextId () const [virtual]

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 0 if there is no such page.

See also addPage() and setPage().

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

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

This function was introduced in Qt 4.7.

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

QList<int> QWizard::pageIds () const

Returns the list of page IDs.

This function was introduced in Qt 4.5.

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

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

This function was introduced in Qt 4.7.

See also removePage() and startId().

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

Reimplemented from QWidget::paintEvent().

QPixmap QWizard::pixmap ( WizardPixmap which ) const

Returns the pixmap set for role which.

By default, the only pixmap that is set is the BackgroundPixmap on Mac OS X.

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.

Note: Removing a page may influence the value of the startId property.

This function was introduced in Qt 4.5.

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

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

Reimplemented from QWidget::resizeEvent().

void QWizard::restart () [slot]

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

See also startId().

void QWizard::setButton ( 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<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 ( 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 Mac OS X, 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().

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:

Widget	Property	Change Notification Signal
QAbstractButton	bool checked	toggled()
QAbstractSlider	int value	valueChanged()
QComboBox	int currentIndex	currentIndexChanged()
QDateTimeEdit	QDateTime dateTime	dateTimeChanged()
QLineEdit	QString text	textChanged()
QListWidget	int currentRow	currentRowChanged()
QSpinBox	int value	valueChanged()

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 ( 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.

Note: Adding a page may influence the value of the startId property in case it was not set explicitly.

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

void QWizard::setPixmap ( 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 0 shows no side widget.

When the widget is not 0 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 0).

By default, no side widget is present.

This function was introduced in Qt 4.7.

See also sideWidget().

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

Reimplemented from QWidget::setVisible().

QWidget * QWizard::sideWidget () const

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

By default, no side widget is present.

This function was introduced in Qt 4.7.

See also setSideWidget().

QSize QWizard::sizeHint () const [virtual]

Reimplemented from QWidget::sizeHint().

bool QWizard::testOption ( WizardOption option ) const

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

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

bool QWizard::validateCurrentPage () [virtual]

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::visitedPages () const

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

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

See also hasVisitedPage().

bool QWizard::winEvent ( MSG * message, long * result ) [virtual protected]

Reimplemented from QWidget::winEvent().