16-窗口、窗口控件、对话框以及相关功能类- 向导对话框QWizard

向导对话框QWizard

向导对话框 QWizard 由多页构成,可以引导客户按步骤完成某项工作

向导对话框在 ModernStyle 风格界面中,对话框的顶部是横幅(banner),横幅中有标题、子标题和logo,左侧是水印区(watermark),底部有一排按钮,右侧是向导页的内容

在MacStyle风格界面中,顶部没有 logo.左侧用背景(background)代替。

与其他对话框不同的是,向导对话框由多页构成,同一时间只能显示其中的一页,单击next按或 Back 按钮可以向后或向前显示其他页。

对话框中的页是向导页WizzrdPage.向导页有自己的布局和控件,向导会为向导页分配从0开始的ID号

向导对话框QWizard 是从QDialog类继承来的,QWizardPage 是从QWidget类继承来的,用QWizard 类和QWizardPage类创建实例对象的方法如下所示:

from PySide6.QtWidgets import QWizard,QWizardPage

QWizard(parent: Union[PySide6.QtWidgets.QWidget,NoneType]=None,flags: PySide6.QtCore.Qt.WindowType=Default(Qt.WindowFlags))-> None
QWizardPage(parent: Union[PySide6.QtWidgets.QWidget,NoneType]=None)-> None

向导对话框QWizard

向导对话框QWizard的说明

向导(在macOS上也称为助手)是一种特殊类型的输入对话框,由一系列页面组成。向导的目的是引导用户一步一步地完成流程。向导对于用户可能难以学习的复杂或不频繁的任务非常有用。
QWizard继承了QDialog并表示一个向导。每个页面都是一个QWizardPage(一个QWidget子类)。要创建自己的向导,可以直接使用这些类,也可以将它们子类化以获得更多控制。

一个微不足道的例子

以下示例说明了如何创建向导页面并将其添加到向导中。有关更高级的示例,请参阅类向导和许可证向导。

createIntroPage = QWizardPage()

    page = QWizardPage()
    page.setTitle("Introduction")
    label = QLabel("This wizard will help you register your copy"()
"of Super Product Two.")
    label.setWordWrap(True)
    layout = QVBoxLayout()
    layout.addWidget(label)
    page.setLayout(layout)
    return page
createRegistrationPage = QWizardPage()...
createConclusionPage = QWizardPage()
createConclusionPage = QWizardPage()...
if __name__ =="__main__":

向导外观

QWizard支持四种向导外观:

• ClassicStyle
• ModernStyle
• MacStyle
• AeroStyle

您可以使用setWizardStyle()显式地设置要使用的外观(例如,如果您希望在所有平台上使用相同的外观)。

注意:AeroStyle仅在启用alpha合成的Windows Vista系统上有效。当不满足此条件时,使用ModernStyle作为回退。
除了向导样式之外,还有几个选项可以控制向导的外观。这些可以使用setOption()或setOptions()进行设置。例如,HaveHelpButton使QWizard显示帮助按钮以及其他向导按钮。
您甚至可以使用setButtonLayout()将向导按钮的顺序更改为任意顺序,并且最多可以向按钮行添加三个自定义按钮(例如,打印按钮)。这是通过使用CustomButton1、CustomButton2或CustomButton3调用setButton()或setButtonText()来设置按钮,并通过启用HaveCustomButton 1、HaveCustomButton 2或HaveCustomButton3选项来实现的。每当用户单击自定义按钮时,就会发出customButtonClicked()。例如:

wizard().setButtonText(QWizard.CustomButton1,tr("Print"))
wizard().setOption(QWizard.HaveCustomButton1,True)
connect(wizard(),QWizard.customButtonClicked,
        self.printButtonClicked)

向导页面的元素

向导由一系列QWizardPage s组成。在任何时候,都只显示一个页面。页面具有以下属性:

• 标题。
• 一个子标题。
• 一组像素图,根据向导的风格,可以使用也可以不使用:
  • 水印Pixmap(由ClassicStyle和ModernStyle使用)
  • BannerPixmap(由ModernStyle使用)
  • LogoPixmap(ClassicStyle和ModernStyle使用)
  • 背景像素图(由MacStyle使用)

下图显示了QWizard如何渲染这些属性,假设它们都存在并且使用了ModernStyle:

设置子标题时,QWizard会将其显示在标题中,在这种情况下,它还会使用BannerPixmap和LogoPixmap来装饰标题。WatermarkPixmap显示在标题下方的左侧。在底部,有一排按钮,允许用户在页面中导航。
页面本身(QWizardPage小部件)占据了页眉、水印和按钮行之间的区域。通常,页面是一个QWizardPage,上面安装了QGridLayout,带有标准的子窗口小部件(QLabel s、QLineEdit s等)。
如果向导的样式是MacStyle,则页面看起来完全不同:

MacStyle会忽略水印、横幅和徽标像素图。如果设置了BackgroundPixmap,它将用作向导的背景；否则,将使用默认的"助理"图像。
标题和副标题是通过在各个页面上调用setTitle()和setSubTitle()来设置的。它们可以是纯文本或HTML(请参阅标题格式和子标题格式)。可以使用setPixmap()为整个向导全局设置像素图,也可以使用set皮克斯图()按页面设置。

注册和使用字段

