CopperSpice API  1.8.2
QWizard Class Reference

Provides support for wizards. More...

Inheritance diagram for QWizard:
QDialog QWidget QObject QPaintDevice

Public Typedefs

using WizardOptions = QFlags< WizardOption >
- Public Typedefs inherited from QWidget
using RenderFlags = QFlags< RenderFlag >

Public Types

enum  WizardButton
enum  WizardOption
enum  WizardPixmap
enum  WizardStyle
- Public Types inherited from QDialog
enum  DialogCode
- Public Types inherited from QWidget
enum  RenderFlag
- Public Types inherited from QPaintDevice
enum  PaintDeviceMetric

Public Signals

void currentIdChanged (int id)
void customButtonClicked (int which)
void helpRequested ()
void pageAdded (int id)
void pageRemoved (int id)
- Public Signals inherited from QDialog
void accepted ()
void finished (int result)
void rejected ()
- Public Signals inherited from QWidget
void customContextMenuRequested (const QPoint &pos)
void windowIconChanged (const QIcon &icon)
void windowIconTextChanged (const QString &iconText)
void windowTitleChanged (const QString &title)
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
void objectNameChanged (const QString &objectName)

Public Slots

void back ()
void next ()
void restart ()
- Public Slots inherited from QDialog
virtual void accept ()
virtual void done (int result)
virtual int exec ()
virtual void open ()
virtual void reject ()
void showExtension (bool showExt)
- Public Slots inherited from QWidget
bool close ()
void hide ()
void lower ()
void raise ()
void repaint ()
void setDisabled (bool disable)
void setEnabled (bool enable)
void setFocus ()
void setHidden (bool hidden)
void setStyleSheet (const QString &styleSheet)
virtual void setVisible (bool visible)
void setWindowModified (bool modified)
void setWindowTitle (const QString &title)
void show ()
void showFullScreen ()
void showMaximized ()
void showMinimized ()
void showNormal ()
void update ()
- Public Slots inherited from QObject
void deleteLater ()

Public Methods

 QWizard (QWidget *parent=nullptr, Qt::WindowFlags flags=Qt::EmptyFlag)
 ~QWizard ()
int addPage (QWizardPage *page)
QAbstractButtonbutton (WizardButton which) const
QString buttonText (WizardButton which) const
int currentId () const
QWizardPagecurrentPage () const
QVariant field (const QString &name) const
bool hasVisitedPage (int id) const
virtual int nextId () const
WizardOptions options () const
QWizardPagepage (int id) const
QList< int > pageIds () const
QPixmap pixmap (WizardPixmap which) const
void removePage (int id)
void setButton (WizardButton which, QAbstractButton *button)
void setButtonLayout (const QList< WizardButton > &layout)
void setButtonText (WizardButton which, const QString &text)
void setDefaultProperty (const QString &className, const QString &property, const QString &changedSignal)
void setField (const QString &name, const QVariant &value)
void setOption (WizardOption option, bool on=true)
void setOptions (WizardOptions options)
void setPage (int id, QWizardPage *page)
void setPixmap (WizardPixmap which, const QPixmap &pixmap)
void setSideWidget (QWidget *widget)
void setStartId (int id)
void setSubTitleFormat (Qt::TextFormat format)
void setTitleFormat (Qt::TextFormat format)
void setVisible (bool visible) override
void setWizardStyle (WizardStyle style)
QWidgetsideWidget () const
QSize sizeHint () const override
int startId () const
Qt::TextFormat subTitleFormat () const
bool testOption (WizardOption option) const
Qt::TextFormat titleFormat () const
virtual bool validateCurrentPage ()
QList< int > visitedPages () const
WizardStyle wizardStyle () const
- Public Methods inherited from QDialog
 QDialog (QWidget *parent=nullptr, Qt::WindowFlags flags=Qt::EmptyFlag)
 ~QDialog ()
QWidgetextension () const
bool isSizeGripEnabled () const
QSize minimumSizeHint () const override
Qt::Orientation orientation () const
int result () const
void setExtension (QWidget *extension)
void setModal (bool modal)
void setOrientation (Qt::Orientation orientation)
void setResult (int result)
void setSizeGripEnabled (bool enabled)
void setVisible (bool visible) override
- Public Methods inherited from QWidget
 QWidget (QWidget *parent=nullptr, Qt::WindowFlags flags=Qt::EmptyFlag)
 ~QWidget ()
