QWizardPage Class

Documentation sur les fonctions membres

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

Construit une page d'assistant avec l'adresse parent.

Lorsque la page est insérée dans un assistant à l'aide de QWizard::addPage() ou QWizard::setPage(), le parent est automatiquement défini comme étant l'assistant.

Voir aussi wizard().

[virtual noexcept] QWizardPage::~QWizardPage()

Destructeur.

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

Renvoie le texte du bouton which de cette page.

Si un texte a été défini à l'aide de setButtonText(), ce texte est renvoyé. Sinon, si un texte a été défini à l'aide de QWizard::setButtonText(), c'est ce texte qui est renvoyé.

Par défaut, le texte des boutons dépend du bouton QWizard::wizardStyle. Par exemple, sous macOS, le bouton Next est appelé Continue.

Voir également setButtonText(), QWizard::buttonText() et QWizard::setButtonText().

[virtual] void QWizardPage::cleanupPage()

Cette fonction virtuelle est appelée par QWizard::cleanupPage() lorsque l'utilisateur quitte la page en cliquant sur Back (sauf si l'option QWizard::IndependentPages est activée).

L'implémentation par défaut réinitialise les champs de la page à leurs valeurs d'origine (les valeurs qu'ils avaient avant l'appel de initializePage()).

Voir également QWizard::cleanupPage(), initializePage() et QWizard::IndependentPages.

[signal] void QWizardPage::completeChanged()

Ce signal est émis chaque fois que l'état complet de la page (c'est-à-dire la valeur de isComplete()) change.

Si vous réimplémentez isComplete(), veillez à émettre completeChanged() chaque fois que la valeur de isComplete() change, afin de vous assurer que QWizard met à jour l'état activé ou désactivé de ses boutons.

Voir également isComplete().

[protected] QVariant QWizardPage::field(const QString &name) const

Renvoie la valeur du champ appelé name.

Cette fonction peut être utilisée pour accéder aux champs de n'importe quelle page de l'assistant. Elle équivaut à appeler wizard()->field(name).

Exemple :

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

Voir également QWizard::field(), setField() et registerField().

[virtual] void QWizardPage::initializePage()

Cette fonction virtuelle est appelée par QWizard::initializePage() pour préparer la page juste avant qu'elle ne soit affichée, soit à la suite de l'appel de QWizard::restart(), soit à la suite du clic de l'utilisateur sur Next(toutefois, si l'option QWizard::IndependentPages est activée, cette fonction n'est appelée que la première fois que la page est affichée).

En réimplémentant cette fonction, vous pouvez vous assurer que les champs de la page sont correctement initialisés en fonction des champs des pages précédentes. Par exemple, l'implémentation par défaut ne fait rien :

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

L'implémentation par défaut ne fait rien.

Voir également QWizard::initializePage(), cleanupPage() et QWizard::IndependentPages.

bool QWizardPage::isCommitPage() const

Renvoie true si cette page est une page d'engagement ; sinon, renvoie false.

Voir aussi setCommitPage().

[virtual] bool QWizardPage::isComplete() const

Cette fonction virtuelle est appelée par QWizard pour déterminer si le bouton Next ou Finish doit être activé ou désactivé.

L'implémentation par défaut renvoie true si tous les mandatory fields sont remplis ; sinon, elle renvoie false.

Si vous réimplémentez cette fonction, assurez-vous d'émettre completeChanged(), à partir du reste de votre implémentation, chaque fois que la valeur de isComplete() change. Cela garantit que QWizard met à jour l'état activé ou désactivé de ses boutons. Un exemple de réimplémentation est disponible ici.

Voir également completeChanged() et isFinalPage().

bool QWizardPage::isFinalPage() const

Cette fonction est appelée par QWizard pour déterminer si le bouton Finish doit être affiché pour cette page ou non.