在许多向导中,页面的内容可能会影响后面页面字段的默认值。为了方便页面之间的通信,QWizard支持"字段"机制,允许您在页面上注册字段(例如QLineEdit),并从任何页面访问其值。还可以指定必填字段(即,在用户进入下一页之前必须填写的字段)。
要注册字段,请调用registerField()字段。例如:

def __init__(self,parent):
    super().__init__(parent)...
classNameLabel = QLabel(tr("Class name:"))
classNameLineEdit = QLineEdit()
classNameLabel.setBuddy(classNameLineEdit)
baseClassLabel = QLabel(tr("Base class:"))
baseClassLineEdit = QLineEdit()
baseClassLabel.setBuddy(baseClassLineEdit)
qobjectMacroCheckBox = QCheckBox(tr("Generate Q_OBJECT macro"))registerField("className*",classNameLineEdit)
registerField("baseClass",baseClassLineEdit)
registerField("qobjectMacro",qobjectMacroCheckBox)...

上面的代码注册了三个字段,className、baseClass和qobjectMacro,它们与三个子窗口小部件相关联。className旁边的星号(*)表示一个必填字段。

任何页面的字段都可以从任何其他页面访问。例如:

def initializePage(self):

    className = field("className").toString()
    headerLineEdit.setText(className.toLower()+".h")
    implementationLineEdit.setText(className.toLower()+".cpp")
    outputDirLineEdit.setText(QDir.toNativeSeparators(QDir.tempPath()))

在这里,我们调用field()来访问className字段(在ClassInfoPage中定义)的内容,并使用它来初始化OutputFilePage。字段的内容将作为QVariant返回。
当我们使用registerField()创建字段时,我们会传递一个唯一的字段名和一个小部件。我们还可以提供一个Qt属性名称和一个"更改"信号(当属性更改时发出的信号)作为第三和第四参数；然而,对于最常见的Qt小部件,如QLineEdit、QCheckBox和QComboBox,这是不必要的,因为QWizard知道要查找哪些属性。

如果在注册属性时在名称后附加星号(*),则该字段为必填字段。当页面具有必填字段时,只有在填写了所有必填字段后,“下一步"和/或"完成"按钮才会启用。
为了考虑字段"已填充”,QWizard只需检查字段的当前值是否等于原始值(调用initializePage()时的值)。对于QLineEdit和QAbstractSpinBox子类,QWizard还检查hasAcceptableInput()是否返回true,以尊重任何验证器或掩码。
QWizard的强制字段机制是为了方便起见而提供的。一个更强大(但也更麻烦)的替代方案是重新实现isComplete(),并在页面变得完整或不完整时发出completeChanged()信号。
"下一步"和/或"完成"按钮的启用/禁用状态是对用户输入执行验证的一种方式。另一种方法是重新实现validateCurrentPage()(或validatePage()),以执行最后一刻的验证(如果用户输入的信息不完整或无效,则显示错误消息)。如果函数返回true,则显示下一页(或向导结束)；否则,当前页面将保持打开状态。

创建线性向导

大多数向导都是线性结构,第1页后面跟着第2页,以此类推,直到最后一页。类向导示例就是这样一个向导。使用QWizard,通过实例化QWizardPage并使用addPage()插入它们来创建线性向导。默认情况下,页面按添加顺序显示。例如:

def __init__(self,parent):
    super().__init__(parent)

    addPage(IntroPage())
    addPage(ClassInfoPage())
    addPage(CodeStylePage())
    addPage(OutputFilesPage())
    addPage(ConclusionPage())...

当一个页面即将显示时,QWizard调用initializePage()(它反过来调用initializePage())来用默认值填充页面。默认情况下,此函数不执行任何操作,但可以重新实现它,以基于其他页面的字段初始化页面的内容(请参阅上面的示例)。
如果用户按下Back,则会调用cleanupPage()(这反过来又调用cleanup Page())。默认实现将页面的字段重置为其原始值(调用initializePage()之前的值)。如果您希望"后退"按钮是非破坏性的,并保留用户输入的值,只需启用IndependentPages选项即可。

创建非线性向导

有些向导更为复杂,因为它们允许根据用户提供的信息提供不同的遍历路径。许可证向导示例说明了这一点。它提供了五个向导页面；根据所选择的选项,用户可以访问不同的页面。

在复杂的向导中,页面由ID标识。这些ID通常使用枚举进行定义。例如:

class LicenseWizard(QWizard):            ...
enum { Page_Intro,Page_Evaluate,Page_Register,Page_Details,
       Page_Conclusion }            ...

页面是使用setPage()插入的,它接受一个ID和QWizardPage(或子类)的实例:

def __init__(self,parent):
    super().__init__(parent)...

默认情况下,页面以递增的ID顺序显示。要提供取决于用户选择的选项的动态顺序,我们必须重新实现nextId()。例如:

def nextId(self):
def nextId(self):

    return LicenseWizard.Page_Conclusion
def nextId(self):

    if upgradeKeyLineEdit.text().isEmpty():
        return LicenseWizard.Page_Details
    else:
        return LicenseWizard.Page_Conclusion
def nextId(self):

    return LicenseWizard.Page_Conclusion
def nextId(self):

    return -1

在nextId()的重新实现中,也可以将所有逻辑放在一个地方。例如:

def nextId(self):

    switch(currentId()){
    elif ret == Page_Intro:
        if field("intro.evaluate").toBool():
            return Page_Evaluate
        else:
            return Page_Register

    elif ret == Page_Evaluate:
        return Page_Conclusion
    elif ret == Page_Register:
        if field("register.upgradeKey").toString().isEmpty():
            return Page_Details
        else:
            return Page_Conclusion

    elif ret == Page_Details:
        return Page_Conclusion
    elif ret == Page_Conclusion:
    else:
        return -1

要从ID最低的页面以外的另一个页面开始,请调用setStartId()。
要测试页面是否已被访问,请调用hasVisitedPage()。例如:

def initializePage(self):

    licenseText = QString()
    if wizard().hasVisitedPage(LicenseWizard.Page_Evaluate):
        licenseText = tr("Evaluation License Agreement:"
"You can use self software for 30 days and make one"
"backup,but you are not allowed to distribute it.")
     elif wizard().hasVisitedPage(LicenseWizard.Page_Details):
        licenseText = tr("First-Time License Agreement:"
"You can use self 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.")

    bottomLabel.setText(licenseText)

向导对话框QWizard的属性

属性	描述	访问功能
currentId: int	此属性保存当前页面的ID。 无法直接设置此属性。要更改当前页面,请调用next()、back()或restart()。 默认情况下,此属性的值为-1,表示当前未显示任何页面。	currentId() setCurrentId(id) Signal currentIdChanged(id)
options: WizardOptions	此属性包含影响向导外观的各种选项。 默认情况下,会设置以下选项(具体取决于平台): Windows:帮助按钮打开右侧。 macOS:NoDefaultButton和NoCancelButton。 X11和QWS(用于嵌入式Linux的Qt):无。	options() setOptions(options)
startId: int	此属性保存第一页的ID。 如果未显式设置此属性,则此属性默认为此向导中的最低页面ID,如果尚未插入页面,则为-1。	startId() setStartId(id)
subTitleFormat: TextFormat	此属性保存页面字幕使用的文本格式。 默认格式为"自动图文集"。	subTitleFormat() setSubTitleFormat(format)
titleFormat: TextFormat	此属性保存页面标题使用的文本格式。 默认格式为"自动图文集"。	titleFormat() setTitleFormat(format)
wizardStyle: WizardStyle	此属性保留向导的外观。 默认情况下,QWizard在启用alpha合成的Windows Vista系统上使用AeroStyle,而不考虑当前的小部件样式。如果不是这种情况,默认的向导样式取决于当前的小部件样式,如下所示:如果当前小部件样式为QMacStyle,则MacStyle为默认样式；如果当前小程序样式为QWindowsStyle,则ModernStyle为默认范围；在所有其他情况下,ClassicStyle为默认。	wizardStyle() setWizardStyle(style)

向导对话框QWizard的枚举值

• PySide6.QtCore.Qt.TextFormat

  此枚举用于可以显示纯文本和富文本的小部件,例如QLabel。它用于决定文本字符串应该被解释为一个还是另一个。这通常是通过将其中一个枚举值传递给QTextEdit::setTextFormat()函数来完成的。

  Constant	Description
  Qt.PlainText	文本字符串被解释为纯文本字符串。
  Qt.RichText	文本字符串被解释为富文本字符串。有关富文本的定义,请参阅支持的HTML子集。
  Qt.AutoText	如果mightBeRichText()返回true,则文本字符串解释为Qt::RichText,否则解释为Qp::PlainText。
  Qt.MarkdownText	文本字符串被解释为Markdown格式的文本。此枚举值已添加到问题5.14中。

• PySide6.QtWidgets.QWizard.WizardStyle

  此枚举指定QWizard支持的不同外观。

  QWizard.WizardStyle	描述
  QWizard.ClassicStyle	经典Windows外观
  QWizard.ModernStyle	现代Windows外观
  QWizard.MacStyle	macOS外观
  QWizard.AeroStyle	Windows Aero外观

• PySide6.QtWidgets.QWizard.WizardPixmap

  此枚举指定可以与页面关联的像素图。

  Constant	Description
  QWizard.WatermarkPixmap	ClassicStyle或ModernStyle页面左侧的高像素图
  QWizard.LogoPixmap	ClassicStyle或ModernStyle页眉右侧的小像素图
  QWizard.BannerPixmap	占据ModernStyle页眉背景的像素图
  QWizard.BackgroundPixmap	占据MacStyle向导背景的像素图

• PySide6.QtWidgets.QWizard.WizardOption

  (继承enum.Flag)此枚举指定影响向导外观的各种选项。

  QWizard.WizardOption的取值	说 明
  QWizard.IndependentPages	向导页之间是相互独立的,相互间不传递数据
  QWizard.IgnoreSubTitles	不显示子标题
  QWizard.ExtendedWatermarkPixmap	将水印图片拓展到窗口边缘
  QWizard.NoDefaultButton	不将Next按钮和Finish按钮设置成默认按钮
  QWizard.NoBackButtonOnStartPage	在起始页中不显示Back按钮
  QWizard.NoBackButtonOnLastPage	在最后页中不显示Back按钮
  QWizard.DisabledBackButtonOnLastPage	在最后页中 Back 按钮失效
  QWizard.HaveNextButtonOnLastPage	在最后页中显示失效的Next按钮
  QWizard.HaveFinishButtonOnEarlyPages	在非最后页中显示失效的 Finish 按钮
  QWizard.NoCancelButton	不显示Cancel 按钮
  QWizard.CancelButtonOnLeft	将 Cancel 按钮放到 Back 按钮的左边
  QWizard.HaveHelpButton	显示 Help 按钮
  QWizard.HelpButtonOnRight	将帮助按钮放到右边
  QWizard.HaveCustomButtonl	显示用户自定义的第1个按钮
  QWizard.HaveCustomButton2	显示用户自定义的第2个按钮
  QWizard.HaveCustomButton3	显示用户自定义的第3个按钮
  QWizard.NoCancelButtonOnLastPage	在最后页中不显示Cancel 按钮

• PySide6.QtWidgets.QWizard.WizardButton

  此枚举指定向导中的按钮。

  Qwizard.wizard Button 的取值	说 明	Qwizard.wizard Button 的取值	说 明
  QWizard.BackButton	后退按钮(在macOS上返回)	QWizard.HelpButton	帮助按钮(另请参阅HaveHelpButton)
  QWizard.NextButton	下一步按钮(在macOS上继续)	QWizard.CustomButtonl	第一个用户定义的按钮(另请参阅HaveCustomButton1)
  QWizard.CommitButton	"提交"按钮	QWizard.CustomButton2	第二个用户定义按钮(另请参阅HaveCustomButton2)
  QWizard.FinishButton	完成按钮(在macOS上完成)	QWizard.CustomButton3	第三个用户定义按钮(另请参阅HaveCustomButton3)
  QWizard.CancelButton	取消按钮(另请参阅取消按钮)	QWizard.Stretch	该值仅在调用setButtonLayout()时有用: 布局中的水平伸缩器

向导对话框QWizard 常用方法

QWizard的方法及参数类型	返回值的类型	说明
addPage(page: QWizardPage)	int	添加向导页,并返回D号
setPage(id:int,page: QWizardPage)	None	用指定的ID号添加向导页
removePage(id: int)	None	移除ID是int的向导页
currentId()	int	获取当前向导页的ID号
currentPage()	QWizardPage	获取当前向导页
basVisitedPage(int)	bool	获取向导页是否被访问过
[slot]restart()	None	回到初始页
[slot]back()	None	显示上一页
[slot]next()	None	显示下一页
page(id:int)	QWizardPage	获取指定ID号的向导页
pageIds()	ListCint]	获取向导页的ID列表
setButton(which: QWizard.WizardButton,button:QAbstractButton)	None	添加某种用途的按钮
button(QWizard.WizardButton)	QAbstractButton	获取某种用途的按钮
setButtonLayout(Sequence[QWizard.WizardButton])	None	设置按钮的布局(相对位置)
setButtonText(QWizard.WizardButton,str)	None	设置按钮的文本
buttonText(which: QWizard.WizardButton)	str	获取按钮的文本
setField(name:str,value:Any)	None	设置字段的值
field(name: str)	Any	获取字段的值
setOption(QWizard.WizardOption,on=True)	None	设置向导对话框的选项
options()	WizardOptions	获取向导对话框的选项
testOption(QWizard.WizardOption)	bool	测试是否设置了某个选项
setPixmap(which: QWizard.WizardPixmap,pixmap:Union[QPixmap,Qlmage,str])	None	在对话框的指定区域设置图片
pixmap(which: QWizard.WizardPixmap)	QPixmap	获取指定位置处的图片
setSideWidget(QWidget)	None	在向导对话框左侧设置控件
setStartId(id:int)	None	用指定ID号的向导页作为起始页,默认用ID值最小的页作为起始页
startId()	int	获取起始页的ID号
setSubTitleFormat(format: Qt.TextFormat)	None	设置子标题的格式
setTitleFormat(format: Qt.TextFormat)	None	设置标题的格式
setWizardStyle(style:QWizard.WizardStyle)	None	设置向导对话框的风格
wizardStyle()	WizardStyle	获取向导对话框的风格
visitedIds()	ListCint]	获取访问过的向导页ID列表
cleanupPage(id:int)	None	清除内容,恢复默认值
initializePage(id:int)	None	初始化向导页
nextId()	int	获取下一页的ID号
validateCurrentPage()	bool	验证当前页的输入是否正确