bool acceptDrops () const
QString accessibleDescription () const
QString accessibleName () const
QList< QAction * > actions () const
void activateWindow ()
void addAction (QAction *action)
void addActions (const QList< QAction * > &actions)
void adjustSize ()
bool autoFillBackground () const
QPalette::ColorRole backgroundRole () const
QBackingStorebackingStore () const
QSize baseSize () const
QWidget * childAt (const QPoint &position) const
QWidget * childAt (int x, int y) const
QRect childrenRect () const
QRegion childrenRegion () const
void clearFocus ()
void clearMask ()
QMargins contentsMargins () const
QRect contentsRect () const
Qt::ContextMenuPolicy contextMenuPolicy () const
QCursor cursor () const
WId effectiveWinId () const
void ensurePolished () const
Qt::FocusPolicy focusPolicy () const
QWidget * focusProxy () const
QWidget * focusWidget () const
const QFontfont () const
QFontInfo fontInfo () const
QFontMetrics fontMetrics () const
QPalette::ColorRole foregroundRole () const
QRect frameGeometry () const
QSize frameSize () const
const QRectgeometry () const
void getContentsMargins (int *left, int *top, int *right, int *bottom) const
QPixmap grab (const QRect &rectangle=QRect (QPoint (0, 0), QSize (-1,-1)))
void grabGesture (Qt::GestureType gestureType, Qt::GestureFlags flags=Qt::GestureFlags ())
void grabKeyboard ()
void grabMouse ()
void grabMouse (const QCursor &cursor)
int grabShortcut (const QKeySequence &key, Qt::ShortcutContext context=Qt::WindowShortcut)
QGraphicsEffectgraphicsEffect () const
QGraphicsProxyWidgetgraphicsProxyWidget () const
bool hasEditFocus () const
bool hasFocus () const
virtual bool hasHeightForWidth () const
bool hasMouseTracking () const
int height () const
virtual int heightForWidth (int width) const
Qt::InputMethodHints inputMethodHints () const
virtual QVariant inputMethodQuery (Qt::InputMethodQuery query) const
void insertAction (QAction *before, QAction *action)
void insertActions (QAction *before, QList< QAction * > actions)
bool isActiveWindow () const
bool isAncestorOf (const QWidget *child) const
bool isEnabled () const
bool isEnabledTo (const QWidget *parent) const
bool isEnabledToTLW () const
bool isFullScreen () const
bool isHidden () const
bool isMaximized () const
bool isMinimized () const
bool isModal () const
bool isTopLevel () const
bool isVisible () const
bool isVisibleTo (const QWidget *parent) const
bool isWindow () const
bool isWindowModified () const
QLayoutlayout () const
Qt::LayoutDirection layoutDirection () const
QLocale locale () const
QPoint mapFrom (const QWidget *parent, const QPoint &pos) const
QPoint mapFromGlobal (const QPoint &pos) const
QPoint mapFromParent (const QPoint &pos) const
QPoint mapTo (const QWidget *parent, const QPoint &pos) const
QPoint mapToGlobal (const QPoint &pos) const
QPoint mapToParent (const QPoint &pos) const
QRegion mask () const
int maximumHeight () const
QSize maximumSize () const
int maximumWidth () const
int minimumHeight () const
QSize minimumSize () const
int minimumWidth () const
void move (const QPoint &point)
void move (int x, int y)
QWidget * nativeParentWidget () const
QWidget * nextInFocusChain () const
QRect normalGeometry () const
void overrideWindowFlags (Qt::WindowFlags flags)
QPaintEnginepaintEngine () const override
const QPalettepalette () const
QWidget * parentWidget () const
QPoint pos () const
QWidget * previousInFocusChain () const
QRect rect () const
void releaseKeyboard ()
void releaseMouse ()
void releaseShortcut (int id)
void removeAction (QAction *action)
void render (QPaintDevice *target, const QPoint &targetOffset=QPoint (), const QRegion &sourceRegion=QRegion (), RenderFlags renderFlags=RenderFlags (DrawWindowBackground|DrawChildren))
void render (QPainter *painter, const QPoint &targetOffset=QPoint (), const QRegion &sourceRegion=QRegion (), RenderFlags renderFlags=RenderFlags (DrawWindowBackground|DrawChildren))
void repaint (const QRect &rect)
void repaint (const QRegion &region)
void repaint (int x, int y, int w, int h)
void resize (const QSize &size)
void resize (int w, int h)
bool restoreGeometry (const QByteArray &geometry)
QByteArray saveGeometry () const
void scroll (int dx, int dy)
void scroll (int dx, int dy, const QRect &rect)
void setAcceptDrops (bool on)
void setAccessibleDescription (const QString &description)
void setAccessibleName (const QString &name)
void setAttribute (Qt::WidgetAttribute attribute, bool enable=true)
void setAutoFillBackground (bool enable)
void setBackgroundRole (QPalette::ColorRole role)
void setBaseSize (const QSize &size)
void setBaseSize (int basew, int baseh)
void setContentsMargins (const QMargins &margins)
void setContentsMargins (int left, int top, int right, int bottom)
void setContextMenuPolicy (Qt::ContextMenuPolicy policy)
void setCursor (const QCursor &cursor)
void setEditFocus (bool enable)
void setFixedHeight (int h)
void setFixedSize (const QSize &size)
void setFixedSize (int w, int h)
void setFixedWidth (int w)
void setFocus (Qt::FocusReason reason)
void setFocusPolicy (Qt::FocusPolicy policy)
void setFocusProxy (QWidget *widget)
void setFont (const QFont &font)
void setForegroundRole (QPalette::ColorRole role)
void setGeometry (const QRect &rect)
void setGeometry (int x, int y, int w, int h)
void setGraphicsEffect (QGraphicsEffect *effect)
void setInputMethodHints (Qt::InputMethodHints hints)
void setLayout (QLayout *layout)
void setLayoutDirection (Qt::LayoutDirection direction)
void setLocale (const QLocale &locale)
void setMask (const QBitmap &bitmap)
void setMask (const QRegion &region)
void setMaximumHeight (int maxh)
void setMaximumSize (const QSize &size)
void setMaximumSize (int maxw, int maxh)
void setMaximumWidth (int maxw)
void setMinimumHeight (int minh)
void setMinimumSize (const QSize &size)
void setMinimumSize (int minw, int minh)
void setMinimumWidth (int minw)
void setMouseTracking (bool enable)
void setPalette (const QPalette &palette)
void setParent (QWidget *parent)
void setParent (QWidget *parent, Qt::WindowFlags flags)
void setShortcutAutoRepeat (int id, bool enable=true)
void setShortcutEnabled (int id, bool enable=true)
void setSizeIncrement (const QSize &size)
void setSizeIncrement (int w, int h)
void setSizePolicy (QSizePolicy policy)
void setSizePolicy (QSizePolicy::Policy horizontal, QSizePolicy::Policy vertical)
void setStatusTip (const QString &data)
void setStyle (QStyle *style)
void setToolTip (const QString &data)
void setToolTipDuration (int msec)
void setUpdatesEnabled (bool enable)
void setWhatsThis (const QString &str)
void setWindowFilePath (const QString &filePath)
void setWindowFlags (Qt::WindowFlags flags)
void setWindowIcon (const QIcon &icon)
void setWindowModality (Qt::WindowModality windowModality)
void setWindowOpacity (qreal level)
void setWindowRole (const QString &role)
void setWindowState (Qt::WindowStates windowState)
QSize size () const
QSize sizeIncrement () const
QSizePolicy sizePolicy () const
void stackUnder (QWidget *widget)
QString statusTip () const
QStylestyle () const
QString styleSheet () const
bool testAttribute (Qt::WidgetAttribute attribute) const
QString toolTip () const
int toolTipDuration () const
QWidget * topLevelWidget () const
bool underMouse () const
void ungrabGesture (Qt::GestureType gestureType)
void unsetCursor ()
void unsetLayoutDirection ()
void unsetLocale ()
void update (const QRect &rect)
void update (const QRegion &region)
void update (int x, int y, int w, int h)
void updateGeometry ()
bool updatesEnabled () const
QRegion visibleRegion () const
QString whatsThis () const
int width () const
QWidget * window () const
QString windowFilePath () const
Qt::WindowFlags windowFlags () const
QWindowwindowHandle () const
QIcon windowIcon () const
Qt::WindowModality windowModality () const
qreal windowOpacity () const
QString windowRole () const
Qt::WindowStates windowState () const
QString windowTitle () const
Qt::WindowType windowType () const
WId winId () const
int x () const
int y () const
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 ~QObject ()
bool blockSignals (bool block)
const QList< QObject * > & children () const
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
void dumpObjectInfo ()
void dumpObjectTree ()
QList< QStringdynamicPropertyNames () const
virtual bool event (QEvent *event)
virtual bool eventFilter (QObject *watched, QEvent *event)
template<typename T >
findChild (const QString &childName=QString ()) const
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
template<class T >
QList< T > findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
bool inherits (const QString &className) const
void installEventFilter (QObject *filterObj)
bool isWidgetType () const
bool isWindowType () const
void killTimer (int id)
const QMetaObjectmetaObject () const
void moveToThread (QThread *targetThread)
QString objectName () const
QObject * parent () const
template<class T = QVariant>
property (const QString &name) const
void removeEventFilter (QObject *obj)
void setObjectName (const QString &name)
void setParent (QObject *parent)
bool setProperty (const QString &name, const QVariant &value)
bool signalsBlocked () const
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
QThreadthread () const
- Public Methods inherited from QPaintDevice
virtual ~QPaintDevice ()
int colorCount () const
int depth () const
int devicePixelRatio () const
qreal devicePixelRatioF () const
int height () const
int heightMM () const
int logicalDpiX () const
int logicalDpiY () const
bool paintingActive () const
int physicalDpiX () const
int physicalDpiY () const
int width () const
int widthMM () const