Par défaut, elle renvoie true s'il n'y a pas de page suivante (c'est-à-dire que nextId() renvoie -1) ; sinon, elle renvoie false.

En appelant explicitement setFinalPage(true), vous pouvez permettre à l'utilisateur d'effectuer une "fin anticipée".

Voir également isComplete() et QWizard::HaveFinishButtonOnEarlyPages.

[virtual] int QWizardPage::nextId() const

Cette fonction virtuelle est appelée par QWizard::nextId() pour savoir quelle page afficher lorsque l'utilisateur clique sur le bouton Next.

La valeur de retour est l'ID de la page suivante, ou -1 si aucune page ne suit.

Par défaut, cette fonction renvoie l'identifiant le plus bas supérieur à l'identifiant de la page actuelle, ou -1 si cet identifiant n'existe pas.

En réimplémentant cette fonction, vous pouvez spécifier un ordre dynamique des pages. Par exemple, cette fonction permet de spécifier un ordre dynamique des pages :

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

Voir aussi QWizard::nextId().

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

Renvoie la pixmap définie pour le rôle which.

Les images peuvent également être définies pour l'ensemble de l'assistant à l'aide de QWizard::setPixmap(), auquel cas elles s'appliquent à toutes les pages qui ne spécifient pas d'image.

Voir aussi setPixmap(), QWizard::pixmap() et Elements of a Wizard Page.

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

Crée un champ appelé name associé à l'élément donné property de l'élément donné widget. Dès lors, cette propriété devient accessible à l'aide de field() et setField().

Les champs sont globaux à l'ensemble de l'assistant et permettent à n'importe quelle page d'accéder facilement aux informations stockées par une autre page, sans avoir à placer toute la logique dans QWizard ou à faire en sorte que les pages se connaissent explicitement les unes les autres.

Si name se termine par un astérisque (*), le champ est obligatoire. Lorsqu'une page comporte des champs obligatoires, les boutons Next et/ou Finish ne sont activés que lorsque tous les champs obligatoires sont remplis. Pour ce faire, il est nécessaire de spécifier changedSignal pour indiquer à QWizard de revérifier la valeur stockée dans le champ obligatoire.

QWizard connaît les Qt Widgets les plus courants. Pour ceux-ci (ou leurs sous-classes), il n'est pas nécessaire de spécifier un property ou un changedSignal. Le tableau ci-dessous répertorie ces widgets :

Vous pouvez utiliser QWizard::setDefaultProperty() pour ajouter des entrées à cette table ou pour remplacer des entrées existantes.

Pour considérer qu'un champ est "rempli", QWizard vérifie simplement que sa valeur actuelle n'est pas égale à sa valeur d'origine (la valeur qu'il avait avant l'appel à initializePage()). Pour QLineEdit, il vérifie également que hasAcceptableInput() renvoie vrai, afin d'honorer tout validateur ou masque.

QWizardLe mécanisme de champ obligatoire de la norme ISO est fourni pour des raisons de commodité. Il peut être contourné en réimplémentant QWizardPage::isComplete().

Voir aussi field(), setField(), et QWizard::setDefaultProperty().

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

Définit le texte du bouton which comme étant text sur cette page.

Par défaut, le texte des boutons dépend de la page QWizard::wizardStyle, mais il peut être redéfini pour l'ensemble de l'assistant à l'aide de QWizard::setButtonText().

Voir également buttonText(), QWizard::setButtonText() et QWizard::buttonText().

void QWizardPage::setCommitPage(bool commitPage)

Définit cette page comme une page de validation si commitPage est vrai ; sinon, la définit comme une page normale.

Une page de validation est une page qui représente une action qui ne peut être annulée en cliquant sur Back ou Cancel.

Un bouton Commit remplace le bouton Next sur une page de validation. En cliquant sur ce bouton, on appelle simplement QWizard::next(), tout comme on le fait en cliquant sur Next.

Le bouton Back d'une page saisie directement à partir d'une page de validation est désactivé.

Voir également isCommitPage().

[protected] void QWizardPage::setField(const QString &name, const QVariant &value)

Définit la valeur du champ appelé name à value.

Cette fonction peut être utilisée pour définir des champs sur n'importe quelle page de l'assistant. Elle équivaut à appeler wizard()->setField(name, value).

Voir également QWizard::setField(), field() et registerField().

void QWizardPage::setFinalPage(bool finalPage)

Définit explicitement cette page comme finale si finalPage est vrai.

Après avoir appelé setFinalPage(true), isFinalPage() renvoie true et le bouton Finish est visible (et activé si isComplete() renvoie true).

Après avoir appelé setFinalPage(false), isFinalPage() renvoie true si nextId() renvoie -1 ; sinon, il renvoie false.

Voir également isFinalPage(), isComplete() et QWizard::HaveFinishButtonOnEarlyPages.

void QWizardPage::setPixmap(QWizard::WizardPixmap which, const QPixmap &pixmap)

Définit la pixmap pour le rôle which à pixmap.

Les pixmaps sont utilisés par QWizard lors de l'affichage d'une page. Les pixmaps réellement utilisés dépendent de la page wizard style.

Les pixmaps peuvent également être définis pour l'ensemble de l'assistant à l'aide de QWizard::setPixmap(), auquel cas ils s'appliquent à toutes les pages qui ne spécifient pas de pixmap.

Voir également pixmap(), QWizard::setPixmap() et Elements of a Wizard Page.

[virtual] bool QWizardPage::validatePage()

Cette fonction virtuelle est appelée par QWizard::validateCurrentPage() lorsque l'utilisateur clique sur Next ou Finish pour effectuer une validation de dernière minute. Si elle renvoie true, la page suivante est affichée (ou l'assistant se termine) ; sinon, la page actuelle reste affichée.

L'implémentation par défaut renvoie true.

Lorsque cela est possible, il est généralement plus élégant de désactiver le bouton Next ou Finish (en spécifiant mandatory fields ou en réimplémentant isComplete()) que de réimplémenter validatePage().

Voir également QWizard::validateCurrentPage() et isComplete().

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

Renvoie l'assistant associé à cette page, ou nullptr si cette page n'a pas encore été insérée dans un QWizard.

Voir aussi QWizard::addPage() et QWizard::setPage().