En esta página

QWizardPage Class

La clase QWizardPage es la clase base para las páginas del asistente. Más información...

Encabezado: #include <QWizardPage>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: QWidget

Propiedades

Funciones públicas

QWizardPage(QWidget *parent = nullptr)
virtual ~QWizardPage()
QString buttonText(QWizard::WizardButton which) const
virtual void cleanupPage()
virtual void initializePage()
bool isCommitPage() const
virtual bool isComplete() const
bool isFinalPage() const
virtual int nextId() const
QPixmap pixmap(QWizard::WizardPixmap which) const
void setButtonText(QWizard::WizardButton which, const QString &text)
void setCommitPage(bool commitPage)
void setFinalPage(bool finalPage)
void setPixmap(QWizard::WizardPixmap which, const QPixmap &pixmap)
void setSubTitle(const QString &subTitle)
void setTitle(const QString &title)
QString subTitle() const
QString title() const
virtual bool validatePage()

Señales

Funciones protegidas

QVariant field(const QString &name) const
void registerField(const QString &name, QWidget *widget, const char *property = nullptr, const char *changedSignal = nullptr)
void setField(const QString &name, const QVariant &value)
QWizard *wizard() const

Descripción detallada

QWizard representa un asistente. Cada página es una QWizardPage. Al crear tus propios asistentes, puedes utilizar QWizardPage directamente o crear una subclase de la misma para tener un mayor control.

Una página tiene los siguientes atributos, que son representados por ` QWizard`: un ` title`, un ` subTitle` y un ` set of pixmaps`. Consulte ` Elements of a Wizard Page ` para obtener más detalles. Una vez que se añade una página al asistente (utilizando ` QWizard::addPage()` o ` QWizard::setPage()`), ` wizard()` devuelve un puntero al objeto ` QWizard ` asociado.

La clase `Page` proporciona cinco funciones virtuales que pueden reimplementarse para ofrecer un comportamiento personalizado:

  • initializePage() se invoca para inicializar el contenido de la página cuando el usuario hace clic en el botón « Next » del asistente. Si se desea que el valor por defecto de la página se derive de lo que el usuario ha introducido en páginas anteriores, esta es la función que hay que reimplementar.
  • cleanupPage() se invoca para restablecer el contenido de la página cuando el usuario hace clic en el botón « Back » del asistente.
  • validatePage() valida la página cuando el usuario hace clic en « Next » o « Finish ». Suele utilizarse para mostrar un mensaje de error si el usuario ha introducido información incompleta o no válida.
  • nextId() devuelve el ID de la página siguiente. Resulta útil cuando se utilizan « creating non-linear wizards », que permiten diferentes rutas de navegación en función de la información proporcionada por el usuario.
  • isCompleteSe invoca () para determinar si los botones « Next » y/o « Finish » deben estar habilitados o deshabilitados. Si reimplementas isComplete(), asegúrate también de que se emita completeChanged() cada vez que cambie el estado de «completo».

Normalmente, los botones « Next » y « Finish » de un asistente son mutuamente excluyentes. Si isFinalPage() devuelve true, Finish estará disponible; en caso contrario, Next estará disponible. Por defecto, isFinalPage() es verdadero solo cuando nextId() devuelve -1. Si desea mostrar Next y Final simultáneamente en una página (permitiendo al usuario realizar una «finalización anticipada»), llame a setFinalPage(verdadero) en esa página. Para los asistentes que admiten finalizaciones anticipadas, es posible que también desee configurar las opciones HaveNextButtonOnLastPage y HaveFinishButtonOnEarlyPages en el asistente.

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 método ` "field" mechanism ` que permite registrar un campo (por ejemplo, ` QLineEdit`) en una página y acceder a su valor desde cualquier página. Los campos son globales para todo el asistente y facilitan que cualquier página pueda acceder a la información almacenada por otra página, sin tener que incluir toda la lógica en QWizard ni que las páginas se conozcan explícitamente entre sí. Los campos se registran mediante registerField() y se puede acceder a ellos en cualquier momento mediante field() y setField().

Véase también QWizard, Ejemplo de asistente trivial y Ejemplo de asistente de licencia.

Documentación sobre propiedades

subTitle : QString

Esta propiedad contiene el subtítulo de la página

El subtítulo se muestra mediante la propiedad ` QWizard`, entre el título y el contenido de la página. Los subtítulos son opcionales. En ClassicStyle y ModernStyle, es necesario utilizar subtítulos para que aparezca el encabezado. En MacStyle, el subtítulo se muestra como una etiqueta de texto justo encima del contenido de la página.

El subtítulo puede ser texto sin formato o HTML, dependiendo del valor de la propiedad « QWizard::subTitleFormat ».

Por defecto, esta propiedad contiene una cadena vacía.