Protected Methods

virtual void cleanupPage (int id)
void done (int result) override
bool event (QEvent *event) override
virtual void initializePage (int id)
bool nativeEvent (const QByteArray &eventType, void *message, long *result) override
void paintEvent (QPaintEvent *event) override
void resizeEvent (QResizeEvent *event) override
- Protected Methods inherited from QDialog
void closeEvent (QCloseEvent *event) override
void contextMenuEvent (QContextMenuEvent *event) override
bool eventFilter (QObject *object, QEvent *event) override
void keyPressEvent (QKeyEvent *event) override
void showEvent (QShowEvent *event) override
- Protected Methods inherited from QWidget
virtual void actionEvent (QActionEvent *event)
virtual void changeEvent (QEvent *event)
void create (WId window=0, bool initializeWindow=true, bool destroyOldWindow=true)
void destroy (bool destroyWindow=true, bool destroySubWindows=true)
virtual void dragEnterEvent (QDragEnterEvent *event)
virtual void dragLeaveEvent (QDragLeaveEvent *event)
virtual void dragMoveEvent (QDragMoveEvent *event)
virtual void dropEvent (QDropEvent *event)
virtual void enterEvent (QEvent *event)
bool event (QEvent *event) override
virtual void focusInEvent (QFocusEvent *event)
bool focusNextChild ()
virtual bool focusNextPrevChild (bool next)
virtual void focusOutEvent (QFocusEvent *event)
bool focusPreviousChild ()
virtual void hideEvent (QHideEvent *event)
void initPainter (QPainter *painter) const override
virtual void inputMethodEvent (QInputMethodEvent *event)
virtual void keyReleaseEvent (QKeyEvent *event)
virtual void leaveEvent (QEvent *event)
int metric (PaintDeviceMetric metric) const override
virtual void mouseDoubleClickEvent (QMouseEvent *event)
virtual void mouseMoveEvent (QMouseEvent *event)
virtual void mousePressEvent (QMouseEvent *event)
virtual void mouseReleaseEvent (QMouseEvent *event)
virtual void moveEvent (QMoveEvent *event)
virtual void tabletEvent (QTabletEvent *event)
virtual void wheelEvent (QWheelEvent *event)
- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
virtual void connectNotify (const QMetaMethod &signalMethod) const
virtual void customEvent (QEvent *event)
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
bool isSignalConnected (const QMetaMethod &signalMethod) const
int receivers (const QString &signal) const
QObject * sender () const
int senderSignalIndex () const
virtual void timerEvent (QTimerEvent *event)
- Protected Methods inherited from QPaintDevice
 QPaintDevice ()


