QWizardPage¶
The
QWizardPage
class is the base class for wizard pages. More…
Synopsis¶
Functions¶
def
buttonText
(which)def
field
(name)def
isCommitPage
()def
isFinalPage
()def
pixmap
(which)def
registerField
(name, widget[, property=None[, changedSignal=None]])def
setButtonText
(which, text)def
setCommitPage
(commitPage)def
setField
(name, value)def
setFinalPage
(finalPage)def
setPixmap
(which, pixmap)def
setSubTitle
(subTitle)def
setTitle
(title)def
subTitle
()def
title
()def
wizard
()
Virtual functions¶
def
cleanupPage
()def
initializePage
()def
isComplete
()def
nextId
()def
validatePage
()
Signals¶
def
completeChanged
()
Detailed Description¶
QWizard
represents a wizard. Each page is aQWizardPage
. When you create your own wizards, you can useQWizardPage
directly, or you can subclass it for more control.A page has the following attributes, which are rendered by
QWizard
: atitle
, asubTitle
, and aset of pixmaps
. SeeElements of a Wizard Page
for details. Once a page is added to the wizard (usingaddPage()
orsetPage()
),wizard()
returns a pointer to the associatedQWizard
object.Page provides five virtual functions that can be reimplemented to provide custom behavior:
initializePage()
is called to initialize the page’s contents when the user clicks the wizard’s Next button. If you want to derive the page’s default from what the user entered on previous pages, this is the function to reimplement.
cleanupPage()
is called to reset the page’s contents when the user clicks the wizard’s Back button.
validatePage()
validates the page when the user clicks Next or Finish. It is often used to show an error message if the user has entered incomplete or invalid information.
nextId()
returns the ID of the next page. It is useful whencreating non-linear wizards
, which allow different traversal paths based on the information provided by the user.
isComplete()
is called to determine whether the Next and/or Finish button should be enabled or disabled. If you reimplementisComplete()
, also make sure thatcompleteChanged()
is emitted whenever the complete state changes.Normally, the Next button and the Finish button of a wizard are mutually exclusive. If
isFinalPage()
returnstrue
, Finish is available; otherwise, Next is available. By default,isFinalPage()
is true only whennextId()
returns -1. If you want to show Next and Final simultaneously for a page (letting the user perform an “early finish”), callsetFinalPage
(true) on that page. For wizards that support early finishes, you might also want to set theHaveNextButtonOnLastPage
andHaveFinishButtonOnEarlyPages
options on the wizard.In many wizards, the contents of a page may affect the default values of the fields of a later page. To make it easy to communicate between pages,
QWizard
supports a"field" mechanism
that allows you to register a field (e.g., aQLineEdit
) on a page and to access its value from any page. Fields are global to the entire wizard and make it easy for any single page to access information stored by another page, without having to put all the logic inQWizard
or having the pages know explicitly about each other. Fields are registered usingregisterField()
and can be accessed at any time usingfield()
andsetField()
.
- class PySide2.QtWidgets.QWizardPage([parent=None])¶
- param parent:
Constructs a wizard page with the given
parent
.When the page is inserted into a wizard using
addPage()
orsetPage()
, the parent is automatically set to be the wizard.See also
- PySide2.QtWidgets.QWizardPage.buttonText(which)¶
- Parameters:
which –
WizardButton
- Return type:
str
Returns the text on button
which
on this page.If a text has ben set using
setButtonText()
, this text is returned. Otherwise, if a text has been set usingsetButtonText()
, this text is returned.By default, the text on buttons depends on the
wizardStyle
. For example, on macOS, the Next button is called Continue.See also
- PySide2.QtWidgets.QWizardPage.cleanupPage()¶
This virtual function is called by
cleanupPage()
when the user leaves the page by clicking Back (unless theIndependentPages
option is set).The default implementation resets the page’s fields to their original values (the values they had before
initializePage()
was called).See also
cleanupPage()
initializePage()
IndependentPages
- PySide2.QtWidgets.QWizardPage.completeChanged()¶
- PySide2.QtWidgets.QWizardPage.field(name)¶
- Parameters:
name – str
- Return type:
object
Returns the value of the field called
name
.This function can be used to access fields on any page of the wizard. It is equivalent to calling
wizard()
->``name`` :meth:` <PySide2.QtWidgets.QWizard.field>` ).Example:
def initializePage(self): className = field("className") self.headerLineEdit.setText(className.lower() + ".h") self.implementationLineEdit.setText(className.lower() + ".cpp") self.outputDirLineEdit.setText(QDir.convertSeparators(QDir.tempPath()))
See also
- PySide2.QtWidgets.QWizardPage.initializePage()¶
This virtual function is called by
initializePage()
to prepare the page just before it is shown either as a result ofrestart()
being called, or as a result of the user clicking Next. (However, if theIndependentPages
option is set, this function is only called the first time the page is shown.)By reimplementing this function, you can ensure that the page’s fields are properly initialized based on fields from previous pages. For example:
def initializePage(self): className = field("className") self.headerLineEdit.setText(className.lower() + ".h") self.implementationLineEdit.setText(className.lower() + ".cpp") self.outputDirLineEdit.setText(QDir.convertSeparators(QDir.tempPath()))
The default implementation does nothing.
See also
initializePage()
cleanupPage()
IndependentPages
- PySide2.QtWidgets.QWizardPage.isCommitPage()¶
- Return type:
bool
Returns
true
if this page is a commit page; otherwise returnsfalse
.See also
- PySide2.QtWidgets.QWizardPage.isComplete()¶
- Return type:
bool
This virtual function is called by
QWizard
to determine whether the Next or Finish button should be enabled or disabled.The default implementation returns
true
if allmandatory fields
are filled; otherwise, it returnsfalse
.If you reimplement this function, make sure to emit
completeChanged()
, from the rest of your implementation, whenever the value of changes. This ensures thatQWizard
updates the enabled or disabled state of its buttons. An example of the reimplementation is available here .See also
- PySide2.QtWidgets.QWizardPage.isFinalPage()¶
- Return type:
bool
This function is called by
QWizard
to determine whether the Finish button should be shown for this page or not.By default, it returns
true
if there is no next page (i.e.,nextId()
returns -1); otherwise, it returnsfalse
.By explicitly calling
setFinalPage
(true), you can let the user perform an “early finish”.See also
isComplete()
HaveFinishButtonOnEarlyPages
- PySide2.QtWidgets.QWizardPage.nextId()¶
- Return type:
int
This virtual function is called by
nextId()
to find out which page to show when the user clicks the Next button.The return value is the ID of the next page, or -1 if no page follows.
By default, this function returns the lowest ID greater than the ID of the current page, or -1 if there is no such ID.
By reimplementing this function, you can specify a dynamic page order. For example:
int IntroPage::nextId() const { if (evaluateRadioButton->isChecked()) { return LicenseWizard::Page_Evaluate; } else { return LicenseWizard::Page_Register; } }
See also
- PySide2.QtWidgets.QWizardPage.pixmap(which)¶
- Parameters:
which –
WizardPixmap
- Return type:
Returns the pixmap set for role
which
.Pixmaps can also be set for the entire wizard using
setPixmap()
, in which case they apply for all pages that don’t specify a pixmap.See also
setPixmap()
pixmap()
Elements of a Wizard Page
- PySide2.QtWidgets.QWizardPage.registerField(name, widget[, property=None[, changedSignal=None]])¶
- Parameters:
name – str
widget –
PySide2.QtWidgets.QWidget
property – str
changedSignal – str
Creates a field called
name
associated with the givenproperty
of the givenwidget
. From then on, that property becomes accessible usingfield()
andsetField()
.Fields are global to the entire wizard and make it easy for any single page to access information stored by another page, without having to put all the logic in
QWizard
or having the pages know explicitly about each other.If
name
ends with an asterisk (*
), the field is a mandatory field. When a page has mandatory fields, the Next and/or Finish buttons are enabled only when all mandatory fields are filled. This requires achangedSignal
to be specified, to tellQWizard
to recheck the value stored by the mandatory field.QWizard
knows the most common Qt widgets. For these (or their subclasses), you don’t need to specify aproperty
or achangedSignal
. The table below lists these widgets:Widget
Property
Change Notification Signal
bool
checked
int
value
int
currentIndex
QDateTime
dateTime
QString
text
int
currentRow
int
value
You can use
setDefaultProperty()
to add entries to this table or to override existing entries.To consider a field “filled”,
QWizard
simply checks that their current value doesn’t equal their original value (the value they had beforeinitializePage()
was called). ForQLineEdit
, it also checks thathasAcceptableInput()
returns true, to honor any validator or mask.QWizard
‘s mandatory field mechanism is provided for convenience. It can be bypassed by reimplementingisComplete()
.See also
- PySide2.QtWidgets.QWizardPage.setButtonText(which, text)¶
- Parameters:
which –
WizardButton
text – str
Sets the text on button
which
to betext
on this page.By default, the text on buttons depends on the
wizardStyle
, but may be redefined for the wizard as a whole usingsetButtonText()
.See also
- PySide2.QtWidgets.QWizardPage.setCommitPage(commitPage)¶
- Parameters:
commitPage – bool
Sets this page to be a commit page if
commitPage
is true; otherwise, sets it to be a normal page.A commit page is a page that represents an action which cannot be undone by clicking Back or Cancel.
A Commit button replaces the Next button on a commit page. Clicking this button simply calls
next()
just like clicking Next does.A page entered directly from a commit page has its Back button disabled.
See also
- PySide2.QtWidgets.QWizardPage.setField(name, value)¶
- Parameters:
name – str
value – object
Sets the value of the field called
name
tovalue
.This function can be used to set fields on any page of the wizard. It is equivalent to calling
wizard()
->``name`` :meth:` <PySide2.QtWidgets.QWizard.setField>` ,value
).See also
- PySide2.QtWidgets.QWizardPage.setFinalPage(finalPage)¶
- Parameters:
finalPage – bool
Explicitly sets this page to be final if
finalPage
is true.After calling (true),
isFinalPage()
returnstrue
and the Finish button is visible (and enabled ifisComplete()
returns true).After calling (false),
isFinalPage()
returnstrue
ifnextId()
returns -1; otherwise, it returnsfalse
.See also
isFinalPage()
isComplete()
HaveFinishButtonOnEarlyPages
- PySide2.QtWidgets.QWizardPage.setPixmap(which, pixmap)¶
- Parameters:
which –
WizardPixmap
pixmap –
PySide2.QtGui.QPixmap
Sets the pixmap for role
which
topixmap
.The pixmaps are used by
QWizard
when displaying a page. Which pixmaps are actually used depend on thewizard style
.Pixmaps can also be set for the entire wizard using
setPixmap()
, in which case they apply for all pages that don’t specify a pixmap.See also
pixmap()
setPixmap()
Elements of a Wizard Page
- PySide2.QtWidgets.QWizardPage.setSubTitle(subTitle)¶
- Parameters:
subTitle – str
This property holds the subtitle of the page.
The subtitle is shown by the
QWizard
, between the title and the actual page. Subtitles are optional. InClassicStyle
andModernStyle
, using subtitles is necessary to make the header appear. InMacStyle
, the subtitle is shown as a text label just above the actual page.The subtitle may be plain text or HTML, depending on the value of the
subTitleFormat
property.By default, this property contains an empty string.
See also
title
IgnoreSubTitles
Elements of a Wizard Page
- PySide2.QtWidgets.QWizardPage.setTitle(title)¶
- Parameters:
title – str
This property holds the title of the page.
The title is shown by the
QWizard
, above the actual page. All pages should have a title.The title may be plain text or HTML, depending on the value of the
titleFormat
property.By default, this property contains an empty string.
See also
subTitle
Elements of a Wizard Page
- PySide2.QtWidgets.QWizardPage.subTitle()¶
- Return type:
str
This property holds the subtitle of the page.
The subtitle is shown by the
QWizard
, between the title and the actual page. Subtitles are optional. InClassicStyle
andModernStyle
, using subtitles is necessary to make the header appear. InMacStyle
, the subtitle is shown as a text label just above the actual page.The subtitle may be plain text or HTML, depending on the value of the
subTitleFormat
property.By default, this property contains an empty string.
See also
title
IgnoreSubTitles
Elements of a Wizard Page
- PySide2.QtWidgets.QWizardPage.title()¶
- Return type:
str
This property holds the title of the page.
The title is shown by the
QWizard
, above the actual page. All pages should have a title.The title may be plain text or HTML, depending on the value of the
titleFormat
property.By default, this property contains an empty string.
See also
subTitle
Elements of a Wizard Page
- PySide2.QtWidgets.QWizardPage.validatePage()¶
- Return type:
bool
This virtual function is called by
validateCurrentPage()
when the user clicks Next or Finish to perform some last-minute validation. If it returnstrue
, the next page is shown (or the wizard finishes); otherwise, the current page stays up.The default implementation returns
true
.When possible, it is usually better style to disable the Next or Finish button (by specifying
mandatory fields
or reimplementingisComplete()
) than to reimplement .See also
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.