Funciones de acceso:

QString subTitle() const
void setSubTitle(const QString &subTitle)

Véase también title, QWizard::IgnoreSubTitles y Elements of a Wizard Page.

title : QString

Esta propiedad contiene el título de la página

El título aparece en la barra de direcciones ( QWizard), encima de la página propiamente dicha. Todas las páginas deben tener un título.

El título puede ser texto sin formato o HTML, dependiendo del valor de la propiedad « QWizard::titleFormat ».

Por defecto, esta propiedad contiene una cadena vacía.

Funciones de acceso:

QString title() const
void setTitle(const QString &title)

Véase también « subTitle » y « Elements of a Wizard Page ».

Documentación de funciones de miembro

[explicit] QWizardPage::QWizardPage(QWidget *parent = nullptr)

Crea una página de asistente con el parent especificado.

Cuando la página se inserta en un asistente mediante QWizard::addPage() o QWizard::setPage(), el elemento padre se establece automáticamente como el asistente.

Véase también wizard().

[virtual noexcept] QWizardPage::~QWizardPage()

Destructor.

QString QWizardPage::buttonText(QWizard::WizardButton which) const

Devuelve el texto del botón « which » de esta página.

Si se ha establecido un texto mediante setButtonText(), se devuelve dicho texto. De lo contrario, si se ha establecido un texto mediante QWizard::setButtonText(), se devuelve dicho texto.

Por defecto, el texto de los botones depende de la configuración de « QWizard::wizardStyle ». Por ejemplo, en macOS, el botón « Next » se denomina « Continue ».

Véanse también setButtonText(), QWizard::buttonText() y QWizard::setButtonText().

[virtual] void QWizardPage::cleanupPage()

QWizard::cleanupPage() invoca esta función virtual cuando el usuario abandona la página haciendo clic en Back (a menos que se haya activado la opción QWizard::IndependentPages ).

La implementación por defecto restablece los campos de la página a sus valores originales (los valores que tenían antes de que se llamara a initializePage()).

Véase también QWizard::cleanupPage(), initializePage() y QWizard::IndependentPages.

[signal] void QWizardPage::completeChanged()

Esta señal se emite cada vez que cambia el estado «complete» de la página (es decir, el valor de ` isComplete()`).

Si reimplementas isComplete(), asegúrate de emitir completeChanged() cada vez que cambie el valor de isComplete(), para garantizar que QWizard actualice el estado de activación o desactivación de sus botones.

Véase también isComplete().

[protected] QVariant QWizardPage::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. Equivale a llamar a wizard()->field(name).

Ejemplo:

        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);

Véase también QWizard::field(), setField() y registerField().

[virtual] void QWizardPage::initializePage()

QWizard::initializePage() llama a esta función virtual para preparar la página 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 activa 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. 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);
}

La implementación predeterminada no hace nada.

Véase también QWizard::initializePage(), cleanupPage() y QWizard::IndependentPages.

bool QWizardPage::isCommitPage() const

Devuelve « true » si esta página es una página de confirmación; en caso contrario, devuelve « false ».

Véase también setCommitPage().

[virtual] bool QWizardPage::isComplete() const

QWizard llama a esta función virtual para determinar si el botón Next o Finish debe estar activado o desactivado.

La implementación por defecto devuelve true si todos los campos de mandatory fields están rellenados; en caso contrario, devuelve false.

Si reimplementas esta función, asegúrate de emitir completeChanged(), desde el resto de tu implementación, cada vez que cambie el valor de isComplete(). Esto garantiza que QWizard actualice el estado de activación o desactivación de sus botones. Aquí puedes encontrar un ejemplo de la reimplementación.

Véase también completeChanged() y isFinalPage().

bool QWizardPage::isFinalPage() const

QWizard llama a esta función para determinar si debe mostrarse o no el botón « Finish » en esta página.

Por defecto, devuelve true si no hay página siguiente (es decir, nextId() devuelve -1); en caso contrario, devuelve false.

Al llamar explícitamente a setFinalPage(true), se permite al usuario realizar una «finalización anticipada».

Véanse también isComplete() y QWizard::HaveFinishButtonOnEarlyPages.

[virtual] int QWizardPage::nextId() const

QWizard::nextId() 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.

Por defecto, esta función devuelve el ID más bajo mayor que el de la página actual, o -1 si no existe tal ID.

Al reimplementar esta función, puedes especificar un orden dinámico de las páginas. Por ejemplo:

int IntroPage::nextId() const
{
    if (evaluateRadioButton->isChecked()) {
        return LicenseWizard::Page_Evaluate;
    } else {
        return LicenseWizard::Page_Register;
    }
}

Véase también ` QWizard::nextId()`.