- Properties inherited from QDialog
- Properties inherited from QWidget
- Properties inherited from QObject


class QWizardPage

Additional Inherited Members

- Static Public Methods inherited from QWidget
static QWidget * createWindowContainer (QWindow *window, QWidget *parent=nullptr, Qt::WindowFlags flags=Qt::EmptyFlag)
static QWidget * find (WId id)
static QWidget * keyboardGrabber ()
static QWidget * mouseGrabber ()
static void setTabOrder (QWidget *firstWidget, QWidget *secondWidget)
- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
static bool disconnect (const QObject *sender, std::nullptr_t, const QObject *receiver, std::nullptr_t)
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
static QMetaObjectstaticMetaObject ()
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
- Protected Slots inherited from QWidget
void updateMicroFocus ()

Detailed Description

The QWizard class provides support for wizards. A wizard (also called an assistant on Mac OS X) is a special type of input dialog that consists of a sequence of pages. The purpose of a wizard is to guide the user through a process step by step. Wizards are useful for complex or infrequent tasks users may find difficult to learn.

QWizard inherits QDialog and represents a wizard. Each page is a QWizardPage (a QWidget subclass). To create your own wizards, you can use these classes directly, or you can subclass them for more control.

Simple Example

The following example illustrates how to create wizard pages and add them to a wizard.