向导对话框QWizard的信号

向导对话框 QWizard 的信号如表所示:

QWizard的信号	说 明
currentIdChanged(ID)	当前页发生变化时发送信号,参数是新页的ID
customButtonCIicked(which)	单击自定义按钮时发送信号,参数 which 可能是 CustomButtonl、 CustomButton2 或 CustomButton3
helpRequested()	单击 Help 按钮时发送信号
pageAdded(ID)	添加向导页时发送信号,参数是新页的ID
pageRemoved(ID)	移除向导页时发送信号,参数是被移除页的ID

向导页QWizardPage

from PySide6.QtWidgets import QWizardPage

QWizardPage(parent: Union[PySide6.QtWidgets.QWidget,NoneType] = None)-> None

向导页QWizardPage说明

QWizard代表一个向导。每个页面都是一个QWizardPage。当您创建自己的向导时,您可以直接使用QWizardPage,也可以将其子类化以获得更多控制。
页面具有以下属性,这些属性由QWizard呈现:标题、子标题和一组像素图。有关详细信息,请参阅向导页面的元素。将页面添加到向导后(使用addPage()或setPage()),wizard()将返回一个指向关联QWizard对象的指针。
页面提供了五个虚拟函数,这些函数可以重新实现以提供自定义行为:

• 当用户单击向导的"下一步"按钮时,会调用initializePage()来初始化页面的内容。如果您想从用户在前几页上输入的内容派生页面的默认值,这是要重新实现的函数。
• 当用户单击向导的"后退"按钮时,会调用cleanupPage()来重置页面的内容。
• validatePage()在用户单击"下一步"或"完成"时验证页面。如果用户输入的信息不完整或无效,它通常用于显示错误消息。
• nextId()返回下一页的ID。它在创建非线性向导时很有用,该向导允许根据用户提供的信息提供不同的遍历路径。
• 调用isComplete()来确定是应启用还是禁用"下一步"和/或"完成"按钮。如果重新实现isComplete(),也要确保在完整状态更改时发出completeChanged()。

