QProgressDialog

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

#include <QProgressDialog>

Voir la position dans l'arbre des classes.

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 !