QWizardPage *createIntroPage()
QLabel *label = new QLabel("This wizard will register your copy of Super Product Two.");
return page;
QWizardPage *createRegistrationPage()
QWizardPage *createConclusionPage()
int main(int argc, char *argv[])
QApplication app(argc, argv);
QString translatorFileName = ("cs_");
translatorFileName += QLocale::system().name();
QTranslator *translator = new QTranslator(&app);
if (translator->load(translatorFileName, QLibraryInfo::location(QLibraryInfo::TranslationsPath))) {
QWizard wizard;
wizard.setWindowTitle("Trivial Wizard");;
return app.exec();

Wizard Look and Feel

QWizard supports four wizard looks.

  • ClassicStyle
  • ModernStyle
  • MacStyle
  • AeroStyle

You can explicitly set the look to use using setWizardStyle() (e.g., if you want the same look on all platforms).


Note: AeroStyle has effect only on a Windows Vista system with alpha compositing enabled. ModernStyle is used as a fallback when this condition is not met.

In addition to the wizard style, there are several options that control the look and feel of the wizard. These can be set using setOption() or setOptions(). For example, HaveHelpButton makes QWizard show a Help button along with the other wizard buttons.

You can even change the order of the wizard buttons to any arbitrary order using setButtonLayout(), and you can add up to three custom buttons (e.g., a Print button) to the button row. This is achieved by calling setButton() or setButtonText() with CustomButton1, CustomButton2, or CustomButton3 to set up the button, and by enabling the HaveCustomButton1, HaveCustomButton2, or HaveCustomButton3 options. Whenever the user clicks a custom button, customButtonClicked() is emitted.

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

Elements of a Wizard Page

Wizards consist of a sequence of QWizardPages. At any time, only one page is shown. A page has the following attributes:

  • A title.
  • A subTitle.
  • A set of pixmaps, which may or may not be honored, depending on the wizard's style:
    • WatermarkPixmap (used by ClassicStyle and ModernStyle)
    • BannerPixmap (used by ModernStyle)
    • LogoPixmap (used by ClassicStyle and ModernStyle)
    • BackgroundPixmap (used by MacStyle)

The diagram below shows how QWizard renders these attributes, assuming they are all present and ModernStyle is used:

When a subTitle is set, QWizard displays it in a header, in which case it also uses the BannerPixmap and the LogoPixmap to decorate the header. The WatermarkPixmap is displayed on the left side, below the header. At the bottom, there is a row of buttons allowing the user to navigate through the pages.

The page itself (the QWizardPage widget) occupies the area between the header, the watermark, and the button row. Typically, the page is a QWizardPage on which a QGridLayout is installed, with standard child widgets (QLabels, QLineEdits, etc.).

If the wizard's style is MacStyle, the page looks radically different:

The watermark, banner, and logo pixmaps are ignored by the MacStyle. If the BackgroundPixmap is set, it is used as the background for the wizard, otherwise a default "assistant" image is used.

The title and subtitle are set by calling QWizardPage::setTitle() and QWizardPage::setSubTitle() on the individual pages. They may be plain text or HTML (see titleFormat and subTitleFormat). The pixmaps can be set globally for the entire wizard using setPixmap(), or on a per-page basis using QWizardPage::setPixmap().

Registering and Using Fields

In many wizards, the contents of a page may affect the default values of the fields of a later page. To make it easy to communicate between pages, QWizard supports a "field" mechanism that allows you to register a field (e.g., a QLineEdit) on a page and to access its value from any page. It is also possible to specify mandatory fields (i.e., fields that must be filled before the user can advance to the next page).

To register a field, call QWizardPage::registerField() field.

ClassInfoPage::ClassInfoPage(QWidget *parent)
classNameLabel = new QLabel(tr("&Class name:"));
classNameLineEdit = new QLineEdit;
baseClassLabel = new QLabel(tr("B&ase class:"));
baseClassLineEdit = new QLineEdit;
qobjectMacroCheckBox = new QCheckBox(tr("Generate CS_OBJECT &macro"));
registerField("className*", classNameLineEdit);
registerField("baseClass", baseClassLineEdit);
registerField("qobjectMacro", qobjectMacroCheckBox);

The above code registers three fields, className, baseClass, and qobjectMacro, which are associated with three child widgets. The asterisk (*) next to className denotes a mandatory field.

The fields of any page are accessible from any other page.

void OutputFilesPage::initializePage()
QString className = field("className").toString();
headerLineEdit->setText(className.toLower() + ".h");
implementationLineEdit->setText(className.toLower() + ".cpp");

We call QWizardPage::field() to access the contents of the className field (which was defined in the ClassInfoPage) and use it to initialize the OutputFilePage. The field's contents is returned as a QVariant.

When we create a field using QWizardPage::registerField(), we pass a unique field name and a widget. We can also provide a CopperSpice property name and a "changed" signal (a signal that is emitted when the property changes) as third and fourth arguments; however, this is not necessary for the most common CopperSpice widgets, such as QLineEdit, QCheckBox, and QComboBox, because QWizard knows which properties to look for.

If an asterisk (*) is appended to the name when the property is registered, the field is a mandatory field. When a page has mandatory fields, the Next and/or Finish buttons are enabled only when all mandatory fields are filled.

To consider a field "filled", QWizard simply checks that the field's current value does not equal the original value (the value it had when initializePage() was called). For QLineEdit and QAbstractSpinBox subclasses, QWizard also checks that hasAcceptableInput() returns true, to honor any validator or mask.

QWizard's mandatory field mechanism is provided for convenience. A more powerful (but also more cumbersome) alternative is to reimplement QWizardPage::isComplete() and to emit the QWizardPage::completeChanged() signal whenever the page becomes complete or incomplete.

The enabled/disabled state of the Next and/or Finish buttons is one way to perform validation on the user input. Another way is to reimplement validateCurrentPage() (or QWizardPage::validatePage()) to perform some last-minute validation (and show an error message if the user has entered incomplete or invalid information). If the function returns true, the next page is shown (or the wizard finishes), otherwise the current page stays up.

Creating Linear Wizards

Most wizards have a linear structure, with page 1 followed by page 2 and so on until the last page. With QWizard, linear wizards are created by instantiating the QWizardPages and inserting them using addPage(). By default, the pages are shown in the order in which they were added.

ClassWizard::ClassWizard(QWidget *parent)
addPage(new IntroPage);
addPage(new ClassInfoPage);
addPage(new CodeStylePage);
addPage(new OutputFilesPage);
addPage(new ConclusionPage);

When a page is about to be shown, QWizard calls initializePage() (which in turn calls QWizardPage::initializePage()) to fill the page with default values. By default, this function does nothing, but it can be reimplemented to initialize the page's contents based on other pages' fields (refer to the initialize page example above).

If the user presses Back, cleanupPage() is called (which in turn calls QWizardPage::cleanupPage()). The default implementation resets the page's fields to their original values (the values they had before initializePage() was called). If you want the Back button to be non-destructive and keep the values entered by the user, simply enable the IndependentPages option.

Creating Non-Linear Wizards

Some wizards are more complex in that they allow different traversal paths based on the information provided by the user.

In complex wizards, pages are identified by IDs. These IDs are typically defined using an enum.

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

The pages are inserted using setPage(), which takes an ID and an instance of QWizardPage (or of a subclass):

LicenseWizard::LicenseWizard(QWidget *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);

By default, the pages are shown in increasing ID order. To provide a dynamic order that depends on the options chosen by the user, we must reimplement QWizardPage::nextId().

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;

It would also be possible to put all the logic in one place, in a QWizard::nextId() reimplementation.

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:
return -1;

To start at another page than the page with the lowest ID, call setStartId().

To test whether a page has been visited or not, call hasVisitedPage().

void ConclusionPage::initializePage()
QString licenseText;
if (wizard()->hasVisitedPage(LicenseWizard::Page_Evaluate)) {
licenseText = tr("Evaluation License Agreement: "
"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("First-Time License Agreement: "
"You can use this software subject to the license "
"you will receive by email.");
} else {
licenseText = tr("Upgrade License Agreement: "
"This software is licensed under the terms of your "
"current license.");
See also

Member Typedef Documentation

Typedef for QFlags<WizardOption>. Refer to QWizard::WizardOption for documentation.

Member Enumeration Documentation

This enum specifies the buttons in a wizard.

QWizard::BackButton0Back button (Go Back on Mac OS X)
QWizard::NextButton1Next button (Continue on Mac OS X)
QWizard::CommitButton2Commit button
QWizard::FinishButton3Finish button (Done on Mac OS X)
QWizard::CancelButton4Cancel button (refer to NoCancelButton)
QWizard::HelpButton5Help button (refer to HaveHelpButton)
QWizard::CustomButton16 First user-defined button (refer to HaveCustomButton1)
QWizard::CustomButton27 Second user-defined button (refer to HaveCustomButton2)
QWizard::CustomButton38 Third user-defined button (refer to HaveCustomButton3)

The following value is only useful when calling setButtonLayout():

QWizard::Stretch9 A horizontal stretch in the button layout
See also
setButton(), setButtonText(), setButtonLayout(), customButtonClicked()

This enum specifies various options that affect the look and feel of a wizard.

QWizard::IndependentPages 0x00000001 Pages are independent of each other, they do not derive values from each other.
QWizard::IgnoreSubTitles 0x00000002 Do not show any subtitles, even if they are set.
QWizard::ExtendedWatermarkPixmap 0x00000004 Extend any WatermarkPixmap all the way down to the window's edge.
QWizard::NoDefaultButton 0x00000008 Do not make the Next or Finish button the dialog's default button.
QWizard::NoBackButtonOnStartPage 0x00000010 Do not show the Back button on the start page.
QWizard::NoBackButtonOnLastPage 0x00000020 Do not show the Back button on the last page.
QWizard::DisabledBackButtonOnLastPage 0x00000040 Disable the Back button on the last page.
QWizard::HaveNextButtonOnLastPage 0x00000080 Show the (disabled) Next button on the last page.
QWizard::HaveFinishButtonOnEarlyPages 0x00000100 Show the (disabled) Finish button on non-final pages.
QWizard::NoCancelButton 0x00000200 Do not show the Cancel button.
QWizard::CancelButtonOnLeft 0x00000400 Put the Cancel button on the left of Back (rather than on the right of Finish or Next).
QWizard::HaveHelpButton 0x00000800 Show the Help button.
QWizard::HelpButtonOnRight 0x00001000 Put the Help button on the far right of the button layout (rather than on the far left).
QWizard::HaveCustomButton1 0x00002000 Show the first user-defined button (CustomButton1).
QWizard::HaveCustomButton2 0x00004000 Show the second user-defined button (CustomButton2).
QWizard::HaveCustomButton3 0x00008000 Show the third user-defined button (CustomButton3).
QWizard::NoCancelButtonOnLastPage 0x00010000 Do not show the Cancel button on the last page.
See also
setOptions(), setOption(), testOption()

This enum specifies the pixmaps that can be associated with a page.

QWizard::WatermarkPixmap0 Tall pixmap on the left side of a ClassicStyle or ModernStyle page
QWizard::LogoPixmap1 Small pixmap on the right side of a ClassicStyle or ModernStyle page header
QWizard::BannerPixmap2 Pixmap that occupies the background of a ModernStyle page header
QWizard::BackgroundPixmap3 Pixmap that occupies the background of a MacStyle wizard
See also
setPixmap(), QWizardPage::setPixmap()

This enum specifies the different looks supported by QWizard.

QWizard::ClassicStyle0Classic Windows look
QWizard::ModernStyle1Modern Windows look
QWizard::MacStyle2Mac OS X look
QWizard::AeroStyle3Windows Aero look
See also
setWizardStyle(), WizardOption

Constructor & Destructor Documentation

QWizard::QWizard ( QWidget parent = nullptr,
Qt::WindowFlags  flags = Qt::EmptyFlag 

Constructs a wizard with the given parent and window flags.

See also
parent(), windowFlags()
QWizard::~QWizard ( )

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

Method Documentation

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(), pageAdded()
void QWizard::back ( )

Goes back to the previous page.

This is equivalent to pressing the Back button.

See also
next(), accept(), reject(), restart()
QAbstractButton * QWizard::button ( WizardButton  which) const

Returns the button corresponding to role which.

See also
setButton(), setButtonText()
QString QWizard::buttonText ( WizardButton  which) const

Returns the text on button which. If a text has been 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(), QWizardPage::setButtonText()
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(), initializePage()
int QWizard::currentId ( ) const

Returns the value of the property.

void QWizard::currentIdChanged ( int  id)

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

See also
currentId(), currentPage()
QWizardPage * QWizard::currentPage ( ) const

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

See also
page(), currentId(), restart()
void QWizard::customButtonClicked ( int  which)

This signal is emitted when the user clicks a custom button. The value for 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
void QWizard::done ( int  result)

Reimplemented from QDialog::done()

bool QWizard::event ( QEvent event)

Reimplemented from QWidget::event()

QVariant QWizard::field ( const QString name) const

Returns the value of the field called name. This method can be used to access fields on any page of the wizard.

See also
QWizardPage::registerField(), QWizardPage::field(), 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
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.

LicenseWizard::LicenseWizard(QWidget *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.");
message = tr("This help is likely not to be of any help.");
QMessageBox::information(this, tr("License Wizard Help"), message);
See also
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(), cleanupPage()
bool QWizard::nativeEvent ( const QByteArray eventType,
void *  message,
long *  result 

This special event handler can be reimplemented in a subclass to receive native platform events identified by eventType which are passed in the message parameter.

In your reimplementation of this method, if you want to stop the event being handled by CopperSpice, return true and set result. If you return false this native event is passed back to CopperSpice, which translates the event into a CopperSpice event and sends it to the widget.

This method supersedes the event filter methods x11Event(), winEvent(), and macEvent().

Events are only delivered to this event handler if the widget is has a native Window handle.
Platform Event Type Identifier Message Type Result Type
Windows "windows_generic_MSG" MSG * LRESULT

Reimplemented from QWidget::nativeEvent()

void QWizard::next ( )

Advances to the next page.

This is equivalent to pressing the Next or Commit button.

See also
nextId(), back(), accept(), reject(), restart()
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(), currentPage()
WizardOptions QWizard::options ( ) const

Returns the value of the property.

QWizardPage * QWizard::page ( int  id) const

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

See also
addPage(), setPage()
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(), startId()
QList< int > QWizard::pageIds ( ) const

Returns the list of page IDs.

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(), startId()
void QWizard::paintEvent ( QPaintEvent event)

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()
void QWizard::removePage ( int  id)

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

Removing a page may influence the value of the startId property.
See also
addPage(), setPage(), pageRemoved(), startId()
void QWizard::resizeEvent ( QResizeEvent event)

Reimplemented from QDialog::resizeEvent()

void QWizard::restart ( )

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

See also
void QWizard::setButton ( WizardButton  which,
QAbstractButton button 

Sets button to behave like the role defined by which. Refer to the WizardButton enum for list of roles.

For example, to add a Print button, one way is to call setButton() with the role CustomButton1. Then make the button visible using the WizardOption::HaveCustomButton1 flag.

See also
button(), setButtonText(), setButtonLayout(), options
void QWizard::setButtonLayout ( const QList< WizardButton > &  layout)

Sets the order in which buttons are displayed to layout, which 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.

MyWizard::MyWizard(QWidget *parent)
layout << QWizard::Stretch << QWizard::BackButton << QWizard::CancelButton
<< QWizard::NextButton << QWizard::FinishButton;
See also
setButton(), setButtonText(), 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 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(), QWizardPage::setButtonText()
void QWizard::setDefaultProperty ( const QString className,
const QString property,
const QString 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 is passed to QWizardPage::registerField() and no property is specified.

QWizard knows the most common CopperSpice widgets. For these or their subclasses, you do not need to specify a property or a changedSignal. This table lists the widgets which are supported automatically in QWizard.

WidgetPropertyChange Notification Signal
QAbstractButtonbool checkedtoggled()
QAbstractSliderint valuevalueChanged()
QComboBoxint currentIndexcurrentIndexChanged()
QDateTimeEditQDateTime dateTimedateTimeChanged()
QLineEditQString texttextChanged()
QListWidgetint currentRowcurrentRowChanged()
QSpinBoxint valuevalueChanged()
See also
void QWizard::setField ( const QString name,
const QVariant value 

Sets the value of the field called name to value. This method can be used to set fields on any page of the wizard.

See also
QWizardPage::registerField(), QWizardPage::setField(), 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(), setWizardStyle()
void QWizard::setOptions ( WizardOptions  options)

Sets the value of the property to options.

void QWizard::setPage ( int  id,
QWizardPage page 

Adds the given page to the wizard with the given id. Adding a page may influence the value of the startId property in case it was not set explicitly.

See also
addPage(), page(), 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()
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. By default, no side widget is present.

Passing nullptr shows no side widget. When the widget is not a nullptr the wizard takes ownership. 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).

See also
void QWizard::setStartId ( int  id)

Sets the value of the property to id.

void QWizard::setSubTitleFormat ( Qt::TextFormat  format)

Sets the value of the property to format.

void QWizard::setTitleFormat ( Qt::TextFormat  format)

Sets the value of the property to format.

void QWizard::setVisible ( bool  visible)

Sets the value of the property to visible.

void QWizard::setWizardStyle ( WizardStyle  style)

Sets the value of the property to style.

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
QSize QWizard::sizeHint ( ) const

Reimplemented from QDialog::sizeHint()

int QWizard::startId ( ) const

Returns the value of the property.

Qt::TextFormat QWizard::subTitleFormat ( ) const

Returns the value of the property.

bool QWizard::testOption ( WizardOption  option) const

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

See also
options, setOption(), setWizardStyle()
Qt::TextFormat QWizard::titleFormat ( ) const

Returns the value of the property.

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(), 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
WizardStyle QWizard::wizardStyle ( ) const

Returns the value of the property.

Property Documentation


This property holds the ID of the current page. This property can not be set directly. To change the current page, call next(), back(), or restart(). By default, this property has a value of -1, indicating that no page is currently shown.

See also
currentIdChanged(), currentPage()
PropertiesClass Methods
read currentId
notify currentIdChanged

This property holds the various options that affect the look and feel of the wizard. The following options are set by default for each listed platform.

  • Windows: HelpButtonOnRight.
  • Mac OS X: NoDefaultButton and NoCancelButton.
  • X11: none.
See also
PropertiesClass Methods
read options
write setOptions

This property holds the ID of the first page. If this property is not explicitly set, this property defaults to the lowest page ID in this wizard, or -1 if no page has been inserted yet.

See also
restart(), nextId()
PropertiesClass Methods
read startId
write setStartId

This property holds the text format used by page subtitles. The default format is Qt::AutoText.

See also
QWizardPage::title, titleFormat
PropertiesClass Methods
read subTitleFormat
write setSubTitleFormat

This property holds the text format used by page titles. The default format is Qt::AutoText.

See also
QWizardPage::title, subTitleFormat
PropertiesClass Methods
read titleFormat
write setTitleFormat

This property holds the look and feel of the wizard.

By default, QWizard uses the AeroStyle on a Windows Vista system with alpha compositing enabled, regardless of the current widget style. If this is not the case, the default wizard style depends on the current widget style as follows: MacStyle is the default if the current widget style is QMacStyle, ModernStyle is the default if the current widget style is QWindowsStyle, and ClassicStyle is the default in all other cases.

See also
PropertiesClass Methods
read wizardStyle
write setWizardStyle