QProgressDialog

La classe QProgressDialog fournit un aperçu sur la progression d'une opération lente. Plus d'informations...

#include <QProgressDialog>

Héritage

Hérite de QDialog.

Description détaillée

La classe QProgressDialog fournit un aperçu sur la progression d'une opération lente.

Une boîte de dialogue affichant une progression est utilisée pour donner à l'utilisateur une indication sur le temps qu'une opération peut prendre et pour montrer que l'application n'a pas gelé. Elle peut également donner à l'utilisateur l'opportunité d'arrêter l'opération.

Un problème courant qui survient avec les boîtes de dialogue affichant une progression est qu'il est difficile de savoir quand les utiliser. La durée de chaque opération diffère en fonction du matériel. QProgressDialog offre une solution à ce problème : il estime le temps que l'opération va prendre (basé sur le temps de chacune des étapes) et ne s'affiche que si le temps estimé est supérieur à minimumDuration() (4 secondes par défaut).

Utilisez setMinimum() et setMaximum() ou le constructeur pour définir le nombre d'étapes dans l'opération et appelez setValue() au fur et à mesure que l'opération avance. Le nombre d'étapes peut être choisi arbitrairement. Cela peut être le nombre de fichiers à copier, le nombre d'octets à recevoir, le nombre d'itérations à travers la boucle principale de votre algorithme ou toute autre unité appropriée. La progression démarre à la valeur fixée par setMinimum(), la boîte de dialogue de progression affiche que l'opération est terminée quand vous appelez setValue() avec la valeur fixée par setMaximum().

Automatiquement, la boîte de dialogue se remet à l'état initial et se cache à la fin de l'opération. Utilisez setAutoReset() et setAutoClose() pour modifier ce comportement. Notez que, si vous définissez un nouveau maximum (en utilisant setMaximum() ou setRange()) égal à votre valeur value() actuelle, la boîte de dialogue ne se fermera pas.

Il existe deux façons d'utiliser QProgressDialog : en fenêtre modale et sans mode (modeless).

En comparaison d'une QProgressDialog modeless, une QProgressDialog modale est plus simple à utiliser pour le développeur. Dans une boucle, exécuter les différentes opérations avec appel à setValue() à intervalle régulier et contrôler s'il y a annulation avec wasCanceled(). Par exemple :

QProgressDialog progress("Copie des fichiers...", "Arrêter la copie", 0, numFiles, this);
progress.setWindowModality(Qt::WindowModal);
 
for (int i = 0; i < numFiles; i++) {
   progress.setValue(i);
 
   if (progress.wasCanceled())
        break;
    // ... copie un fichier
}
progress.setValue(numFiles);

Une boîte de dialogue modeless affichant une progression convient aux opérations qui ont lieu en arrière-plan, où l'utilisateur peut interagir avec l'application. De telles opérations sont typiquement basées sur QTimer (ou QObject::timerEvent()), QSocketNotifier ou QUrlOperator ; ou exécutées dans un thread séparé. Une QProgressBar dans la barre de statut de votre fenêtre principale est souvent une alternative à une boîte de dialogue modeless affichant une progression.

Vous devez avoir une boucle événementielle en fonctionnement, connectez le signal canceled() à un slot qui stoppe l'opération et appelez setValue() à intervalles réguliers. Par exemple :

// Constructeur de opération
opération::opération(QObject *parent)
    : QObject(parent), steps(0)
{
    pd = new QProgressDialog("Opération en cours.", "Annuler", 0, 100);
    connect(pd, SIGNAL(canceled()), this, SLOT(cancel()));
    t = new QTimer(this);
    connect(t, SIGNAL(timeout()), this, SLOT(perform()));
    t->start(0);
}
 
void opération::perform()
{
    pd->setValue(steps);
    //... exécuter un pour cent de l'opération
    steps++;
    if (steps > pd->maximum())
        t->stop();
}
 
void opération::cancel()
{
    t->stop();
    //... nettoyage
}

Les deux modes de boîte de dialogue affichant une progression peuvent être personnalisés en remplaçant les widgets enfants avec des widgets personnalisés en utilisant setLabel(), setBar() et setCancelButton(). Les fonctions setLabelText() et setCancelButtonText() définissent les textes à afficher.

Voir aussi QDialog, QProgressBar, Livre design d'interface graphique utilisateur : indicateur de progression, Exemple Trouver des fichiers et Exemple Pixelator.

Propriétés

autoClose : bool

