QWizard 代表一个向导。每个页面都是一个 QWizardPage。
Page 提供了五个可以重新实现以提供自定义行为的虚函数：
通常，向导的 Next 按钮和 Finish 按钮是互斥的。如果 isFinalPage() 返回 true，则 Finish 可用；否则，Next 可用。默认情况下，isFinalPage() 仅在 nextId() 返回 -1 时为 true。如果想同时显示页面的 Next 和 Final（让用户执行“提前完成”），请在该页面上调用 setFinalPage(true)。对于支持提前完成的向导，可能还需要在向导上设置 HaveNextButtonOnLastPage 和 HaveFinishButtonOnEarlyPages 选项。
在许多向导中，页面内容可能会影响后续页面字段的默认值。为了方便页面之间的通信，QWizard 支持“字段（field）”机制，允许在页面上注册字段（例如，QLineEdit）并从任何页面访问其值。字段对整个向导是全局的，使任何单个页面都可以轻松访问另一个页面存储的信息，而无需将所有逻辑放入 QWizard 或让页面明确了解彼此。字段使用 registerField() 注册，并且可以随时使用 field() 和 setField() 访问。
1、subTitle : QString
页面的副标题
副标题由 QWizard 显示，位于标题和实际页面之间。在 ClassicStyle 和 ModernStyle 中，必须使用副标题才能使标题出现。在 MacStyle 中，副标题显示为实际页面上方的文本标签。
副标题可能是纯文本或 HTML，取决于 QWizard::subTitleFormat 属性的值。
2、title : QString
页面的标题。
标题由 QWizard 显示，位于实际页面上方。所有页面都应该有一个标题。
标题可能是纯文本或 HTML，取决于 QWizard::titleFormat 属性的值。
1、QWizardPage(QWidget *parent = nullptr)
构造具有给定父级的向导页面。
当使用 QWizard::addPage() 或 QWizard::setPage() 将页面插入到 QWizard 中时，父页面会自动设置为QWizard。
2、void completeChanged()
只要页面的完整状态（即 isComplete() 的值）发生变化，就会发出此信号。
如果重新实现 isComplete()，请确保在 isComplete() 的值更改时发出 completeChanged()，以确保 QWizard 更新其按钮的启用或禁用状态。
3、QString buttonText(QWizard::WizardButton which)
返回此页面上的按钮上的文本。
文本可使用 setButtonText() 或 QWizard::setButtonText() 设置。
默认情况下，按钮上的文本取决于 QWizard::wizardStyle。 例如，在 macOS 上，“下一步”按钮称为“继续”。
4、【virtual】 void cleanupPage()
当用户通过单击返回离开页面时，QWizard::cleanupPage() 调用此虚函数（除非设置了 QWizard::IndependentPages 选项）。
默认实现将页面的字段（field）重置为其原始值（原始值是在调用 initializePage() 之前它们具有的值）。
5、【protected】 QVariant field(const QString &name)
返回名为 name 的字段的值。
此功能可用于访问向导任何页面上的字段。相当于调用 wizard()->field(name)。
【protected】 void setField(const QString &name, const QVariant &value)
设置字段的值。
此功能可用于在向导的任何页面上设置字段。相当于调用 wizard()->setField(name, value)。
6、【virtual】 void initializePage()
此虚函数由 QWizard::initializePage() 调用，以在页面显示之前准备页面，或者作为调用 QWizard::restart() 的结果，或者作为用户单击 Next 按钮的结果。（但是，如果设置了 QWizard::IndependentPages 选项，则仅在第一次显示页面时调用此函数。）
默认什么都不做。重新实现此功能，可确保页面的字段根据之前页面的字段正确初始化。
例如：
void OutputFilesPage::initializePage() { QString className = field("className").toString(); headerLineEdit->setText(className.toLower() + ".h"); implementationLineEdit->setText(className.toLower() + ".cpp"); outputDirLineEdit->setText(QDir::toNativeSeparators(QDir::tempPath())); }
7、bool isCommitPage()
此页面是否提交页面。
8、【virtual】 bool isComplete()
QWizard 调用此虚函数来确定是否应启用或禁用 Next 或 Finish 按钮。
如果填写了所有必填字段，则默认实现返回 true；否则，它返回 false。
如果重新实现此函数，请确保在 isComplete() 的值发生变化时从其余的实现中发出 completeChanged()。这确保 QWizard 更新其按钮的启用或禁用状态。
9、bool isFinalPage()
QWizard 调用此函数来确定是否应为此页面显示 Finish 按钮。
默认情况下，如果没有下一页，则返回 true（即 nextId() 返回 -1）； 否则，返回 false。
通过显式调用 setFinalPage(true)，可以让用户执行“提前完成”。
10、【virtual】 int nextId()
这个虚函数由 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;
}
}11、QPixmap pixmap(QWizard::WizardPixmap which)
void setPixmap(QWizard::WizardPixmap which, const QPixmap &pixmap)
设置 QWizard 在显示页面时使用像素图。
也可以使用 QWizard::setPixmap() 为整个向导设置像素图，在这种情况下，它们适用于所有未指定像素图的页面。
12、void 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 重新检查强制字段存储的值。
常见的 Qt 小部件其子类无需指定属性或 changedSignal。下面是这些小部件：
可以使用 QWizard::setDefaultProperty() 将条目添加到此表或覆盖现有条目。
13、void setButtonText(QWizard::WizardButton which, const QString &text)
设置按钮上的文本。
14、void setCommitPage(bool commitPage)
如果 commitPage 为 true，则将此页面设置为提交页面；否则，将其设置为普通页面。
提交页面是表示无法通过单击“返回”或“取消”来撤消的操作的页面。
提交按钮替换提交页面上的 Next 按钮。
15、void setFinalPage(bool finalPage)
如果 finalPage 为 true，则显式将此页面设置为最终页面。
16、【virtual】bool validatePage()
当用户单击 Next 或 Finish 以执行信息验证时，QWizard::validateCurrentPage() 调用此虚函数。 如果返回 true，则显示下一页（或向导结束）； 否则，当前页面保持不变。
默认实现返回 true。
如果可能，禁用 Next 或 Finish 按钮（通过指定必填字段或重新实现 isComplete()）通常比重新实现 validatePage() 更好。
17、QWizard *wizard()
返回与此页面关联的向导。
向导是一种特殊类型的输入对话框，由一系列页面组成。向导的目的是引导用户逐步完成一个过程。
QWizard 继承 QDialog 并表示一个向导。每个页面都是一个 QWizardPage。
以下示例说明了如何创建向导页面并将它们添加到向导。
#include <QApplication>
#include <QWizardPage>
#include <QLabel>
#include <QVBoxLayout>
#include <QLineEdit>
QWizardPage *createIntroPage()
{
QWizardPage *page = new QWizardPage;
page->setTitle("介绍");
QLabel *label = new QLabel("此向导将帮助您注册产品");
label->setWordWrap(true);
QVBoxLayout *layout = new QVBoxLayout;
layout->addWidget(label);
page->setLayout(layout);
return page;
}
QWizardPage *createRegistrationPage()
{
QWizardPage *page = new QWizardPage;
page->setTitle("注册");
QLabel *label = new QLabel("注册码：");
QLineEdit * lineEdit = new QLineEdit();
QHBoxLayout *layout = new QHBoxLayout;
layout->addWidget(label);
layout->addWidget(lineEdit);
page->setLayout(layout);
return page;
}
QWizardPage *createConclusionPage()
{
QWizardPage *page = new QWizardPage;
page->setTitle("完成");
QLabel *label = new QLabel("注册完成");
QVBoxLayout *layout = new QVBoxLayout;
layout->addWidget(label);
page->setLayout(layout);
return page;
}
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QWizard wizard;
wizard.addPage(createIntroPage());
wizard.addPage(createRegistrationPage());
wizard.addPage(createConclusionPage());
wizard.setWindowTitle("Trivial Wizard");
wizard.show();
return app.exec();
}
QWizard 支持四种向导外观：
向导由一系列 QWizardPages 组成。在任何时候，只显示一页。一个页面具有以下属性：
enum QWizard::WizardPixmap：
下图显示了 QWizard 如何呈现这些属性，假设它们都存在并且使用了 ModernStyle：
如果向导的样式是 MacStyle，则页面看起来完全不同：
在许多向导中，页面内容可能会影响后续页面字段的默认值。为了方便页面之间的通信，QWizard 支持“字段”机制，允许在页面上注册字段并从任何页面访问其值。还可以指定必填字段（即，在用户进入下一页之前必须填写的字段）。
调用 QWizardPage::registerField() 注册字段。例如：
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 ¯o"));
registerField("className*", classNameLineEdit);
registerField("baseClass", baseClassLineEdit);
registerField("qobjectMacro", qobjectMacroCheckBox);
...
}上面的代码注册了三个字段，className、baseClass和qobjectMacro，分别与三个子 widget 相关联。className 旁边的星号 (*) 表示必填字段。
任何页面的字段都可以从任何其他页面访问。 例如：
void OutputFilesPage::initializePage()
{
QString className = field("className").toString();
headerLineEdit->setText(className.toLower() + ".h");
implementationLineEdit->setText(className.toLower() + ".cpp");
outputDirLineEdit->setText(QDir::toNativeSeparators(QDir::tempPath()));
}调用 QWizardPage::field() 来访问 className 字段的内容。
当页面具有必填字段时，只有在填写了所有必填字段后，才会启用下一步和/或完成按钮。
QWizard 只需检查该字段的当前值是否不等于原始值（它在调用 initializePage() 时具有的值）。对于 QLineEdit 和 QAbstractSpinBox 子类，QWizard 还检查 hasAcceptableInput() 是否返回 true，以支持任何验证器或掩码。
QWizard 提供了的强制字段机制。一个更强大（但也更麻烦）的替代方法是重新实现 QWizardPage::isComplete() 并在页面变得完整或不完整时发出 QWizardPage::completeChanged() 信号。
Next 和/或 Finish 按钮的启用/禁用状态是对用户输入执行验证的一种方式。另一种方法是重新实现 validateCurrentPage()（或 QWizardPage::validatePage()）以执行验证（如果用户输入了不完整或无效的信息，则显示错误消息）。如果函数返回 true，则显示 Next（或向导结束）；否则，当前页面保持不变。
大多数向导具有线性结构，第 1 页后跟第 2 页，以此类推，直到最后一页。使用 QWizard，通过实例化 QWizardPages 并使用 addPage() 插入它们来创建线性向导。默认情况下，页面按添加顺序显示。例如：
ClassWizard::ClassWizard(QWidget *parent)
: QWizard(parent)
{
addPage(new IntroPage);
addPage(new ClassInfoPage);
addPage(new CodeStylePage);
addPage(new OutputFilesPage);
addPage(new ConclusionPage);
...
}当一个页面即将显示时，QWizard 调用 initializePage()（它又调用 QWizardPage::initializePage()）来用默认值填充页面。默认情况下，此函数什么都不做，但可以重新实现它以根据其他页面的字段初始化页面的内容。
如果用户按下 Back，则调用 cleanupPage()（它又调用 QWizardPage::cleanupPage()）。默认实现将页面的字段重置为其原始值（在调用 initializePage() 之前它们具有的值）。如果希望后退按钮是非破坏性的并保留用户输入的值，只需启用 IndependentPages 选项。
一些向导更复杂，因为它们允许基于用户提供的信息的不同遍历路径。
在复杂的向导中，页面由 ID 标识。这些 ID 通常使用枚举定义。 例如：
class LicenseWizard : public QWizard
{
...
enum { Page_Intro,
Page_Evaluate,
Page_Register,
Page_Details,
Page_Conclusion };
...
};页面是使用 setPage() 插入的，它接受一个 ID 和一个 QWizardPage（或子类）的实例：
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);
...
}默认情况下，页面按 ID 递增顺序显示。为了提供取决于用户选择的选项的动态顺序，必须重新实现 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;
}也可以将所有逻辑放在一个地方，在 QWizard::nextId() 重新实现中。例如：
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;
}
}要从具有最低 ID 的页面以外的另一个页面开始，请调用 setStartId()。
要测试页面是否已被访问，请调用 hasVisitedPage()。例如：
void ConclusionPage::initializePage()
{
QString licenseText;
if (wizard()->hasVisitedPage(LicenseWizard::Page_Evaluate)) {
licenseText = tr("<u>评估许可协议：</u> "
"您可以使用此软件 30 天并进行一次备份，但不允许分发它。");
} else if (wizard()->hasVisitedPage(LicenseWizard::Page_Details)) {
licenseText = tr("<u>首次许可协议：</u> "
"您可以根据您将通过电子邮件收到的许可证来使用此软件。");
} else {
licenseText = tr("<u>升级许可协议：</u> "
"本软件根据您当前的许可条款获得许可。");
}
bottomLabel->setText(licenseText);
}1、enum QWizard::WizardButton：此枚举指定向导中的按钮：
2、enum QWizard::WizardOption：此枚举指定影响向导外观的各种选项：
3、enum QWizard::WizardPixmap：此枚举指定可以与页面关联的像素图：
4、enum QWizard::WizardStyle：此枚举指定了 QWizard 支持的不同外观：
1、【只读】currentId : const int
当前页面的ID。
2、options : WizardOptions
影响向导外观的各种选项。
3、startId : int
第一页的 ID。
如果未明确设置此属性，则默认为该向导中的最低页面 ID，如果尚未插入页面，则为 -1。
4、subTitleFormat : Qt::TextFormat
子标题使用的文本格式。默认为 Qt::AutoText。
- Qt::PlainText：纯文本字符串。
- Qt::RichText：富文本字符串。
- Qt::AutoText：自动检测。
- Qt::MarkdownText：Markdown 格式的文本。
5、titleFormat : Qt::TextFormat
标题使用的文本格式。默认为 Qt::AutoText。
6、wizardStyle : WizardStyle
向导的外观。
1、void back()
返回上一页。相当于按下 Back 按钮。
void next()
前进到下一页。
这相当于按下 Next 或 Commit 按钮。
2、【信号】void currentIdChanged(int id)
此信号在当前页面更改时发出，参数为新的当前 id。
3、【信号】void customButtonClicked(int which)
当用户单击自定义按钮时会发出此信号。可以是 CustomButton1、CustomButton2 或 CustomButton3。
4、【信号】void helpRequested()
当用户单击帮助按钮时会发出此信号。
默认情况下，不显示帮助按钮。调用 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);
}5、【信号】void pageAdded(int id)
每当向向导添加页面时都会发出此信号。页面的 id 作为参数传递。
【信号】void pageRemoved(int id)
每当从向导中删除页面时都会发出此信号。页面的 id 作为参数传递。
6、void restart()
在开始页面重新启动向导。显示向导时会自动调用此函数。
7、int addPage(QWizardPage *page)
添加页面到向导，并返回页面的 ID。该 ID 保证大于 QWizard 中的任何其他 ID。
8、QAbstractButton * button(QWizard::WizardButton which)
返回与角色 which 对应的按钮。
void setButton(QWizard::WizardButton which, QAbstractButton *button)
设置按钮对应角色的按钮。
要向向导添加额外的按钮（例如，打印按钮），可以使用 CustomButton1 到 CustomButton3 调用 setButton()，并使用 HaveCustomButton1 到 HaveCustomButton3 选项使按钮可见。
void setButtonLayout(const QList<QWizard::WizardButton> &layout)
将按钮显示的顺序设置为 layout。
默认布局取决于设置的选项（例如，是否 HelpButtonOnRight）。 如果需要比已经提供的选项更多地控制按钮的布局，则可以调用此函数。
可以使用 Stretch 在布局中指定水平拉伸。
MyWizard::MyWizard(QWidget *parent)
: QWizard(parent)
{
...
QList<QWizard::WizardButton> layout;
layout << QWizard::Stretch << QWizard::BackButton << QWizard::CancelButton
<< QWizard::NextButton << QWizard::FinishButton;
setButtonLayout(layout);
...
}9、QString buttonText(QWizard::WizardButton which)
返回按钮上的文本。如果使用 setButtonText() 设置了文本，则返回该文本。
默认按钮上的文本取决于 wizardStyle。例如 在 macOS 上，“下一步”按钮称为“继续”。
void setButtonText(QWizard::WizardButton which, const QString &text)
设置按钮上的文本。
也可以使用 QWizardPage::setButtonText() 在每页的基础上设置按钮文本。
10、void cleanupPage(int id)
这个虚函数被 QWizard 调用以在用户通过单击 Back 离开它之前清理页面 id（除非设置了 IndependentPages 选项）。
默认实现在 page(id) 上调用 QWizardPage::cleanupPage()。
11、QWizardPage * currentPage()
返回指向当前页面的指针，如果没有当前页面（例如，在显示向导之前），则返回 nullptr。
这相当于调用 page(currentId())。
12、QVariant field(const QString &name)
返回名为 name 的字段的值。此功能可用于访问向导任何页面上的字段。
13、bool hasVisitedPage(int id)
返回页面历史记录是否包含页面 id。按 Back 将当前页面再次标记为“未访问”。
14、void initializePage(int id)
这个虚函数被 QWizard 调用以在页面 id 显示之前准备页面 id，或者作为调用 restart() 的结果，或者作为用户单击 Next 的结果。（但是，如果设置了 IndependentPages 选项，则仅在第一次显示页面时调用此函数。）
通过重新实现此功能，可以确保页面的字段根据之前页面的字段正确初始化。
默认实现在 page(id) 上调用 QWizardPage::initializePage()。
15、int nextId()
QWizard 调用这个虚函数来找出当用户单击 Next 按钮时要显示的页面。
返回值为下一页的 ID，如果没有后续页面，则返回 -1。
默认实现在 currentPage() 上调用 QWizardPage::nextId()。
通过重新实现此函数，可以指定动态页面顺序。
16、QWizardPage *page(int id)
返回具有给定 id 的页面。
17、QList<int> pageIds()
返回页面 ID 列表。
18、QPixmap pixmap(QWizard::WizardPixmap which)
返回为角色 which 设置的像素图。
19、void removePage(int id)
删除具有给定 id 的页面。
注意：删除页面可能会影响 startId 属性的值。
20、void setDefaultProperty(const char *className, const char *property, const char *changedSignal)
将 className 的默认属性设置为 property，并将关联的更改信号设置为 changedSignal。
当 className （或其子类之一）的实例传递给 QWizardPage::registerField() 并且未指定任何属性时，使用默认属性。
21、void setField(const QString &name, const QVariant &value)
将名为 name 的字段的值设置为 value。此功能可用于在向导的任何页面上设置字段。
22、void setOption(QWizard::WizardOption option, bool on = true)
如果 on 为true，则将给定选项设置为启用；否则，清除给定的选项。
bool testOption(QWizard::WizardOption option)
是否启用了相应选项。
23、void setPage(int id, QWizardPage *page)
将给定页面添加到具有给定 ID 的向导。
24、void setPixmap(QWizard::WizardPixmap which, const QPixmap &pixmap)
设置角色的像素图设置为像素图。
也可以使用 QWizardPage::setPixmap() 为特定页面设置像素图。
25、void setSideWidget(QWidget *widget) / QWidget * sideWidget()
设置显示在向导的侧面小部件。对于使用 WatermarkPixmap（ClassicStyle 和 ModernStyle）的样式，侧面小部件显示在水印顶部，对于其他样式，侧面小部件显示在向导的左侧。
默认情况下，不存在任何侧面小部件。
26、bool validateCurrentPage()
当用户单击 Next 或 Finish 以执行验证时，QWizard 会调用此虚拟函数。如果返回 true，则显示下一页（或向导结束）； 否则，当前页面保持不变。
默认实现在 currentPage() 上调用 QWizardPage::validatePage()。
如果可能，禁用 Next 或 Finish 按钮（通过指定必填字段或通过重新实现 QWizardPage::isComplete()）通常比重新实现 validateCurrentPage() 更好。
27、QList<int> visitedIds()
按照页面被访问的顺序返回已访问页面的 ID 列表。