En esta página

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:

El siguiente diagrama muestra cómo QWizard representa estos atributos, suponiendo que todos estén presentes y que se utilice ModernStyle:

Atributos en una página del asistente

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:

Atributos en una página del asistente utilizando MacStyle

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.

Diagrama de flujo de una página de asistente compleja

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.

ConstanteValorDescripción
QWizard::BackButton0El botón « Back » (Go Back en macOS)
QWizard::NextButton1El botón « Next » (Continue en macOS)
QWizard::CommitButton2El botón « Commit »
QWizard::FinishButton3El botón « Finish » (Done en macOS)
QWizard::CancelButton4El botón « Cancel » (véase también NoCancelButton)
QWizard::HelpButton5El botón « Help » (véase también HaveHelpButton)
QWizard::CustomButton16El primer botón definido por el usuario (véase también HaveCustomButton1)
QWizard::CustomButton27El segundo botón definido por el usuario (véase también HaveCustomButton2)
QWizard::CustomButton38El tercer botón definido por el usuario (véase también HaveCustomButton3)

El siguiente valor solo es útil al llamar a setButtonLayout():

ConstanteValorDescripción
QWizard::Stretch9Un 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.

ConstanteValorDescripción
QWizard::IndependentPages0x00000001Las páginas son independientes entre sí (es decir, no obtienen valores unas de otras).
QWizard::IgnoreSubTitles0x00000002No muestra ningún subtítulo, aunque estén configurados.
QWizard::ExtendedWatermarkPixmap0x00000004Amplía cualquier « WatermarkPixmap » hasta el borde de la ventana.
QWizard::NoDefaultButton0x00000008No establezcas el botón « Next » o « Finish » como el botón de inicio del cuadro de diálogo ( default button).
QWizard::NoBackButtonOnStartPage0x00000010No muestres el botón « Back » en la página de inicio.
QWizard::NoBackButtonOnLastPage0x00000020No muestres el botón Back en la última página.
QWizard::DisabledBackButtonOnLastPage0x00000040Desactivar el botón « Back » en la última página.
QWizard::HaveNextButtonOnLastPage0x00000080Mostrar el botón « Next » (desactivado) en la última página.
QWizard::HaveFinishButtonOnEarlyPages0x00000100Mostrar el botón « Finish » (desactivado) en las páginas que no sean la última.
QWizard::NoCancelButton0x00000200No mostrar el botón « Cancel ».
QWizard::CancelButtonOnLeft0x00000400Coloca el botón « Cancel » a la izquierda de « Back » (en lugar de a la derecha de « Finish » o « Next »).
QWizard::HaveHelpButton0x00000800Muestra el botón « Help ».
QWizard::HelpButtonOnRight0x00001000Coloca el botón « Help » en el extremo derecho de la disposición de botones (en lugar de en el extremo izquierdo).
QWizard::HaveCustomButton10x00002000Mostrar el primer botón definido por el usuario (CustomButton1).
QWizard::HaveCustomButton20x00004000Muestra el segundo botón definido por el usuario (CustomButton2).
QWizard::HaveCustomButton30x00008000Mostrar el tercer botón definido por el usuario (CustomButton3).
QWizard::NoCancelButtonOnLastPage0x00010000No mostrar el botón « Cancel » en la última página.
QWizard::StretchBanner0x00020000Si 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.

ConstanteValorDescripción
QWizard::WatermarkPixmap0El mapa de píxeles alto situado a la izquierda de una página de ClassicStyle o ModernStyle
QWizard::LogoPixmap1El mapa de píxeles pequeño situado a la derecha del encabezado de una página ClassicStyle o ModernStyle
QWizard::BannerPixmap2El mapa de píxeles que ocupa el fondo del encabezado de una página de ModernStyle
QWizard::BackgroundPixmap3El 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.

ConstanteValorDescripción
QWizard::ClassicStyle0Aspecto clásico de Windows
QWizard::ModernStyle1Aspecto moderno de Windows
QWizard::MacStyle2Estilo de macOS
QWizard::AeroStyle3Aspecto 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):

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:

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.