Cette propriété permet de savoir si la boîte de dialogue est cachée par reset().

La valeur par défaut est true.

Fonctions d'accès

bool autoClose () const

void setAutoClose ( bool close )

Voir aussi setAutoReset().

autoReset : bool

Cette propriété permet de savoir si la boîte de dialogue appelle reset() dès que value() vaut maximum().

La valeur par défaut est true.

Fonctions d'accès

bool autoReset () const

void setAutoReset ( bool reset )

Voir aussi setAutoClose().

labelText : QString

Cette propriété contient le texte du label.

La valeur par défaut du texte est une chaîne de caractères vide.

Fonctions d'accès

QString labelText () const

void setLabelText ( const QString & text )

maximum : int

Cette propriété contient la valeur la plus élevée représentée par la barre de progression.

La valeur par défaut est  .

Fonctions d'accès

int maximum () const

void setMaximum ( int maximum )

Voir aussi minimum et setRange().

mimimum : int

Cette propriété contient la valeur la plus basse représentée par la barre de progression.

La valeur par défaut est  .

Fonctions d'accès

int minimum () const

void setminimum ( int minimum )

Voir aussi maximum et setRange().

minimumDuration : int

Cette propriété contient la durée minimale qui doit s'écouler avant l'apparition de la boîte de dialogue.

Si la durée prévue de la tâche est inférieure à minimumDuration, la boîte de dialogue n'apparaîtra pas du tout. Ceci empêche que la boîte de dialogue apparaisse pour les tâches rapidement effectuées. Pour les tâches qui sont censées dépasser minimumDuration, la boîte de dialogue apparaîtra après minimumDuration ou dès qu'une progression est définie.

Si elle est définie à  , la boîte de dialogue sera toujours affichée dès qu'une progression sera définie. Par défaut, celle-ci est de 4000 millisecondes.

Fonctions d'accès

int minimumDuration () const

void setMinimumDuration ( int ms )

value : int

Cette propriété contient la progression effectuée.

Pour que la boîte de dialogue affichant la progression fonctionne comme prévu, vous devriez définir au début cette propriété à   et à la fin à maximum() ; vous pouvez appeler setValue() et lui passer tout nombre dans l'intervalle.

Attention : si la boîte de dialogue affichant la progression est modale (voir QProgressDialog::QProgressDialog()), setValue() appelle QApplication::processEvents(), donc faites attention que ceci n'entraîne pas une réentrance indésirable dans votre code. Par exemple, ne pas utiliser un QProgressDialog à l'intérieur d'un paintEvent() !

Fonctions d'accès

int value () const

void setValue ( int progress )

Voir aussi minimum et maximum.

wasCanceled : const bool

Cette propriété précise si la boîte de dialogue a été annulée.

Fonctions d'accès

bool wasCanceled () const

Fonctions membres