通常,向导的"下一步"按钮和"完成"按钮是互斥的。如果isFinalPage()返回true,则Finish可用；否则,Next可用。默认情况下,只有当nextId()返回-1时,isFinalPage()才为true。如果您想同时显示页面的Next和Final(让用户执行"提前完成"),请在该页面上调用setFinalPage(true)。对于支持早期完成的向导,您可能还需要在向导上设置HaveNextButtonOnLastPage和HaveFinishButtonOnEarlyPages选项。
在许多向导中,页面的内容可能会影响后面页面字段的默认值。为了方便页面之间的通信,QWizard支持"字段"机制,允许您在页面上注册字段(例如QLineEdit),并从任何页面访问其值。字段对整个向导来说是全局的,使任何一个页面都可以轻松访问另一个页面存储的信息,而不必将所有逻辑都放在QWizard中,也不必让页面明确地了解彼此。字段是使用registerField()注册的,并且可以随时使用field()和setField()访问。

向导页QWizardPage的属性

属性	描述	功能访问
subTitle: str	此属性保留页面的副标题。 字幕由QWizard显示,位于标题和实际页面之间。字幕是可选的。在ClassicStyle和ModernStyle中,必须使用字幕才能显示标题。在MacStyle中,字幕显示为实际页面上方的文本标签。 根据subTitleFormat属性的值,副标题可以是纯文本或HTML。 默认情况下,此属性包含一个空字符串。	subTitle() setSubTitle(subTitle)
title: str	此属性保留页面的标题。 标题由QWizard显示,位于实际页面上方。所有页面都应该有一个标题。 标题可以是纯文本或HTML,具体取决于titleFormat属性的值。 默认情况下,此属性包含一个空字符串。	title() setTitle(title)

向导页QWizardPage的常用方法

QWizardPage的方法及参数类型	返回值的类型	说 明
setButtonText(QWizard.WizardButton,str)	None	设置某种用途按钮的文字
buttonText(which: QWizard.WizardButton)	str	获取指定用途的按钮的文本
setCommitPage(commitPage:bool)	None	设置成提交页
isCommitPage()	bool	获取是否是提交页
setFinalPage(bool)	None	设置成最后页
isFinalPage()	bool	获取是否是最后页
setPixmap(which: QWizard.WizardPixmap,pixmap:QPixmap)	None	在指定区域设置图片
pixmap(which: QWizard.WizardPixmap)	QPixmap	获取指定区域的图片
setSubTitle(subTitle:str)	None	设置子标题
setTitle(title:str)	None	设置标题
subTitle()	str	获取子标题
title()	Str	获取标题
registerField(name: str,widget: QWidget,property: str=None,changedSignal: str=None)	None	创建字段
setField(name: str,value: Any)	None	设置字段的值
field(name:str)	Any	获取字段的值
setDefaultProperty(classNane: str,property: str,changedSignal:str)	None	设置某类控件的某个属性与某个信号相 关联
validatePage()	bool	验证向导页中的输入内容
wizard()	QWizard	获取向导页所在的向导对话框
cleanupPage()	None	清除页面的内容,恢复默认值
initializePage()	None	用于初始化向导页
isComplete()	bool	获取是否完成输人,以便激活Next 按钮或 Finish 按钮
validatePage()	bool	验证向导页中的内容,若为True则显示下 一页
nextId()	int	获取下一页的ID号

向导页QWizardPage的信号

向导页 QWizardPage 只有一个信号completeChanged()

每当页面的完整状态(即isComplete()的值)发生变化时,就会发出此信号。
如果重新实现isComplete(),请确保在isComplete的值发生变化时发出completeChanged(),以确保QWizard更新其按钮的启用或禁用状态。

向导对话框QWizar和向导页QWizardPage主要方法介绍

