include/QtWidgets/qwizard.h

0001 // Copyright (C) 2016 The Qt Company Ltd.
0002 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0003
0004 #ifndef QWIZARD_H
0005 #define QWIZARD_H
0006
0007 #include <QtWidgets/qtwidgetsglobal.h>
0008 #include <QtWidgets/qdialog.h>
0009
0010 QT_REQUIRE_CONFIG(wizard);
0011
0012 QT_BEGIN_NAMESPACE
0013
0014 class QAbstractButton;
0015 class QWizardPage;
0016 class QWizardPrivate;
0017
0018 class Q_WIDGETS_EXPORT QWizard : public QDialog
0019 {
0020     Q_OBJECT
0021     Q_PROPERTY(WizardStyle wizardStyle READ wizardStyle WRITE setWizardStyle)
0022     Q_PROPERTY(WizardOptions options READ options WRITE setOptions)
0023     Q_PROPERTY(Qt::TextFormat titleFormat READ titleFormat WRITE setTitleFormat)
0024     Q_PROPERTY(Qt::TextFormat subTitleFormat READ subTitleFormat WRITE setSubTitleFormat)
0025     Q_PROPERTY(int startId READ startId WRITE setStartId)
0026     Q_PROPERTY(int currentId READ currentId WRITE setCurrentId NOTIFY currentIdChanged)
0027
0028 public:
0029     enum WizardButton {
0030         BackButton,
0031         NextButton,
0032         CommitButton,
0033         FinishButton,
0034         CancelButton,
0035         HelpButton,
0036         CustomButton1,
0037         CustomButton2,
0038         CustomButton3,
0039         Stretch,
0040
0041         NoButton = -1,
0042         NStandardButtons = 6,
0043         NButtons = 9
0044     };
0045
0046     enum WizardPixmap {
0047         WatermarkPixmap,
0048         LogoPixmap,
0049         BannerPixmap,
0050         BackgroundPixmap,
0051         NPixmaps
0052     };
0053
0054     enum WizardStyle {
0055         ClassicStyle,
0056         ModernStyle,
0057         MacStyle,
0058         AeroStyle,
0059         NStyles
0060     };
0061     Q_ENUM(WizardStyle)
0062
0063     enum WizardOption {
0064         IndependentPages                = 0x00000001,
0065         IgnoreSubTitles                 = 0x00000002,
0066         ExtendedWatermarkPixmap         = 0x00000004,
0067         NoDefaultButton                 = 0x00000008,
0068         NoBackButtonOnStartPage         = 0x00000010,
0069         NoBackButtonOnLastPage          = 0x00000020,
0070         DisabledBackButtonOnLastPage    = 0x00000040,
0071         HaveNextButtonOnLastPage        = 0x00000080,
0072         HaveFinishButtonOnEarlyPages    = 0x00000100,
0073         NoCancelButton                  = 0x00000200,
0074         CancelButtonOnLeft              = 0x00000400,
0075         HaveHelpButton                  = 0x00000800,
0076         HelpButtonOnRight               = 0x00001000,
0077         HaveCustomButton1               = 0x00002000,
0078         HaveCustomButton2               = 0x00004000,
0079         HaveCustomButton3               = 0x00008000,
0080         NoCancelButtonOnLastPage        = 0x00010000
0081     };
0082     Q_ENUM(WizardOption)
0083
0084     Q_DECLARE_FLAGS(WizardOptions, WizardOption)
0085     Q_FLAG(WizardOptions)
0086
0087     explicit QWizard(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags());
0088     ~QWizard();
0089
0090     int addPage(QWizardPage *page);
0091     void setPage(int id, QWizardPage *page);
0092     void removePage(int id);
0093     QWizardPage *page(int id) const;
0094     bool hasVisitedPage(int id) const;
0095     QList<int> visitedIds() const;
0096     QList<int> pageIds() const;
0097     void setStartId(int id);
0098     int startId() const;
0099     QWizardPage *currentPage() const;
0100     int currentId() const;
0101
0102     virtual bool validateCurrentPage();
0103     virtual int nextId() const;
0104
0105     void setField(const QString &name, const QVariant &value);
0106     QVariant field(const QString &name) const;
0107
0108     void setWizardStyle(WizardStyle style);
0109     WizardStyle wizardStyle() const;
0110
0111     void setOption(WizardOption option, bool on = true);
0112     bool testOption(WizardOption option) const;
0113     void setOptions(WizardOptions options);
0114     WizardOptions options() const;
0115
0116     void setButtonText(WizardButton which, const QString &text);
0117     QString buttonText(WizardButton which) const;
0118     void setButtonLayout(const QList<WizardButton> &layout);
0119     void setButton(WizardButton which, QAbstractButton *button);
0120     QAbstractButton *button(WizardButton which) const;
0121
0122     void setTitleFormat(Qt::TextFormat format);
0123     Qt::TextFormat titleFormat() const;
0124     void setSubTitleFormat(Qt::TextFormat format);
0125     Qt::TextFormat subTitleFormat() const;
0126     void setPixmap(WizardPixmap which, const QPixmap &pixmap);
0127     QPixmap pixmap(WizardPixmap which) const;
0128
0129     void setSideWidget(QWidget *widget);
0130     QWidget *sideWidget() const;
0131
0132     void setDefaultProperty(const char *className, const char *property,
0133                             const char *changedSignal);
0134
0135     void setVisible(bool visible) override;
0136     QSize sizeHint() const override;
0137
0138 Q_SIGNALS:
0139     void currentIdChanged(int id);
0140     void helpRequested();
0141     void customButtonClicked(int which);
0142     void pageAdded(int id);
0143     void pageRemoved(int id);
0144
0145 public Q_SLOTS:
0146     void back();
0147     void next();
0148     void setCurrentId(int id);
0149     void restart();
0150
0151 protected:
0152     bool event(QEvent *event) override;
0153     void resizeEvent(QResizeEvent *event) override;
0154     void paintEvent(QPaintEvent *event) override;
0155 #if defined(Q_OS_WIN) || defined(Q_QDOC)
0156     bool nativeEvent(const QByteArray &eventType, void *message, qintptr *result) override;
0157 #endif
0158     void done(int result) override;
0159     virtual void initializePage(int id);
0160     virtual void cleanupPage(int id);
0161
0162 private:
0163     Q_DISABLE_COPY(QWizard)
0164     Q_DECLARE_PRIVATE(QWizard)
0165     Q_PRIVATE_SLOT(d_func(), void _q_emitCustomButtonClicked())
0166     Q_PRIVATE_SLOT(d_func(), void _q_updateButtonStates())
0167     Q_PRIVATE_SLOT(d_func(), void _q_handleFieldObjectDestroyed(QObject *))
0168
0169     friend class QWizardPage;
0170 };
0171
0172 Q_DECLARE_OPERATORS_FOR_FLAGS(QWizard::WizardOptions)
0173
0174 class QWizardPagePrivate;
0175
0176 class Q_WIDGETS_EXPORT QWizardPage : public QWidget
0177 {
0178     Q_OBJECT
0179     Q_PROPERTY(QString title READ title WRITE setTitle)
0180     Q_PROPERTY(QString subTitle READ subTitle WRITE setSubTitle)
0181
0182 public:
0183     explicit QWizardPage(QWidget *parent = nullptr);
0184     ~QWizardPage();
0185
0186     void setTitle(const QString &title);
0187     QString title() const;
0188     void setSubTitle(const QString &subTitle);
0189     QString subTitle() const;
0190     void setPixmap(QWizard::WizardPixmap which, const QPixmap &pixmap);
0191     QPixmap pixmap(QWizard::WizardPixmap which) const;
0192     void setFinalPage(bool finalPage);
0193     bool isFinalPage() const;
0194     void setCommitPage(bool commitPage);
0195     bool isCommitPage() const;
0196     void setButtonText(QWizard::WizardButton which, const QString &text);
0197     QString buttonText(QWizard::WizardButton which) const;
0198
0199     virtual void initializePage();
0200     virtual void cleanupPage();
0201     virtual bool validatePage();
0202     virtual bool isComplete() const;
0203     virtual int nextId() const;
0204
0205 Q_SIGNALS:
0206     void completeChanged();
0207
0208 protected:
0209     void setField(const QString &name, const QVariant &value);
0210     QVariant field(const QString &name) const;
0211     void registerField(const QString &name, QWidget *widget, const char *property = nullptr,
0212                        const char *changedSignal = nullptr);
0213     QWizard *wizard() const;
0214
0215 private:
0216     Q_DISABLE_COPY(QWizardPage)
0217     Q_DECLARE_PRIVATE(QWizardPage)
0218     Q_PRIVATE_SLOT(d_func(), void _q_maybeEmitCompleteChanged())
0219     Q_PRIVATE_SLOT(d_func(), void _q_updateCachedCompleteState())
0220
0221     friend class QWizard;
0222     friend class QWizardPrivate;
0223 };
0224
0225 QT_END_NAMESPACE
0226
0227 #endif // QWIZARD_H