QProgressDialog::QProgressDialog ( QWidget *

Construit une boîte de dialogue affichant la progression.

Paramètres par défaut :

• Le texte du label est vide ;
• Le texte du bouton pour annuler est « Cancel » (traduit) ;
• Le minimum est de 0 ;
• Le maximum est de 100.

L'argument parent est le widget parent de cette boîte de dialogue. Les drapeaux (flags) du widget, f, sont passés au constructeur de QDialog::QDialog().

Voir aussi setLabelText(), setCancelButtonText(), setCancelButton(), setMinimum() et setMaximum().

QProgressDialog::QProgressDialog ( const QString & labelText, const QString & cancelButtonText, int minimum, int maximum, QWidget * parent = 0, Qt::WindowFlags f = 0 )

Construit une boîte de dialogue affichant la progression.

labelText est le texte qui sert à rappeler à l'utilisateur ce qui est en progression.

cancelButtonText est le texte à afficher sur le bouton d'annulation. Si cancelButtonText vaut QString() alors le bouton d'annulation n'est pas affiché.

minimum et maximum correspondent au nombre d'étapes qui constituent l'opération pour laquelle cette boîte de dialogue montre la progression. Par exemple, si l'opération consiste à examiner 50 fichiers, la valeur de minimum serait 0, et la valeur de maximum serait 50. Avant d'examiner le premier fichier, appelez setValue(0). Pendant que chaque fichier est traité, appelez setValue(1), setValue(2), etc., jusqu'à appeler setValue(50) après avoir examiné le dernier fichier.

L'argument parent correspond au widget parent de la boîte de dialogue. Le widget parent, parent, et les drapeaux du widget, f, sont passés au constructeur QDialog::QDialog().

Voir aussi setLabelText(), setLabel(), setCancelButtonText(), setCancelButton(), setMinimum() et setMaximum().

QProgressDialog::~QProgressDialog ()

Détruit la boîte de dialogue affichant la progression.

void QProgressDialog::cancel () [slot]

Réinitialise la boîte de dialogue affichant la progression. wasCanceled() devient true jusqu'à ce que la boîte de dialogue de progression soit réinitialisée. La boîte de dialogue de progression est cachée.

void QProgressDialog::canceled () [signal]

Ce signal est émis lors d'un clic sur le bouton cancel. Il est connecté par défaut au slot cancel().

Voir aussi wasCanceled().

void QProgressDialog::changeEvent ( QEvent * ev ) [virtual protected]

Réimplémentation de QWidget::changeEvent().

void QProgressDialog::closeEvent ( QCloseEvent * e ) [virtual protected]

Réimplémentation de QWidget::closeEvent().

void QProgressDialog::forceShow () [protected slot]

Montre la boîte de dialogue si elle est toujours cachée après que l'algorithme a démarré et que minimumDuration millisecondes se sont écoulées.

Voir aussi setMinimumDuration().

void QProgressDialog::open ( QObject * receiver, const char * member )

Il s'agit d'une fonction surchargée.

Ouvre la boîte de dialogue et connecte son signal accepted() au slot spécifié par son récepteur receiver et son membre member.

Le signal sera déconnecté du slot quand la boîte de dialogue sera fermée.

Cette fonction a été introduite dans Qt 4.5.

void QProgressDialog::reset () [slot]

Réinitialise la boîte de dialogue de progression. Celle-ci est cachée si autoClose() est true.

Voir aussi setAutoClose() et setAutoReset().

void QProgressDialog::resizeEvent ( QResizeEvent * event ) [virtual protected]

Réimplémentation de QWidget::resizeEvent().

void QProgressDialog::setBar ( QProgressBar * bar )

Définit la barre de progression à bar. La boîte de dialogue se redimensionnera en fonction et prendra possession de la barre de progression, qui sera détruite au bon moment. Ne passez donc pas l'adresse d'une barre allouée sur la pile.

void QProgressDialog::setCancelButton ( QPushButton * cancelButton )

Définit le bouton d'annulation à cancelButton. La boîte de dialogue de progression va prendre possession de ce bouton, qui sera donc supprimé quand cela sera nécessaire. Ne passez donc pas l'adresse d'un objet alloué sur la pile, utilisez new() pour créer le bouton. Si   est passé en paramètre, aucun bouton d'annulation ne sera affiché.

Voir aussi setCancelButtonText().

void QProgressDialog::setCancelButtonText ( const QString & cancelButtonText ) [slot]

Définit le texte du bouton d'annulation à cancelButtonText. Si ce texte est défini à QString(), alors le bouton d'annulation sera caché et détruit.

Voir aussi setCancelButton().

void QProgressDialog::setLabel ( QLabel * label )

Définit le label à label. La boîte de dialogue se redimensionnera en fonction de sa longueur. La boîte de dialogue prendra possession du label, qui sera supprimé dès que cela sera nécessaire : ne passez donc pas l'adresse d'un objet alloué sur la pile, utilisez new() pour créer le label.

Voir aussi setLabelText().

void QProgressDialog::setRange ( int minimum, int maximum ) [slot]

Définit les valeurs maximale et minimale de la boîte de dialogue de progression respectivement à minimum et maximum.

Si maximum est plus petit que minimum, celui-ci devient la seule valeur prise en compte.

Si la valeur actuelle de la boîte de dialogue de progression se trouve hors du nouvel intervalle, celui-ci est réinitialisé avec reset().

Voir aussi minimum et maximum.

void QProgressDialog::showEvent ( QShowEvent * e ) [virtual protected]

Réimplémentation de QWidget::showEvent().

QSize QProgressDialog::sizeHint () const [virtual]

Réimplémentation de QWidget::sizeHint().

Retourne une taille qui convient au contenu de la boîte de dialogue de progression. Elle se redimensionne seulement si nécessaire, vous ne devriez donc pas avoir à appeler cette fonction vous-même.

Remerciements

Merci à Mikael Sans, Nicolas Carion et Jonathan Courtois pour la traduction, ainsi qu'à Thibaut Cuvelier pour la traduction, la mise en page et la relecture et Maxime Gault pour la relecture !