• 向导对话框属性

  • currentId:int - 当前页面的ID

    无法直接设置此属性。要更改当前页面,请调用next()、back()或restart()。
    默认情况下,此属性的值为-1,表示当前未显示任何页面。

  • options:PySide6.QtWidgets.QWizard.WizardStyle - 影响向导外观的各种选项

    此属性包含影响向导外观的各种选项。枚举值见下
    默认情况下,会设置以下选项(具体取决于平台):

    • Windows: HelpButtonOnRight .
    • macOS: NoDefaultButton and NoCancelButton .
    • X11 and QWS(Qt for Embedded Linux): none.

  • startId:int - 第一页的ID

    此属性保存第一页的ID。
    如果未显式设置此属性,则此属性默认为此向导中的最低页面ID,如果尚未插入页面,则为-1。

  • subTitleFormat:PySide6.QtCore.Qt.TextFormat - 页面字幕使用的文本格式

    此属性保存页面字幕使用的文本格式。TextFormat 枚举值见下方
    默认格式为"AutoText"。

  • titleFormat:PySide6.QtCore.Qt.TextFormat - 页面标题使用的文本格式

    此属性保存页面标题使用的文本格式。TextFormat 枚举值见下方
    默认格式为"AutoText"。

• 向导对话框的风格

  • 用setWizardStyle(style: QWizard.WizardStyle)方法设置,其中参数 style是QWizard,WizardStyle 的枚举值,可以取:

    QWizard.WizardStyle	描述
    QWizard.ClassicStyle	经典Windows外观
    QWizard.ModernStyle	现代Windows外观
    QWizard.MacStyle	macOS外观
    QWizard.AeroStyle	Windows Aero外观

• 添加向导页

  • 用向导对话框的 addPage(page:QWizardPage)方法可以添加向导页,并返回向导页的ID号
  • 也可用setPage(id;int,page:QWizardPage)方法用指定的ID号添加向导页。

• 向导对话框的标题和子标题

  • 向导页的 setTitle(title; str)方法和 setSubTitle(subTitle: str)方法设置标题和子标题

  • 虽然由向导页设置标题和子标题,但是它们会显示在向导对话框的横幅中。

  • 标题和子标题的格式由向导对话框的setTitleFormat(format:Qt.TextFormat)法和 setSubTitleFormat(format:Qt.TextFormat)方法设置,其中参数 format 的取值是 QtTextFormat 举值可以取:

    PySide6.QtCore.Qt.TextFormat

    此枚举用于可以显示纯文本和富文本的小部件,例如QLabel。它用于决定文本字符串应该被解释为一个还是另一个。这通常是通过将其中一个枚举值传递给QTextEdit::setTextFormat()函数来完成的。

    Constant	Description
    Qt.PlainText	文本字符串被解释为纯文本字符串。
    Qt.RichText	文本字符串被解释为富文本字符串。有关富文本的定义,请参阅支持的HTML子集。
    Qt.AutoText	如果mightBeRichText()返回true,则文本字符串解释为Qt::RichText,否则解释为Qp::PlainText。
    Qt.MarkdownText	文本字符串被解释为Markdown格式的文本。此枚举值已添加到问题5.14中。

• 向导对话框的选项由 setOption(QWizard,WizardOption,on=True)方法设置中QWizard.WizardOption 参数是枚举类型,其可以取的值如表所示:

  QWizard.WizardOption的取值	说 明
  QWizard.IndependentPages	向导页之间是相互独立的,相互间不传递数据
  QWizard.IgnoreSubTitles	不显示子标题
  QWizard.ExtendedWatermarkPixmap	将水印图片拓展到窗口边缘
  QWizard.NoDefaultButton	不将Next按钮和Finish按钮设置成默认按钮
  QWizard.NoBackButtonOnStartPage	在起始页中不显示Back按钮
  QWizard.NoBackButtonOnLastPage	在最后页中不显示Back按钮
  QWizard.DisabledBackButtonOnLastPage	在最后页中 Back 按钮失效
  QWizard.HaveNextButtonOnLastPage	在最后页中显示失效的Next按钮
  QWizard.HaveFinishButtonOnEarlyPages	在非最后页中显示失效的 Finish 按钮
  QWizard.NoCancelButton	不显示Cancel 按钮
  QWizard.CancelButtonOnLeft	将 Cancel 按钮放到 Back 按钮的左边
  QWizard.HaveHelpButton	显示 Help 按钮
  QWizard.HelpButtonOnRight	将帮助按钮放到右边
  QWizard.HaveCustomButtonl	显示用户自定义的第1个按钮
  QWizard.HaveCustomButton2	显示用户自定义的第2个按钮
  QWizard.HaveCustomButton3	显示用户自定义的第3个按钮
  QWizard.NoCancelButtonOnLastPage	在最后页中不显示Cancel 按钮

• 显示的图片

  • 向导对话框和向导页都可以用setPixmap(which:QWizard.WizardPixmappixmap:QPixmap)方法设置向导对话框中显示的图片

  • 用向导对话框设置的图片作用于所有页,用向导页设置的图片只作用于向导页所在的页面,其中参 which的取值是QWizard,WizardPixmap 的校举值,用于设置图片放置的位置,可以取:

    PySide6.QtWidgets.QWizard.WizardPixmap此枚举指定可以与页面关联的像素图。

    Constant	Description
    QWizard.WatermarkPixmap	ClassicStyle或ModernStyle页面左侧的高像素图
    QWizard.LogoPixmap	ClassicStyle或ModernStyle页眉右侧的小像素图
    QWizard.BannerPixmap	占据ModernStyle页眉背景的像素图
    QWizard.BackgroundPixmap	占据MacStyle向导背景的像素图

