QWizard Class

成员函数文档

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

根据给定的parent 和窗口flags 构建一个向导。

另请参阅 parent() 和windowFlags()。

[virtual noexcept] QWizard::~QWizard()

销毁该向导及其页面，并释放所有已分配的资源。

int QWizard::addPage(QWizardPage *page)

将指定的page 添加到向导中，并返回该页面的ID。

该 ID 保证大于该QWizard 当前包含的任何其他 ID。

另请参阅 setPage()、page() 和pageAdded()。

[slot] void QWizard::back()

返回上一页。

这相当于点击Back 按钮。

另请参阅 next()、accept()、reject() 以及restart()。

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

返回与角色which 相对应的按钮。

另请参阅 setButton() 和setButtonText()。

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

返回按钮which 上的文本。

如果已使用 `setButtonText()` 设置了文本，则返回该文本。

默认情况下，按钮上的文本取决于wizardStyle 。例如，在 macOS 上，Next 按钮被命名为Continue 。

另请参阅 button()、setButton()、setButtonText()、QWizardPage::buttonText() 和QWizardPage::setButtonText()。

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

该虚拟函数由QWizard 调用，用于在用户点击Back 离开页面id 之前清理该页面（除非设置了QWizard::IndependentPages 选项）。

默认实现会调用页面（id ）上的QWizardPage::cleanupPage()。

另请参阅 QWizardPage::cleanupPage() 和initializePage()。

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

当当前页面发生变化时，会发出此信号，此时新的当前页面为id 。

另请参阅 currentId() 和currentPage()。

QWizardPage *QWizard::currentPage() const

返回指向当前页面的指针；如果没有当前页面（例如，在显示向导之前），则返回nullptr 。

这相当于调用 page(currentId())。

另请参阅 page()、currentId() 和restart()。

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

当用户点击自定义按钮时，会触发此信号。which 可以是CustomButton1 、CustomButton2 或CustomButton3 。

默认情况下，不会显示任何自定义按钮。若要显示自定义按钮，请调用setOption() 并传入HaveCustomButton1 、HaveCustomButton2 或HaveCustomButton3 作为参数；若要配置该按钮，请使用setButtonText() 或setButton()。

另请参阅 helpRequested()。

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

重新实现了：QDialog::done(int r)。

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

重写了：QWidget::event(QEvent *event)。

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

返回名为name 的字段的值。

此函数可用于访问向导中任意页面的字段。

另请参阅 QWizardPage::registerField()、QWizardPage::field() 和setField()。

bool QWizard::hasVisitedPage(int id) const

如果页面历史记录中包含页面id ，则返回true ；否则，返回false 。

点击Back 会将当前页面再次标记为“未访问”。

另请参阅 visitedIds()。

[signal] void QWizard::helpRequested()

当用户点击“Help ”按钮时，会触发此信号。

默认情况下，不会显示“Help ”按钮。若需显示该按钮，请调用setOption(HaveHelpButton, true)。

示例：

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

}

另请参阅 customButtonClicked()。

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

该虚拟函数由QWizard 调用，用于在页面id 显示之前对其进行准备——无论是因调用QWizard::restart()所致，还是因用户点击Next 所致。（不过，如果设置了QWizard::IndependentPages 选项，则该函数仅在页面首次显示时被调用。）

通过重写此函数，您可以确保页面的字段能够根据前一页的字段进行正确初始化。

默认实现会在页面加载时（id ）调用QWizardPage::initializePage()。

另请参阅 QWizardPage::initializePage()和cleanupPage()。

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

重写了：QWidget::nativeEvent （const QByteArray &eventType, void *message, qintptr *result）。

[slot] void QWizard::next()

转到下一页。

这相当于点击Next 或Commit 按钮。

另请参阅 nextId()、back()、accept()、reject() 以及restart()。

[virtual] int QWizard::nextId() const

该虚拟函数由QWizard 调用，用于确定当用户点击Next 按钮时应显示哪一页。

返回值为下一页的 ID，如果没有后续页面，则返回 -1。

默认实现会在调用currentPage() 时调用QWizardPage::nextId()。

通过重写此函数，您可以指定动态的页面顺序。

另请参阅 QWizardPage::nextId() 和currentPage()。

QWizardPage *QWizard::page(int id) const

返回指定id 的页面；如果不存在该页面，则返回nullptr 。

另请参阅 addPage() 和setPage()。

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

每当向向导添加一个页面时，都会触发此信号。该页面的id 将作为参数传递。

另请参阅 addPage()、setPage() 和startId()。

QList<int> QWizard::pageIds() const

返回页面 ID 的列表。

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

每当从向导中移除一个页面时，都会触发此信号。该页面的id 将作为参数传递。

另请参阅 removePage() 和startId()。

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

重写了：QWidget::paintEvent(QPaintEvent *event)。

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

返回为角色“which ”设置的像素图。

默认情况下，在 macOS 上唯一设置的位图是BackgroundPixmap 。

另请参阅 setPixmap()、QWizardPage::pixmap() 以及Elements of a Wizard Page 。

void QWizard::removePage(int id)

删除具有指定id 的页面。如有必要，将调用cleanupPage()。

