QWizard Class
La clase QWizard ofrece un marco de trabajo para los asistentes. Más información...
| Encabezado: | #include <QWizard> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredan: | QDialog |
Tipos públicos
| enum | WizardButton { BackButton, NextButton, CommitButton, FinishButton, CancelButton, …, Stretch } |
| enum | WizardOption { IndependentPages, IgnoreSubTitles, ExtendedWatermarkPixmap, NoDefaultButton, NoBackButtonOnStartPage, …, StretchBanner } |
| flags | WizardOptions |
| enum | WizardPixmap { WatermarkPixmap, LogoPixmap, BannerPixmap, BackgroundPixmap } |
| enum | WizardStyle { ClassicStyle, ModernStyle, MacStyle, AeroStyle } |
Propiedades
|
Funciones públicas
| QWizard(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags()) | |
| virtual | ~QWizard() |
| int | addPage(QWizardPage *page) |
| QAbstractButton * | button(QWizard::WizardButton which) const |
| QString | buttonText(QWizard::WizardButton which) const |
| int | currentId() const |
| QWizardPage * | currentPage() const |
| QVariant | field(const QString &name) const |
| bool | hasVisitedPage(int id) const |
| virtual int | nextId() const |
| QWizard::WizardOptions | options() const |
| QWizardPage * | page(int id) const |
| QList<int> | pageIds() const |
| QPixmap | pixmap(QWizard::WizardPixmap which) const |
| void | removePage(int id) |
| void | setButton(QWizard::WizardButton which, QAbstractButton *button) |
| void | setButtonLayout(const QList<QWizard::WizardButton> &layout) |
| void | setButtonText(QWizard::WizardButton which, const QString &text) |
| void | setDefaultProperty(const char *className, const char *property, const char *changedSignal) |
| void | setField(const QString &name, const QVariant &value) |
| void | setOption(QWizard::WizardOption option, bool on = true) |
| void | setOptions(QWizard::WizardOptions options) |
| void | setPage(int id, QWizardPage *page) |
| void | setPixmap(QWizard::WizardPixmap which, const QPixmap &pixmap) |
| void | setSideWidget(QWidget *widget) |
| void | setStartId(int id) |
| void | setSubTitleFormat(Qt::TextFormat format) |
| void | setTitleFormat(Qt::TextFormat format) |
| void | setWizardStyle(QWizard::WizardStyle style) |
| QWidget * | sideWidget() const |
| int | startId() const |
| Qt::TextFormat | subTitleFormat() const |
| bool | testOption(QWizard::WizardOption option) const |
| Qt::TextFormat | titleFormat() const |
| virtual bool | validateCurrentPage() |
| QList<int> | visitedIds() const |
| QWizard::WizardStyle | wizardStyle() const |
Funciones públicas reimplementadas
| virtual void | setVisible(bool visible) override |
| virtual QSize | sizeHint() const override |
Ranuras públicas
| void | back() |
| void | next() |
| void | restart() |
| void | setCurrentId(int id) |
Señales
| void | currentIdChanged(int id) |
| void | customButtonClicked(int which) |
| void | helpRequested() |
| void | pageAdded(int id) |
| void | pageRemoved(int id) |
Funciones protegidas
| virtual void | cleanupPage(int id) |
| virtual void | initializePage(int id) |
Funciones protegidas reimplementadas
| virtual void | done(int result) override |
| virtual bool | event(QEvent *event) override |
| virtual bool | nativeEvent(const QByteArray &eventType, void *message, qintptr *result) override |
| virtual void | paintEvent(QPaintEvent *event) override |
| virtual void | resizeEvent(QResizeEvent *event) override |
Descripción detallada
Un asistente (también denominado «wizard» en macOS) es un tipo especial de cuadro de diálogo de entrada que consta de una secuencia de páginas. La finalidad de un asistente es guiar al usuario paso a paso a lo largo de un proceso. Los asistentes resultan útiles para tareas complejas o poco frecuentes que a los usuarios les puede resultar difícil aprender.
QWizard hereda de ` QDialog ` y representa un asistente. Cada página es un ` QWizardPage ` (una subclase de ` QWidget `). Para crear tus propios asistentes, puedes utilizar estas clases directamente o crear subclases de las mismas para tener un mayor control.
Un ejemplo sencillo
El siguiente ejemplo ilustra cómo crear páginas de asistente y añadirlas a un asistente. Para ver ejemplos más avanzados, consulta el Asistente de licencia.
QWizardPage *createIntroPage()
{
QWizardPage *page = new QWizardPage;
page->setTitle("Introduction");
QLabel *label = new QLabel("This wizard will help you register your copy "
"of Super Product Two.");
label->setWordWrap(true);
QVBoxLayout *layout = new QVBoxLayout;
layout->addWidget(label);
page->setLayout(layout);
return page;
}
QWizardPage *createRegistrationPage()
{
...
}
QWizardPage *createConclusionPage()
{
...
}
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
#if QT_CONFIG(translation)
QTranslator translator;
for (const QString &trPath : QLibraryInfo::paths(QLibraryInfo::TranslationsPath)) {
if (translator.load(QLocale(), u"qtbase"_s, u"_"_s, trPath)) {
app.installTranslator(&translator);
break;
}
}
#endif
QWizard wizard;
wizard.addPage(createIntroPage());
wizard.addPage(createRegistrationPage());
wizard.addPage(createConclusionPage());
wizard.setWindowTitle("Trivial Wizard");
wizard.show();
return app.exec();
}Aspecto y funcionamiento del asistente
QWizard admite cuatro estilos de asistente:
Puedes establecer explícitamente el estilo que se va a utilizar mediante ` setWizardStyle()` (por ejemplo, si deseas que tenga el mismo aspecto en todas las plataformas).
Nota: AeroStyle solo tiene efecto en un sistema Windows Vista con la composición alfa activada. ModernStyle se utiliza como alternativa cuando no se cumple esta condición.
Además del estilo del asistente, existen varias opciones que controlan el aspecto y el comportamiento del asistente. Estas se pueden configurar mediante setOption() o setOptions(). Por ejemplo, HaveHelpButton hace que QWizard muestre un botón « Help » junto con los demás botones del asistente.
Incluso puedes cambiar el orden de los botones del asistente por cualquier orden arbitrario utilizando setButtonLayout(), y puedes añadir hasta tres botones personalizados (por ejemplo, un botón Print ) a la fila de botones. Esto se consigue llamando a setButton() o setButtonText() con CustomButton1, CustomButton2 o CustomButton3 para configurar el botón, y activando las opciones HaveCustomButton1, HaveCustomButton2 o HaveCustomButton3. Cada vez que el usuario haga clic en un botón personalizado, se emitirá customButtonClicked(). Por ejemplo:
wizard()->setButtonText(QWizard::CustomButton1, tr("&Print"));
wizard()->setOption(QWizard::HaveCustomButton1, true);
connect(wizard(), &QWizard::customButtonClicked,
this, &ConclusionPage::printButtonClicked);Elementos de una página del asistente
Los asistentes constan de una secuencia de QWizardPages. En cada momento, solo se muestra una página. Una página tiene los siguientes atributos:
- Un title.
- Un « subTitle ».
- Un conjunto de mapas de píxeles, que pueden tenerse en cuenta o no, dependiendo del estilo del asistente:
- WatermarkPixmap (utilizados por ClassicStyle y ModernStyle)
- BannerPixmap (utilizado por ModernStyle)
- LogoPixmap (utilizado por ClassicStyle y ModernStyle)
- BackgroundPixmap (utilizado por MacStyle)
El siguiente diagrama muestra cómo QWizard representa estos atributos, suponiendo que todos estén presentes y que se utilice ModernStyle:

Cuando se establece un « subTitle », QWizard lo muestra en un encabezado, en cuyo caso también utiliza el « BannerPixmap » y el « LogoPixmap » para decorar el encabezado. El « WatermarkPixmap » se muestra en la parte izquierda, debajo del encabezado. En la parte inferior, hay una fila de botones que permiten al usuario navegar por las páginas.
La página en sí (el widget QWizardPage ) ocupa el área entre el encabezado, la marca de agua y la fila de botones. Normalmente, la página es un QWizardPage en el que está instalado un QGridLayout, con widgets secundarios estándar (QLabels, QLineEdits, etc.).
Si el estilo del asistente es MacStyle, la página tiene un aspecto radicalmente diferente:

El MacStyle ignora las imágenes de marca de agua, el banner y el logotipo. Si se establece el BackgroundPixmap, se utiliza como fondo del asistente; de lo contrario, se utiliza una imagen predeterminada de «asistente».
El título y el subtítulo se establecen llamando a ` QWizardPage::setTitle()` y ` QWizardPage::setSubTitle()` en cada una de las páginas. Pueden ser texto sin formato o HTML (véase titleFormat y subTitleFormat). Las imágenes se pueden configurar de forma global para todo el asistente utilizando ` setPixmap()`, o por página utilizando ` QWizardPage::setPixmap()`.
Registro y uso de campos
En muchos asistentes, el contenido de una página puede afectar a los valores por defecto de los campos de una página posterior. Para facilitar la comunicación entre páginas, QWizard admite un mecanismo de «campos» que permite registrar un campo (por ejemplo, un QLineEdit) en una página y acceder a su valor desde cualquier página. También es posible especificar campos obligatorios (es decir, campos que deben rellenarse antes de que el usuario pueda pasar a la página siguiente).
Para registrar un campo, llama a la función QWizardPage::registerField() field. Por ejemplo:
registerField("evaluate.name*", nameLineEdit);
registerField("evaluate.email*", emailLineEdit);El código anterior registra tres campos: className, baseClass y qobjectMacro, que están asociados a tres widgets secundarios. El asterisco (*) junto a className indica que se trata de un campo obligatorio.
Se puede acceder a los campos de cualquier página desde cualquier otra página. Por ejemplo:
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);
}Aquí, llamamos a QWizardPage::field() para acceder al contenido del campo details.email (que se definió en DetailsPage) y lo utilizamos para inicializar ConclusionPage. El contenido del campo se devuelve como un QVariant.
Cuando creamos un campo mediante QWizardPage::registerField(), pasamos un nombre de campo único y un widget. También podemos proporcionar un nombre de propiedad de Qt y una señal «changed» (una señal que se emite cuando cambia la propiedad) como tercer y cuarto argumento; sin embargo, esto no es necesario para los widgets de Qt más comunes, como QLineEdit, QCheckBox y QComboBox, ya que QWizard sabe qué propiedades debe buscar.
Si se añade un asterisco (*) al nombre al registrar la propiedad, el campo pasa a ser obligatorio. Cuando una página contiene campos obligatorios, los botones Next y/o Finish solo se activan cuando se han rellenado todos los campos obligatorios.
Para considerar que un campo está «rellenado», QWizard simplemente comprueba que el valor actual del campo no sea igual al valor original (el valor que tenía cuando se llamó a initializePage()). En el caso de las subclases de QLineEdit y QAbstractSpinBox, QWizard también comprueba que hasAcceptableInput() devuelva «true», para respetar cualquier validador o máscara.
El mecanismo de campos obligatorios de QWizard se ofrece para mayor comodidad. Una alternativa más potente (aunque también más engorrosa) consiste en reimplementar ` QWizardPage::isComplete()` y emitir la señal ` QWizardPage::completeChanged()` cada vez que la página se complete o quede incompleta.
El estado activado/desactivado de los botones « Next » y/o « Finish » es una forma de validar los datos introducidos por el usuario. Otra forma es reimplementar ` validateCurrentPage()` (o ` QWizardPage::validatePage()`) para realizar una validación de última hora (y mostrar un mensaje de error si el usuario ha introducido información incompleta o no válida). Si la función devuelve ` true`, se muestra la página siguiente (o finaliza el asistente); de lo contrario, la página actual permanece visible.
Creación de asistentes lineales
La mayoría de los asistentes tienen una estructura lineal, en la que a la página 1 le sigue la página 2 y así sucesivamente hasta la última página. El ejemplo «Trivial Wizard» es un asistente de este tipo. Con QWizard, los asistentes lineales se crean instanciando los objetos ` QWizardPage` e insertándolos mediante ` addPage()` (). Por defecto, las páginas se muestran en el orden en que se han añadido. Por ejemplo:
QWizard wizard;
wizard.addPage(createIntroPage());
wizard.addPage(createRegistrationPage());
wizard.addPage(createConclusionPage());Cuando se va a mostrar una página, QWizard llama a ` initializePage()` (que a su vez llama a ` QWizardPage::initializePage()`) para rellenar la página con valores por defecto. Por defecto, esta función no hace nada, pero se puede reimplementar para inicializar el contenido de la página en función de los campos de otras páginas (véase ` example above`).
Si el usuario pulsa Back, se llama a cleanupPage(), que a su vez llama a QWizardPage::cleanupPage(). La implementación predeterminada restablece los campos de la página a sus valores originales (los valores que tenían antes de que se llamara a initializePage()). Si desea que el botón Back no sea destructivo y conserve los valores introducidos por el usuario, basta con activar la opción IndependentPages.
Creación de asistentes no lineales
Algunos asistentes son más complejos, ya que permiten diferentes rutas de navegación en función de la información proporcionada por el usuario. El ejemplo del asistente de licencias ilustra esto. Ofrece varias páginas del asistente; dependiendo de las opciones seleccionadas, el usuario puede acceder a diferentes páginas.