• 往对话框中添加按钮

  • 用setButton(which: QWizard,WizardButton,button:QAbstractButton)方法往对话框中添加某种用途的按钮,其中参数 which 的取值是 QWizard.WizardButton的枚举值,用于指定按钮的用途。QWizard.WizardButton 的取值如表所示。

    Qwizard.wizard Button 的取值	说 明	Qwizard.wizard Button 的取值	说 明
    QWizard.BackButton	Back 按钮	QWizard.HelpButton	Help 按钮
    QWizard.NextButton	Next 按钮	QWizard.CustomButtonl	用户自定义第1个按钮
    QWizard.CommitButton	Commit 按钮	QWizard.CustomButton2	用户自定义第2个按钮
    QWizard.FinishButton	Finish按钮	QWizard.CustomButton3	用户自定义第3个按钮
    QWizard.CancelButton	Cancel按钮	QWizard.Stretch	布局中的水平伸缩器

  • 对话框中最多可以添加3个自定义的按钮,要使自定义按钮可见,还需要用setOption()方法把自定义按钮显示出米。通常情况下 Next 按钮和 Finish 按钮是互斥的

• 提交页

  • 用向导页的 setCommitPage(bool)方法可以把向导页设置成提交页,提交页上用Commit 按钮替换 Next 按钮,且不能用Back 或 Cancel 按钮来撤销。
  • 单击 Commit 按钮后,下一页的 Back 按钮失效。用isCommit()方法可以获取该页是否是提交页

• 把向导页设置成最后页

  • 用向导页的 setFinalPage(bool)方法可以把向导页设置成最后页,最后页上用Finish 按钮替换 Next 按钮,此时用nextld()方法取下一页的ID 时返回-1

• 多个向导页之间的数据通信

  • 向导对话框中的多个向导页之间的数据不能自动进行通信

  • 要实现向导页之间的数据传递,可以将向导页上的控件属性定义成字段,并可以将控件属性与某信号关联这样当属性值发生变化时发送信号,也可以通过字段设置或获取控件的属性值,字段对于向导对话框来说是全局性的。字段的定义通过 registerField(name: str,widget:QWidget,property:str=None,changedSignal: str=None)函数来实现,其中

    • name 是字段名称
    • widget 是向导页上的控件
    • property 是字段的属性
    • changedSignal是与字段属性相关的信号。

    定义好字段后,可以利用setField(name:str,value:Any)方法和 field(name:str)方法设置和获取字段的值。

    用setDefaultProperty(className: str,property: str,changedSignal: str)方法可以设置某类控件的某个属性与某个信号相关联。PySide6 对大多数控件能自动将某个属性与某个信号相关联,如表所示。

    控件	属性	关联的信号
    QAbstractButton	checked	toggled(bool)
    QAbstractSlider	value	valueChanged(int)
    QComboBox	currentIndex	currentIndexChanged(int)
    QDateTimeEdit	dateTime	dateTimeChanged(QDatetime)
    QLLineEdit	text	textChanged(str)
    QListWidget	currentRow	currentRowChanged(int)
    QSpinBox	value	valueChanged(int)

• 当isComplete()函数的返回值为 True 时,会激活 Next 按钮或 Finish 按钮

  可以重写该函数,用户在页面上输入信息后,当满足一定条件时改变 isComplete()的返回值,以便激活 Next 按钮或 Finish 按钮。

  如果重写 isComplete()函数,一定要确保completeChange()信号也能发送

• 用户单击 Next 按钮或 Finish 按后,需要验证页面上输人的内容是否合法

  • 这时会调用向导对话框的 validateCurrentPage()函数和向导页的 validatePage()函数通常需要重写这两个函数以便完成对输人内容的验证,如果返回 True 则显示下一页

• 单击 Next 按钮后,在显示下一页之前,会调用向导页的 initializePage()函数。可以重写该函数,以便根据前面的向导页的内容初始化本向导页的内容。

• 单击 Back 按钮后,在显示前一页之前,会调用向导页的 cleanupPage()函数。可以重写该函数,以保证向导页能恢复默认值。

• 根据 nextId()函数的返回值,决定要显示的下一页,如果没有后续页,则返回-1。单击 next 按钮和 back 按都会调用nextId()函数如果重写该函数会根据已经输入和选择的内容让 nextId()返回相应页的ID号,从而控制页面显示的顺序

向导对话框QWizard 和向导页QWizardPage 的应用实例

下面的程序建立由3个向导页构成的导航对话框,通过单击菜单显示出对话框,用于人学生基本信息、联系方式和考试成绩。

其中第 1个向导页输人姓名和学号,在这个向导页中重写了 isComplete()函数和 validatePage()函数,当姓名和学号中都输人了内容时isComplete()的返回值是True。

这时"下一步"按钮会激活单击"下一步"按钮时,会验学号中输人的内容是否为数字如果是则 validatePage()的返回值是True,显示下一个导航页;

如果不是会弹出警告信息对话框,validatePage()的返回值是 False,不会显示下一个导页。其他向导页也可作类似的处理。在最后一页中单击"完成"按钮,通过字段获取输人的值,并输出到界面上。

import sys
from PySide6.QtWidgets import(QApplication,QWidget,QMenuBar,QPlainTextEdit,QVBoxLayout,QWizard,QWizardPage,QMessageBox,QPushButton,QLineEdit,QFormLayout)