另请参阅 addPage()、setPage()、pageRemoved() 和startId()。

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

重写了：QDialog::resizeEvent （QResizeEvent *）。

[slot] void QWizard::restart()

将向导重启至起始页面。当向导显示时，该函数会自动调用。

另请参阅 startId()。

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

将对应于角色“which ”的按钮设置为“button ”。

若要向向导中添加额外按钮（例如，Print 按钮），一种方法是调用setButton()，将CustomButton1 设置为CustomButton3 ，并使用HaveCustomButton1 和HaveCustomButton3 选项使按钮可见。

另请参阅 button()、setButtonText()、setButtonLayout() 以及options 。

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

将按钮的显示顺序设置为layout ，其中layout 是一个WizardButton列表。

默认布局取决于所设置的选项（例如，是否启用了HelpButtonOnRight ）。若您需要比options 所提供的更多按钮布局控制权，可调用此函数。

您可以使用Stretch 来指定布局中的水平拉伸比例。

示例：

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

另请参阅 setButton()、setButtonText() 和setOptions()。

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

将按钮which 上的文本设置为text 。

默认情况下，按钮上的文本取决于wizardStyle 。例如，在 macOS 上，Next 按钮被称为Continue 。

若要向向导中添加额外按钮（例如“Print ”按钮），一种方法是调用 setButtonText() 并传入CustomButton1 、CustomButton2 或CustomButton3 来设置其文本，然后使用HaveCustomButton1 、HaveCustomButton2 和/或HaveCustomButton3 选项使这些按钮可见。

按钮文本也可以通过QWizardPage::setButtonText() 按页面进行设置。

另请参阅 buttonText()、setButton()、button()、setButtonLayout()、setOptions() 以及QWizardPage::setButtonText()。

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

将currentId 设置为id ，期间不访问currentId 到id 之间的页面。

如果

• 向导中没有页面
• 当前页面无效
• 给定的页面等于currentId()
• 给定的页面超出范围

注意：如果已向前跳过页面且id 为0，则页面访问历史记录将被删除

另请参阅 currentId()。

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

将className 的默认属性设置为property ，并将相关的变更信号设置为changedSignal 。

当将className （或其子类之一）的实例传递给QWizardPage::registerField() 且未指定属性时，将使用该默认属性。

QWizard 该函数支持最常见的 Qt Widgets。对于这些 Widgets（或其子类），您无需指定property 或changedSignal 。下表列出了这些 Widgets：

另请参阅 QWizardPage::registerField()。

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

将名为name 的字段值设置为value 。

此函数可用于设置向导中任意页面的字段。

另请参阅 QWizardPage::registerField()、QWizardPage::setField() 和field()。

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

如果on 为true，则启用指定的option ；否则，清除指定的option 。

另请参阅 options 、testOption() 和setWizardStyle()。

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

将给定的page 添加到具有给定id 的向导中。

另请参阅 addPage()、page() 和pageAdded()。

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

将角色which 的位图设置为pixmap 。

QWizard 在显示页面时会使用这些位图。实际使用的位图取决于wizard style 。

还可以通过QWizardPage::setPixmap() 为特定页面设置像素图。

另请参阅 pixmap()、QWizardPage::setPixmap() 以及Elements of a Wizard Page 。

void QWizard::setSideWidget(QWidget *widget)

将指定的widget 设置为显示在向导的左侧。对于使用WatermarkPixmap 的样式（ClassicStyle 和ModernStyle ），侧边小部件将显示在水印上方；对于其他样式，或者未提供水印时，侧边小部件将显示在向导的左侧。

若传入nullptr ，则不显示侧边小部件。

当widget 不是nullptr 时，向导会重新设置其父元素。

任何先前的侧边小部件都会被隐藏。

您可以在不同时间调用 setSideWidget() 并传入相同的控件。

除非您在设置其他侧边小部件（或 `nullptr`）后单独重新设置该小部件的父级，否则向导在销毁时会删除此处设置的所有小部件。

默认情况下，不存在侧边小部件。

另请参阅 sideWidget()。

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

重写了：QDialog::setVisible （bool visible）。

QWidget *QWizard::sideWidget() const

返回向导左侧的小部件，或nullptr 。

默认情况下，不存在侧边小部件。

另请参阅 setSideWidget()。

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

重新实现了：QDialog::sizeHint() const。

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

如果指定的option 已启用，则返回true ；否则，返回false。

另请参阅 options 、setOption() 和setWizardStyle()。

[virtual] bool QWizard::validateCurrentPage()

当用户点击Next 或Finish 时，QWizard 会调用此虚拟函数，以执行一些最后时刻的验证。如果它返回true ，则显示下一页（或向导结束）；否则，当前页面保持显示。

默认实现会在调用currentPage() 时调用QWizardPage::validatePage()。

在可能的情况下，通常更好的做法是禁用“Next ”或“Finish ”按钮（通过指定mandatory fields 或重写QWizardPage::isComplete()），而不是重写validateCurrentPage()。

另请参阅 QWizardPage::validatePage() 和currentPage()。

QList<int> QWizard::visitedIds() const

返回已访问页面的 ID 列表，按访问页面的顺序排列。

另请参阅 hasVisitedPage()。