En los asistentes complejos, las páginas se identifican mediante ID. Estos ID suelen definirse mediante una enumeración. Por ejemplo:
class LicenseWizard : public QWizard
{
...
enum { Page_Intro, Page_Evaluate, Page_Register, Page_Details,
Page_Conclusion };
...
};Las páginas se insertan mediante ` setPage()`, que toma un ID y una instancia de ` QWizardPage ` (o de una subclase):
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);
...
}Por defecto, las páginas se muestran en orden ascendente de ID. Para establecer un orden dinámico que dependa de las opciones elegidas por el usuario, debemos reimplementar ` QWizardPage::nextId()`. Por ejemplo:
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;
}También sería posible reunir toda la lógica en un solo lugar, en una reimplementación de ` QWizard::nextId()`. Por ejemplo:
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;
}
}Para comenzar en una página distinta a la que tiene el ID más bajo, llama a ` setStartId()`.
Para comprobar si una página ha sido visitada o no, llama a ` hasVisitedPage()`. Por ejemplo:
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);
}Véase también ` QWizardPage` , «Ejemplo sencillo del asistente» y «Ejemplo del asistente de licencias».
Documentación sobre tipos de miembros
enum QWizard::WizardButton
Esta enumeración especifica los botones de un asistente.
| Constante | Valor | Descripción |
|---|---|---|
QWizard::BackButton | 0 | El botón « Back » (Go Back en macOS) |
QWizard::NextButton | 1 | El botón « Next » (Continue en macOS) |
QWizard::CommitButton | 2 | El botón « Commit » |
QWizard::FinishButton | 3 | El botón « Finish » (Done en macOS) |
QWizard::CancelButton | 4 | El botón « Cancel » (véase también NoCancelButton) |
QWizard::HelpButton | 5 | El botón « Help » (véase también HaveHelpButton) |
QWizard::CustomButton1 | 6 | El primer botón definido por el usuario (véase también HaveCustomButton1) |
QWizard::CustomButton2 | 7 | El segundo botón definido por el usuario (véase también HaveCustomButton2) |
QWizard::CustomButton3 | 8 | El tercer botón definido por el usuario (véase también HaveCustomButton3) |
El siguiente valor solo es útil al llamar a setButtonLayout():
| Constante | Valor | Descripción |
|---|---|---|
QWizard::Stretch | 9 | Un estiramiento horizontal en el diseño del botón |
Véase también ` setButton()`, ` setButtonText()`, ` setButtonLayout()` y ` customButtonClicked()`.
enum QWizard::WizardOption
flags QWizard::WizardOptions
Esta enumeración especifica diversas opciones que afectan al aspecto y el comportamiento de un asistente.
| Constante | Valor | Descripción |
|---|---|---|
QWizard::IndependentPages | 0x00000001 | Las páginas son independientes entre sí (es decir, no obtienen valores unas de otras). |
QWizard::IgnoreSubTitles | 0x00000002 | No muestra ningún subtítulo, aunque estén configurados. |
QWizard::ExtendedWatermarkPixmap | 0x00000004 | Amplía cualquier « WatermarkPixmap » hasta el borde de la ventana. |
QWizard::NoDefaultButton | 0x00000008 | No establezcas el botón « Next » o « Finish » como el botón de inicio del cuadro de diálogo ( default button). |
QWizard::NoBackButtonOnStartPage | 0x00000010 | No muestres el botón « Back » en la página de inicio. |
QWizard::NoBackButtonOnLastPage | 0x00000020 | No muestres el botón Back en la última página. |
QWizard::DisabledBackButtonOnLastPage | 0x00000040 | Desactivar el botón « Back » en la última página. |
QWizard::HaveNextButtonOnLastPage | 0x00000080 | Mostrar el botón « Next » (desactivado) en la última página. |
QWizard::HaveFinishButtonOnEarlyPages | 0x00000100 | Mostrar el botón « Finish » (desactivado) en las páginas que no sean la última. |
QWizard::NoCancelButton | 0x00000200 | No mostrar el botón « Cancel ». |
QWizard::CancelButtonOnLeft | 0x00000400 | Coloca el botón « Cancel » a la izquierda de « Back » (en lugar de a la derecha de « Finish » o « Next »). |
QWizard::HaveHelpButton | 0x00000800 | Muestra el botón « Help ». |
QWizard::HelpButtonOnRight | 0x00001000 | Coloca el botón « Help » en el extremo derecho de la disposición de botones (en lugar de en el extremo izquierdo). |
QWizard::HaveCustomButton1 | 0x00002000 | Mostrar el primer botón definido por el usuario (CustomButton1). |
QWizard::HaveCustomButton2 | 0x00004000 | Muestra el segundo botón definido por el usuario (CustomButton2). |
QWizard::HaveCustomButton3 | 0x00008000 | Mostrar el tercer botón definido por el usuario (CustomButton3). |
QWizard::NoCancelButtonOnLastPage | 0x00010000 | No mostrar el botón « Cancel » en la última página. |
QWizard::StretchBanner | 0x00020000 | Si hay un banner, extiéndelo a lo ancho de todo el asistente. |
El tipo WizardOptions es un typedef para QFlags<WizardOption>. Almacena una combinación OR de valores de WizardOption.
Véase también setOptions(), setOption() y testOption().
enum QWizard::WizardPixmap
Esta enumeración especifica los mapas de píxeles que se pueden asociar a una página.
| Constante | Valor | Descripción |
|---|---|---|
QWizard::WatermarkPixmap | 0 | El mapa de píxeles alto situado a la izquierda de una página de ClassicStyle o ModernStyle |
QWizard::LogoPixmap | 1 | El mapa de píxeles pequeño situado a la derecha del encabezado de una página ClassicStyle o ModernStyle |
QWizard::BannerPixmap | 2 | El mapa de píxeles que ocupa el fondo del encabezado de una página de ModernStyle |
QWizard::BackgroundPixmap | 3 | El mapa de píxeles que ocupa el fondo de un asistente de MacStyle |
Véase también setPixmap(), QWizardPage::setPixmap() y Elements of a Wizard Page.
enum QWizard::WizardStyle
Esta enumeración especifica los diferentes estilos compatibles con QWizard.
| Constante | Valor | Descripción |
|---|---|---|
QWizard::ClassicStyle | 0 | Aspecto clásico de Windows |
QWizard::ModernStyle | 1 | Aspecto moderno de Windows |
QWizard::MacStyle | 2 | Estilo de macOS |
QWizard::AeroStyle | 3 | Aspecto de Windows Aero |
Véase también setWizardStyle(), WizardOption y Wizard Look and Feel.
Documentación de propiedades
currentId : int
Esta propiedad contiene el ID de la página actual
Por defecto, esta propiedad tiene un valor de -1, lo que indica que actualmente no se muestra ninguna página.
Funciones de acceso:
| int | currentId() const |
| void | setCurrentId(int id) |
Señal del notificador:
| void | currentIdChanged(int id) |
Véase también currentPage().
options : WizardOptions
Esta propiedad contiene las distintas opciones que influyen en el aspecto y el comportamiento del asistente
De forma predeterminada, se configuran las siguientes opciones (dependiendo de la plataforma):
- Windows: HelpButtonOnRight.
- macOS: NoDefaultButton y NoCancelButton.
- X11 y QWS (Qt para Linux embebido): ninguna.
Funciones de acceso:
| QWizard::WizardOptions | options() const |
| void | setOptions(QWizard::WizardOptions options) |
Véase también wizardStyle.
startId : int
Esta propiedad contiene el ID de la primera página
Si esta propiedad no se establece explícitamente, su valor por defecto es el ID de página más bajo de este asistente, o -1 si aún no se ha insertado ninguna página.
Funciones de Access:
| int | startId() const |
| void | setStartId(int id) |
Véase también restart() y nextId().
subTitleFormat : Qt::TextFormat
Esta propiedad contiene el formato de texto utilizado en los subtítulos de las páginas
El formato predeterminado es « Qt::AutoText ».
Funciones de acceso:
| Qt::TextFormat | subTitleFormat() const |
| void | setSubTitleFormat(Qt::TextFormat format) |
Véase también QWizardPage::title y titleFormat.
titleFormat : Qt::TextFormat
Esta propiedad contiene el formato de texto utilizado en los títulos de las páginas
El formato predeterminado es Qt::AutoText.
Funciones de acceso:
| Qt::TextFormat | titleFormat() const |
| void | setTitleFormat(Qt::TextFormat format) |
Véase también QWizardPage::title y subTitleFormat.
wizardStyle : WizardStyle
Esta propiedad determina el aspecto y el comportamiento del asistente
Por defecto, QWizard utiliza el estilo « AeroStyle » en un sistema Windows Vista con la composición alfa activada, independientemente del estilo actual del widget. Si no es así, el estilo predeterminado del asistente depende del estilo actual del widget de la siguiente manera: MacStyle es el predeterminado si el estilo actual del widget es QMacStyle, ModernStyle es el predeterminado si el estilo actual del widget es QWindowsStyle, y ClassicStyle es el predeterminado en todos los demás casos.
Funciones de acceso:
| QWizard::WizardStyle | wizardStyle() const |
| void | setWizardStyle(QWizard::WizardStyle style) |
Véase también Wizard Look and Feel y options.
Documentación de las funciones de miembro
[explicit] QWizard::QWizard(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())
Crea un asistente con el parent y el flags especificados.
Véanse también parent() y windowFlags().
[virtual noexcept] QWizard::~QWizard()
Destruye el asistente y sus páginas, liberando los recursos asignados.
int QWizard::addPage(QWizardPage *page)
Añade el « page » indicado al asistente y devuelve el ID de la página.
Se garantiza que el ID será mayor que cualquier otro ID de la lista « QWizard » hasta el momento.
Véase también setPage(), page() y pageAdded().
[slot] void QWizard::back()
Vuelve a la página anterior.
Esto equivale a pulsar el botón « Back ».
Véase también « next()», « accept()», « reject()» y « restart()».
QAbstractButton *QWizard::button(QWizard::WizardButton which) const
Devuelve el botón correspondiente al rol « which ».
Véase también setButton() y setButtonText().
QString QWizard::buttonText(QWizard::WizardButton which) const
Devuelve el texto del botón « which ».
Si se ha establecido un texto mediante setButtonText(), se devuelve dicho texto.
Por defecto, el texto de los botones depende de wizardStyle. Por ejemplo, en macOS, el botón « Next » se denomina « Continue ».
Véanse también button(), setButton(), setButtonText(), QWizardPage::buttonText() y QWizardPage::setButtonText().
[virtual protected] void QWizard::cleanupPage(int id)
QWizard llama a esta función virtual para limpiar la página id justo antes de que el usuario salga de ella haciendo clic en Back (a menos que se haya activado la opción QWizard::IndependentPages ).
La implementación por defecto llama a QWizardPage::cleanupPage() en la página (id).
Véase también QWizardPage::cleanupPage() y initializePage().
[signal] void QWizard::currentIdChanged(int id)
Esta señal se emite cuando cambia la página actual, con la nueva propiedad « id ».
Nota: Señalde notificación para la propiedad ` currentId`.
Véase también currentId() y currentPage().
QWizardPage *QWizard::currentPage() const
Devuelve un puntero a la página actual o ` nullptr ` si no hay ninguna página actual (por ejemplo, antes de que se muestre el asistente).
Esto equivale a llamar a page(currentId()).
Véase también page(), currentId() y restart().
[signal] void QWizard::customButtonClicked(int which)
Esta señal se emite cuando el usuario hace clic en un botón personalizado. which puede ser CustomButton1, CustomButton2 o CustomButton3.
Por defecto, no se muestra ningún botón personalizado. Llama a ` setOption()` con ` HaveCustomButton1`, ` HaveCustomButton2` o ` HaveCustomButton3 ` para mostrar uno, y utiliza ` setButtonText()` o ` setButton()` para configurarlo.
Véase también helpRequested().
[override virtual protected] void QWizard::done(int result)
Reimplementa: QDialog::done(int r).
[override virtual protected] bool QWizard::event(QEvent *event)
Reimplementa: ` QWidget::event(QEvent *event)`.
QVariant QWizard::field(const QString &name) const
Devuelve el valor del campo denominado « name ».
Esta función se puede utilizar para acceder a los campos de cualquier página del asistente.
Véase también QWizardPage::registerField(), QWizardPage::field() y setField().
bool QWizard::hasVisitedPage(int id) const
Devuelve true si el historial de la página contiene la página id; en caso contrario, devuelve false.
Al pulsar Back, la página actual vuelve a marcarse como «no visitada».
Véase también visitedIds().
[signal] void QWizard::helpRequested()
Esta señal se emite cuando el usuario hace clic en el botón « Help ».
Por defecto, no se muestra ningún botón « Help ». Llama a setOption(HaveHelpButton, true) para que aparezca uno.
Ejemplo:
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);
}Véase también customButtonClicked().
[virtual protected] void QWizard::initializePage(int id)
QWizard llama a esta función virtual para preparar la página id justo antes de que se muestre, ya sea como resultado de la llamada a QWizard::restart() o porque el usuario ha hecho clic en Next. (No obstante, si se ha activado la opción QWizard::IndependentPages, esta función solo se llama la primera vez que se muestra la página).
Al reimplementar esta función, puedes asegurarte de que los campos de la página se inicialicen correctamente en función de los campos de las páginas anteriores.
La implementación predeterminada llama a QWizardPage::initializePage() en la página (id).
Véase también ` QWizardPage::initializePage()` y ` cleanupPage()`.
[override virtual protected] bool QWizard::nativeEvent(const QByteArray &eventType, void *message, qintptr *result)
Reimplementa: ` QWidget::nativeEvent` (`const QByteArray &eventType, void *message, qintptr *result`).
[slot] void QWizard::next()
Pasa a la página siguiente.
Esto equivale a pulsar el botón « Next » o « Commit ».
Véase también nextId(), back(), accept(), reject() y restart().
[virtual] int QWizard::nextId() const
QWizard llama a esta función virtual para determinar qué página mostrar cuando el usuario hace clic en el botón « Next ».
El valor de retorno es el ID de la página siguiente, o -1 si no hay ninguna página posterior.
La implementación predeterminada llama a ` QWizardPage::nextId()` desde ` currentPage()`.
Al reimplementar esta función, puedes especificar un orden dinámico de las páginas.
Véanse también QWizardPage::nextId() y currentPage().
QWizardPage *QWizard::page(int id) const
Devuelve la página con la URL indicada id, o nullptr si no existe dicha página.
Véase también addPage() y setPage().
[signal] void QWizard::pageAdded(int id)
Esta señal se emite cada vez que se añade una página al asistente. Se pasa como parámetro el ` id ` de la página.
Véanse también addPage(), setPage() y startId().
QList<int> QWizard::pageIds() const
Devuelve la lista de ID de página.
[signal] void QWizard::pageRemoved(int id)
Esta señal se emite cada vez que se elimina una página del asistente. El objeto ` id ` de la página se pasa como parámetro.
Véanse también « removePage()» y « startId()».
[override virtual protected] void QWizard::paintEvent(QPaintEvent *event)
Reimplementa: QWidget::paintEvent(QPaintEvent *event).
QPixmap QWizard::pixmap(QWizard::WizardPixmap which) const
Devuelve el mapa de píxeles establecido para el rol « which ».
Por defecto, el único mapa de píxeles establecido es el BackgroundPixmap en macOS.
Véase también setPixmap(), QWizardPage::pixmap() y Elements of a Wizard Page.
void QWizard::removePage(int id)
Elimina la página con el id indicado. Si es necesario, se llamará a cleanupPage().
Nota: La eliminación de una página puede influir en el valor de la propiedad ` startId `.
Véase también addPage(), setPage(), pageRemoved() y startId().
[override virtual protected] void QWizard::resizeEvent(QResizeEvent *event)
Reimplementa: ` QDialog::resizeEvent` (`QResizeEvent *`).
[slot] void QWizard::restart()
Reinicia el asistente desde la página de inicio. Esta función se activa automáticamente cuando se muestra el asistente.
Véase también startId().
void QWizard::setButton(QWizard::WizardButton which, QAbstractButton *button)
Establece el botón correspondiente a la función « which » en « button ».
Para añadir botones adicionales al asistente (por ejemplo, un botón « Print »), una forma de hacerlo es llamar a setButton() con CustomButton1 a CustomButton3 y hacer que los botones sean visibles utilizando las opciones HaveCustomButton1 a HaveCustomButton3.
Véase también button(), setButtonText(), setButtonLayout() y options.
void QWizard::setButtonLayout(const QList<QWizard::WizardButton> &layout)
Establece el orden en el que se muestran los botones en ` layout`, donde ` layout ` es una lista de ` WizardButton`.
La disposición predeterminada depende de las opciones (por ejemplo, si se ha establecido HelpButtonOnRight). Puedes llamar a esta función si necesitas un mayor control sobre la disposición de los botones del que ya ofrece options.
Se pueden especificar los espacios horizontales en el diseño utilizando Stretch.
Ejemplo:
MyWizard::MyWizard(QWidget *parent)
: QWizard(parent)
{
//...
QList<QWizard::WizardButton> layout;
layout << QWizard::Stretch << QWizard::BackButton << QWizard::CancelButton
<< QWizard::NextButton << QWizard::FinishButton;
setButtonLayout(layout);
//...
}Véase también setButton(), setButtonText() y setOptions().
void QWizard::setButtonText(QWizard::WizardButton which, const QString &text)
Establece el texto del botón « which » como « text ».
Por defecto, el texto de los botones depende de wizardStyle. Por ejemplo, en macOS, el botón Next se llama Continue.
Para añadir botones adicionales al asistente (por ejemplo, un botón « Print »), una forma de hacerlo es llamar a setButtonText() con « CustomButton1 », « CustomButton2 » o « CustomButton3 » para establecer su texto, y hacer que los botones sean visibles utilizando las opciones « HaveCustomButton1 », « HaveCustomButton2 » y/o « HaveCustomButton3 ».
Los textos de los botones también se pueden configurar para cada página mediante QWizardPage::setButtonText().
Véanse también buttonText(), setButton(), button(), setButtonLayout(), setOptions() y QWizardPage::setButtonText().
[slot] void QWizard::setCurrentId(int id)
Establece currentId en id, sin pasar por las páginas comprendidas entre currentId y id.
Vuelve sin cambiar de página, si
- el asistente no contiene páginas
- la página actual no es válida
- la página indicada es igual a currentId()
- la página indicada está fuera de rango
Nota: Si se han saltado páginas hacia adelante y id es 0, se eliminará el historial de visitas a las páginas
Nota: Funciónde asignación para la propiedad currentId.
Véase también currentId().
void QWizard::setDefaultProperty(const char *className, const char *property, const char *changedSignal)
Establece la propiedad por defecto de « className » en « property » y la señal de cambio asociada en « changedSignal ».
La propiedad por defecto se utiliza cuando se pasa una instancia de ` className ` (o de una de sus subclases) a ` QWizardPage::registerField()` y no se especifica ninguna propiedad.
QWizard conoce los widgets más comunes de Qt Widgets. Para estos (o sus subclases), no es necesario especificar un ` property ` ni un ` changedSignal`. La tabla siguiente enumera estos widgets:
| Widget | Propiedad | Señal de notificación de cambio |
|---|---|---|
| QAbstractButton | bool checked | toggled() |
| QAbstractSlider | int value | valueChanged() |
| QComboBox | int currentIndex | currentIndexChanged() |
| QDateTimeEdit | QDateTime dateTime | dateTimeChanged() |
| QLineEdit | QString text | textChanged() |
| QListWidget | int currentRow | currentRowChanged() |
| QSpinBox | int value | valueChanged() |
Véase también QWizardPage::registerField().
void QWizard::setField(const QString &name, const QVariant &value)
Establece el valor del campo denominado « name » en « value ».
Esta función se puede utilizar para establecer campos en cualquier página del asistente.
Véase también QWizardPage::registerField(), QWizardPage::setField() y field().
void QWizard::setOption(QWizard::WizardOption option, bool on = true)
Establece que el option especificado esté activado si on es verdadero; en caso contrario, desactiva el option especificado.
Véase también options, testOption() y setWizardStyle().
void QWizard::setPage(int id, QWizardPage *page)
Añade el « page » indicado al asistente con el « id » indicado.
Nota: Añadir una página puede afectar al valor de la propiedad ` startId ` en caso de que no se haya establecido explícitamente.
Véase también addPage(), page() y pageAdded().
void QWizard::setPixmap(QWizard::WizardPixmap which, const QPixmap &pixmap)
Establece el mapa de píxeles para el rol « which » en « pixmap ».
QWizard utiliza los mapas de píxeles al mostrar una página. Los mapas de píxeles que se utilizan realmente dependen de wizard style.
Los mapas de píxeles también se pueden establecer para una página específica mediante QWizardPage::setPixmap().
Véase también pixmap(), QWizardPage::setPixmap() y Elements of a Wizard Page.
void QWizard::setSideWidget(QWidget *widget)
Establece que el « widget » indicado se muestre en el lado izquierdo del asistente. En el caso de los estilos que utilizan la marca de agua « WatermarkPixmap » (ClassicStyle y ModernStyle), el widget lateral se muestra sobre la marca de agua; para otros estilos, o cuando no se ha especificado ninguna marca de agua, el widget lateral se muestra en el lado izquierdo del asistente.
Si se pasa « nullptr », no se muestra ningún widget lateral.
Cuando el widget no es nullptr, el asistente le asigna un nuevo elemento padre.
Cualquier widget lateral anterior queda oculto.
Se puede llamar a `setSideWidget()` con el mismo widget en diferentes momentos.
El asistente eliminará todos los widgets establecidos aquí cuando se destruya, a menos que cambies la pertenencia del widget por separado tras establecer algún otro widget lateral (o un « nullptr »).
Por defecto, no hay ningún widget lateral.
Véase también sideWidget().
[override virtual] void QWizard::setVisible(bool visible)
Reimplementa: ` QDialog::setVisible` (bool visible).
QWidget *QWizard::sideWidget() const
Devuelve el widget situado a la izquierda del asistente o nullptr.
Por defecto, no hay ningún widget lateral.
Véase también setSideWidget().
[override virtual] QSize QWizard::sizeHint() const
Reimplementa: ` QDialog::sizeHint()` const.
bool QWizard::testOption(QWizard::WizardOption option) const
Devuelve « true » si el elemento « option » especificado está habilitado; en caso contrario, devuelve «false».
Véase también options, setOption() y setWizardStyle().
[virtual] bool QWizard::validateCurrentPage()
QWizard llama a esta función virtual cuando el usuario hace clic en Next o en Finish para realizar una validación de última hora. Si devuelve true, se muestra la página siguiente (o finaliza el asistente); de lo contrario, se mantiene la página actual.
La implementación predeterminada llama a QWizardPage::validatePage() desde currentPage().
Siempre que sea posible, suele ser mejor desactivar el botón « Next » o « Finish » (especificando ` mandatory fields ` o reimplementando ` QWizardPage::isComplete()`) que reimplementar `validateCurrentPage()`.
Véase también QWizardPage::validatePage() y currentPage().
QList<int> QWizard::visitedIds() const
Devuelve la lista de los ID de las páginas visitadas, en el orden en que se visitaron.
Véase también hasVisitedPage().
© 2026 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.