QPixmap QWizardPage::pixmap(QWizard::WizardPixmap which) const

Devuelve el mapa de píxeles establecido para el rol « which ».

Los mapas de píxeles también se pueden establecer para todo el asistente mediante QWizard::setPixmap(), en cuyo caso se aplican a todas las páginas que no especifiquen un mapa de píxeles.

Véanse también setPixmap(), QWizard::pixmap() y Elements of a Wizard Page.

[protected] void QWizardPage::registerField(const QString &name, QWidget *widget, const char *property = nullptr, const char *changedSignal = nullptr)

Crea un campo denominado « name » asociado a la propiedad « property » de la página « widget » indicada. A partir de ese momento, se podrá acceder a dicha propiedad mediante « field()» y « setField()».

Los campos son globales para todo el asistente y facilitan que cualquier página pueda acceder a la información almacenada por otra página, sin tener que incluir toda la lógica en QWizard ni que las páginas se conozcan explícitamente entre sí.

Si name termina con un asterisco (*), el campo es obligatorio. Cuando una página tiene campos obligatorios, los botones « Next » y/o « Finish » solo se activan cuando se han rellenado todos los campos obligatorios. Esto requiere que se especifique un changedSignal, para indicar a QWizard que vuelva a comprobar el valor almacenado por el campo obligatorio.

QWizard Reconoce los widgets más comunes de Qt Widgets. Para estos (o sus subclases), no es necesario especificar un ` property ` ni un ` changedSignal`. En la tabla siguiente se enumeran estos widgets:

Puedes utilizar QWizard::setDefaultProperty() para añadir entradas a esta tabla o para sobrescribir entradas existentes.

Para considerar que un campo está «relleno», ` QWizard ` simplemente comprueba que su valor actual no sea igual a su valor original (el valor que tenía antes de que se llamara a ` initializePage()`). En el caso de ` QLineEdit`, también comprueba que ` hasAcceptableInput()` devuelva «true», para respetar cualquier validador o máscara.

QWizardEl mecanismo de campos obligatorios se proporciona por comodidad. Se puede omitir reimplementando QWizardPage::isComplete().

Véanse también field(), setField() y QWizard::setDefaultProperty().

void QWizardPage::setButtonText(QWizard::WizardButton which, const QString &text)

Establece el texto del botón « which » como « text » en esta página.

Por defecto, el texto de los botones depende de ` QWizard::wizardStyle`, pero se puede redefinir para todo el asistente utilizando ` QWizard::setButtonText()`.

Véanse también buttonText(), QWizard::setButtonText() y QWizard::buttonText().

void QWizardPage::setCommitPage(bool commitPage)

Establece esta página como página de confirmación si commitPage es verdadero; en caso contrario, la establece como una página normal.

Una página de confirmación es una página que representa una acción que no se puede deshacer haciendo clic en « Back » o « Cancel ».

En una página de confirmación, el botón « Commit » sustituye al botón « Next ». Al hacer clic en este botón, simplemente se llama a QWizard::next(), igual que al hacer clic en Next.

En una página a la que se accede directamente desde una página de confirmación, el botón « Back » aparece desactivado.

Véase también isCommitPage().

[protected] void QWizardPage::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. Equivale a llamar a wizard()->setField(name, value).

Véase también QWizard::setField(), field() y registerField().

void QWizardPage::setFinalPage(bool finalPage)

Establece explícitamente esta página como final si finalPage es verdadero.

Tras llamar a setFinalPage(true), isFinalPage() devuelve true y el botón « Finish » aparece visible (y habilitado si isComplete() devuelve true).

Tras llamar a setFinalPage(false), isFinalPage() devuelve true si nextId() devuelve -1; en caso contrario, devuelve false.

Véase también isFinalPage(), isComplete() y QWizard::HaveFinishButtonOnEarlyPages.

void QWizardPage::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 todo el asistente mediante QWizard::setPixmap(), en cuyo caso se aplican a todas las páginas que no especifiquen un mapa de píxeles.

Véase también pixmap(), QWizard::setPixmap() y Elements of a Wizard Page.

[virtual] bool QWizardPage::validatePage()

QWizard::validateCurrentPage() llama a esta función virtual cuando el usuario hace clic en Next o 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, la página actual permanece abierta.

La implementación predeterminada devuelve true.

Siempre que sea posible, suele ser mejor desactivar el botón « Next » o « Finish » (especificando « mandatory fields » o reimplementando « isComplete()») que reimplementar «validatePage()».

Véase también QWizard::validateCurrentPage() y isComplete().

[protected] QWizard *QWizardPage::wizard() const

Devuelve el asistente asociado a esta página, o nullptr si esta página aún no se ha insertado en un QWizard.

Véase también QWizard::addPage() y QWizard::setPage().

© 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.