===== QProgressDialog ===== La classe QProgressDialog fournit un aperçu sur la progression d'une opération lente. [[#Description détaillée|Plus d'informations...]] ==== 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-prop|minimumDuration()]] (4 secondes par défaut). Utilisez [[#minimum-prop|setMinimum()]] et [[#maximum-prop|setMaximum()]] ou le constructeur pour définir le nombre d'étapes dans l'opération et appelez [[#value-prop|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 [[#minimum-prop|setMinimum()]], la boîte de dialogue de progression affiche que l'opération est terminée quand vous appelez [[#value-prop|setValue()]] avec la valeur fixée par [[#maximum-prop|setMaximum()]]. Automatiquement, la boîte de dialogue se remet à l'état initial et se cache à la fin de l'opération. Utilisez [[#autoReset-prop|setAutoReset()]] et [[#autoClose-prop|setAutoClose()]] pour modifier ce comportement. Notez que, si vous définissez un nouveau maximum (en utilisant [[#maximum-prop|setMaximum()]] ou [[#setRange()]]) égal à votre valeur [[#value-prop|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 à [[#value-prop|setValue()]] à intervalle régulier et contrôler s'il y a annulation avec [[#wasCanceled-prop|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|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 [[#value-prop|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 [[#labelText-prop|setLabelText()]] et [[#setCancelButtonText()]] définissent les textes à afficher. {{ http://qt.developpez.com/doc/4.6/images/plastique-progressdialog.png |}} Voir aussi [[QDialog]], [[QProgressBar]], [[guibooks#fowler|Livre design d'interface graphique utilisateur : indicateur de progression]], [[dialogs-findfiles|Exemple Trouver des fichiers]] et [[itemviews-pixelator|Exemple Pixelator]]. ==== Propriétés ==== === autoClose-prop === ''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 [[#autoReset-prop|setAutoReset()]]. === autoReset-prop === ''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 [[#autoClose-prop|setAutoClose()]]. === labelText-prop === ''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-prop === ''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 ''0''. == Fonctions d'accès == ''int maximum () const'' ''void setMaximum ( int maximum )'' Voir aussi [[#minimum-prop|minimum]] et [[#setRange()]]. === mimimum-prop=== ''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 ''0''. == Fonctions d'accès == ''int minimum () const'' ''void setminimum ( int minimum )'' Voir aussi [[#maximum-prop|maximum]] et [[#setRange()]]. === minimumDuration-prop === ''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 à ''0'', 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-prop === ''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é à ''0'' 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::QProgressDialog()]]), setValue() appelle [[qcoreapplication#processEvents|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 [[qwidget#paintEvent|paintEvent()]] ! == Fonctions d'accès == ''int value () const'' ''void setValue ( int progress )'' Voir aussi [[minimum-prop|minimum]] et [[maximum-prop|maximum]]. === wasCanceled-prop === ''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::QProgressDialog ( [[QWidget]] * ''parent'' = 0, [[Qt]]::[[qt#WindowFlags|WindowFlags]] f = 0 )'' 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|QDialog::QDialog()]]. Voir aussi [[#labelText-prop|setLabelText()]], [[#setCancelButtonText()]], [[#setCancelButton()]], [[#setMinimum()]] et [[#setMaximum()]]. === QProgressDialog() === ''QProgressDialog::QProgressDialog ( const [[QString]] & labelText, const [[QString]] & cancelButtonText, int minimum, int maximum, [[QWidget]] * parent = 0, [[Qt]]::[[qt#WindowFlags|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()|setValue(0)]]. Pendant que chaque fichier est traité, appelez [[#setValue()|setValue(1)]], [[#setValue()|setValue(2)]], etc., jusqu'à appeler [[#setValue()|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|QDialog::QDialog()]]. Voir aussi [[#setLabelText()]], [[#setLabel()]], [[#setCancelButtonText()]], [[#setCancelButton()]], [[#setMinimum()]] et [[#setMaximum()]]. === ~QProgressDialog() === ''QProgressDialog::~QProgressDialog ()'' Détruit la boîte de dialogue affichant la progression. === cancel() === ''void QProgressDialog::cancel () [slot]'' Réinitialise la boîte de dialogue affichant la progression. [[qprogressdialog#wasCanceled-prop|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. === canceled() === ''void QProgressDialog::canceled () [signal]'' Ce signal est émis lors d'un clic sur le bouton ''cancel''. Il est connecté par défaut au slot [[qprogressdialog#cancel|cancel()]]. Voir aussi [[qprogressdialog#wasCanceled-prop|wasCanceled()]]. === changeEvent() === ''void QProgressDialog::changeEvent ( [[QEvent]] * ev ) [virtual protected]'' Réimplémentation de [[qwidget#changeEvent|QWidget::changeEvent()]]. === closeEvent() === ''void QProgressDialog::closeEvent ( [[QCloseEvent]] * e ) [virtual protected]'' Réimplémentation de [[qwidget#closeEvent|QWidget::closeEvent()]]. === forceShow() === ''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 [[qprogressdialog#minimumDuration-prop|minimumDuration]] millisecondes se sont écoulées. Voir aussi [[qprogressdialog#minimumDuration-prop|setMinimumDuration()]]. === open() === ''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 [[qdialog#accepted|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. === reset() === ''void QProgressDialog::reset () [slot]'' Réinitialise la boîte de dialogue de progression. Celle-ci est cachée si [[qprogressdialog#autoClose-prop|autoClose()]] est ''true''. Voir aussi [[qprogressdialog#autoClose-prop|setAutoClose()]] et [[qprogressdialog#autoReset-prop|setAutoReset()]]. === resizeEvent() === ''void QProgressDialog::resizeEvent ( [[QResizeEvent]] * event ) [virtual protected]'' Réimplémentation de [[qwidget#resizeEvent|QWidget::resizeEvent()]]. === setBar() === ''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. === setCancelButton() === ''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 ''0'' est passé en paramètre, aucun bouton d'annulation ne sera affiché. Voir aussi [[qprogressdialog#setCancelButtonText|setCancelButtonText()]]. === 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 [[qprogressdialog#setCancelButton|setCancelButton()]]. === setLabel() === ''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 [[qprogressdialog#labelText-prop|setLabelText()]]. === setRange() === ''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 [[qprogressdialog#reset|reset()]]. Voir aussi [[qprogressdialog#minimum-prop|minimum]] et [[qprogressdialog#maximum-prop|maximum]]. === showEvent() === ''void QProgressDialog::showEvent ( [[QShowEvent]] * e ) [virtual protected]'' Réimplémentation de [[qwidget#showEvent|QWidget::showEvent()]]. === sizeHint() === ''[[QSize]] QProgressDialog::sizeHint () const [virtual]'' Réimplémentation de [[qwidget#sizeHint-prop|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 à , et pour la traduction, ainsi qu'à pour la traduction, la mise en page et la relecture et pour la relecture !