QWizardPage Class

成员函数文档

[explicit] QWizardPage::QWizardPage(QWidget *parent = nullptr)

根据给定的parent 构建一个向导页面。

当使用QWizard::addPage()或QWizard::setPage()将该页面插入向导时，其父级将自动设置为该向导。

另请参阅 wizard()。

[virtual noexcept] QWizardPage::~QWizardPage()

析构函数。

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

返回本页面上which 按钮上的文本。

如果已通过 `setButtonText()` 设置了文本，则返回该文本。否则，如果已通过 `QWizard::setButtonText()` 设置了文本，则返回该文本。

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

另请参阅 setButtonText()、QWizard::buttonText() 和QWizard::setButtonText()。

[virtual] void QWizardPage::cleanupPage()

当用户点击Back 离开页面时，QWizard::cleanupPage()会调用此虚拟函数（除非设置了QWizard::IndependentPages 选项）。

默认实现会将页面的字段重置为原始值（即调用initializePage() 之前的值）。

另请参阅 QWizard::cleanupPage()、initializePage() 和QWizard::IndependentPages 。

[signal] void QWizardPage::completeChanged()

每当页面的“完成”状态（即 `isComplete()` 的值）发生变化时，都会触发此信号。

如果您重写了isComplete() 方法，请确保在isComplete() 的值发生变化时触发 completeChanged() 事件，以确保QWizard 能更新其按钮的启用或禁用状态。

另请参阅 isComplete()。

[protected] QVariant QWizardPage::field(const QString &name) const

返回名为“name ”的字段的值。

此函数可用于访问向导中任意页面的字段。其效果等同于调用wizard()->field(name)。

示例：

        const QString emailAddress = field("details.email").toString();
        licenseText = tr("<u>First-Time License Agreement:</u> "
                         "You can use this software subject to the license "
                         "you will receive by email sent to %1.").arg(emailAddress);

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

[virtual] void QWizardPage::initializePage()

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

通过重写此函数，您可以确保根据前一页面的字段正确初始化当前页面的字段。例如：

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)) {
        const QString emailAddress = field("details.email").toString();
        licenseText = tr("<u>First-Time License Agreement:</u> "
                         "You can use this software subject to the license "
                         "you will receive by email sent to %1.").arg(emailAddress);
    } else {
        licenseText = tr("<u>Upgrade License Agreement:</u> "
                         "This software is licensed under the terms of your "
                         "current license.");
    }
    bottomLabel->setText(licenseText);
}

默认实现不执行任何操作。

另请参阅 QWizard::initializePage()、cleanupPage() 和QWizard::IndependentPages 。

bool QWizardPage::isCommitPage() const

如果该页面是提交页面，则返回true ；否则返回false 。

另请参阅 setCommitPage()。

[virtual] bool QWizardPage::isComplete() const

该虚拟函数由QWizard 调用，用于确定Next 或Finish 按钮应启用还是禁用。

如果所有mandatory fields 都已填写，则默认实现返回true ；否则，返回false 。

如果您重写此函数，请确保在实现的其余部分中，每当 isComplete() 的值发生变化时，都要发出completeChanged()。这可确保QWizard 更新其按钮的启用或禁用状态。此处的示例展示了重写方法。

另请参阅 completeChanged() 和isFinalPage()。

bool QWizardPage::isFinalPage() const

该函数由QWizard 调用，用于确定是否应在此页面上显示“Finish ”按钮。

默认情况下，如果没有下一页（即nextId() 返回 -1），则返回true ；否则，返回false 。

通过显式调用setFinalPage(true)，您可以让用户执行“提前结束”操作。

另请参阅 isComplete() 和QWizard::HaveFinishButtonOnEarlyPages 。

[virtual] int QWizardPage::nextId() const

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

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

默认情况下，该函数返回大于当前页面 ID 的最小 ID；如果不存在这样的 ID，则返回 -1。

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

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

另请参阅 QWizard::nextId()。

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

返回为角色which 设置的位图。

也可以通过QWizard::setPixmap() 为整个向导设置位图，在这种情况下，这些位图将应用于所有未指定位图的页面。

另请参阅 setPixmap()、QWizard::pixmap() 和Elements of a Wizard Page 。

[protected] void QWizardPage::registerField(const QString &name, QWidget *widget, const char *property = nullptr, const char *changedSignal = nullptr)

创建一个名为name 的字段，该字段与给定widget 的property 相关联。此后，可通过field()和setField()访问该属性。

字段在整个向导中是全局的，这使得任何单个页面都能轻松访问由另一个页面存储的信息，而无需将所有逻辑都放在QWizard 中，也无需让各个页面显式地相互了解。

如果name 以星号结尾（例如* ），则该字段为必填字段。当页面包含必填字段时，只有在所有必填字段均已填写后，Next 和/或Finish 按钮才会被启用。这需要指定changedSignal ，以告知QWizard 重新检查必填字段存储的值。

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

您可以使用QWizard::setDefaultProperty() 向该表添加条目或覆盖现有条目。

要将一个字段视为“已填充”，QWizard 仅需检查其当前值是否不等于其原始值（即在调用initializePage() 之前的值）。对于QLineEdit ，它还会检查hasAcceptableInput() 是否返回 true，以遵守任何验证器或掩码。

QWizard的必填字段机制是为了方便而提供的。可以通过重写QWizardPage::isComplete() 来绕过该机制。

另请参阅 field()、setField() 以及QWizard::setDefaultProperty()。

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

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

默认情况下，按钮上的文本取决于QWizard::wizardStyle ，但可以通过QWizard::setButtonText() 函数为整个向导重新定义。

另请参阅 buttonText()、QWizard::setButtonText() 和QWizard::buttonText()。

void QWizardPage::setCommitPage(bool commitPage)

如果commitPage 为真，则将此页面设为提交页面；否则，将其设为普通页面。

提交页面是指其操作无法通过点击“Back ”或“Cancel ”来撤销的页面。

在提交页面上，“Commit ”按钮会取代“Next ”按钮。点击此按钮仅会调用QWizard::next()，其效果与点击Next 相同。

直接从提交页面进入的页面中，“Back ”按钮处于禁用状态。

另请参阅 isCommitPage()。

[protected] void QWizardPage::setField(const QString &name, const QVariant &value)

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

此函数可用于设置向导中任意页面的字段。其效果等同于调用wizard()->setField(name, value)。

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

void QWizardPage::setFinalPage(bool finalPage)

如果 `finalPage ` 为真，则显式地将此页面设为最终页面。

调用 setFinalPage(true) 之后，isFinalPage() 将返回true ，且“Finish ”按钮将显示（若isComplete() 返回 true，则该按钮处于启用状态）。

调用 setFinalPage(false) 后，如果nextId() 返回 -1，则isFinalPage() 返回true ；否则，它返回false 。

另请参阅 isFinalPage()、isComplete() 和QWizard::HaveFinishButtonOnEarlyPages 。

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

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

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

还可以通过QWizard::setPixmap() 为整个向导设置位图，在这种情况下，这些位图将适用于所有未指定位图的页面。

另请参阅 pixmap()、QWizard::setPixmap() 和Elements of a Wizard Page 。

[virtual] bool QWizardPage::validatePage()

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

默认实现返回true 。

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

另请参阅 QWizard::validateCurrentPage() 和isComplete()。

[protected] QWizard *QWizardPage::wizard() const

返回与该页面关联的向导；如果该页面尚未插入到QWizard 中，则返回nullptr 。

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