class QWizardPage_1(QWizardPage):  # 第1个向导页类
    def __init__(self,parent=None):
        super().__init__(parent)
        form=QFormLayout(self)
        self.line_name=QLineEdit()
        self.line_number=QLineEdit()
        form.addRow("姓名:",self.line_name)
        form.addRow("学号:",self.line_number)

        self.setTitle("学生成绩输入系统")
        self.setSubTitle("基本信息")

        self.line_name.textChanged.connect(self.isComplete)
        self.line_number.textChanged.connect(self.isComplete)
        self.line_name.textChanged.connect(self.completeChanged_emit)
        self.line_number.textChanged.connect(self.completeChanged_emit)

        self.registerField("name",self.line_name)# 创建字段创建字段#重写isComplete()函数
        self.registerField("number",self.line_number)

    def isComplete(self):  # 重写isComplete()函数
        if self.line_name.text()!=""and self.line_number.text()!="":
            return True
        else:
            return False

    def completeChanged_emit(self):  # 重写isComplete()函数后,需要重新发送信号
        self.completeChanged.emit()

    def validatePage(self):  # 重写validatePage()函数
        if self.line_number.text().isdigit():  # 确保学号中输人的是数字
            return True
        else:
            QMessageBox.warning(self,"警告","输人有误,请检查输人的信息")
            return False


class QWizardPage_2(QWizardPage):  # 第2个向导页类
    def __init__(self,parent=None):
        super().__init__(parent)

        form=QFormLayout(self)
        self.line_telephone=QLineEdit()
        self.line_address=QLineEdit()
        form.addRow("电话:",self.line_telephone)
        form.addRow("地址:",self.line_address)

        self.setTitle("学生成绩输人系统")
        self.setSubTitle("联系方式")
        self.registerField("telephone",self.line_telephone)
        self.registerField("address",self.line_address)


class QWizardPage_3(QWizardPage):
    def __init__(self,parent=None):
        super().__init__(parent)
        form=QFormLayout(self)
        self.line_chinese=QLineEdit()
        self.line_math=QLineEdit()
        self.line_english=QLineEdit()

        form.addRow("语文:",self.line_chinese)
        form.addRow("数学:",self.line_math)
        form.addRow("英语:",self.line_english)

        self.setTitle("学生成绩输入系统")
        self.setSubTitle("考试成绩")

        self.registerField("chinese",self.line_chinese)# 创建字段
        self.registerField("math",self.line_math)# 创建字段
        self.registerField("english",self.line_english)# 创建字段


class QWizard_studentnumber(QWizard):  # 向导对话框

    def __init__(self,parent=None):
        super().__init__(parent)

        self.setWizardStyle(QWizard.WizardStyle.ModernStyle)
        self.addPage(QWizardPage_1(self))# 添加向导页
        self.addPage(QWizardPage_2(self))# 添加向导页
        self.addPage(QWizardPage_3(self))# 添加向导页

        self.btn_back=QPushButton("上一步")
        self.btn_next=QPushButton("下一步")
        self.btn_finish=QPushButton("完成")

        self.setButton(QWizard.WizardButton.BackButton,self.btn_back)# 添加按钮
        self.setButton(QWizard.WizardButton.FinishButton,self.btn_finish)
        self.setButton(QWizard.WizardButton.NextButton,self.btn_next)# 添加按钮

        self.setButtonLayout([self.WizardButton.Stretch,self.WizardButton.BackButton,self.WizardButton.NextButton,self.WizardButton.FinishButton])


class MyWindow(QWidget):
    def __init__(self,parent=None):
        super().__init__(parent)
        self.widget_setupUi()# 建立主界面
        self.wizard=QWizard_studentnumber(self)# 实例化向导对话框
        self.wizard.btn_finish.clicked.connect(self.btn_finish_clicked)# 完成按钮信号与槽的连接

    def widget_setupUi(self):  # 建立主程序界面
        menuBar=QMenuBar(self)# 定义菜单栏
        file_menu=menuBar.addMenu("文件(&F)")# 定义文件菜单
        action_enter=file_menu.addAction("进入")
        action_enter.triggered.connect(self.action_enter_triggered)# 动作的信号与槽函数的连接
        self.plainText=QPlainTextEdit(self)# 显示数据控件

        v=QVBoxLayout(self)# 主界面的布局
        v.addWidget(menuBar)
        v.addWidget(self.plainText)

    def action_enter_triggered(self):
        self.wizard.setStartId(0)
        self.wizard.restart()
        self.wizard.open()

    def btn_finish_clicked(self):  # 单击最后一页的"完成"按钮,输人的数据在plainText中显示
        template="姓名:{}   学号:{}  电话:{}  地址:{}  语文:{}  数学:{}  英语:{}"
        string=template.format(self.wizard.field("name"),self.wizard.field("number"),self.wizard.field("telephone"),self.wizard.field("address"),self.wizard.field("chinese"),self.wizard.field("math"),self.wizard.field("english"))# 获取字段值,格式化输出文本
        self.plainText.appendPlainText(string)


if __name__=='__main__':
    app=QApplication(sys.argv)
    window=MyWindow()
    window.show()
    sys.exit(app.exec())# 动作的槽函数