QDialog

La classe QDialog est la classe de base des boîtes de dialogue. Plus d'informations...

#include <QDialog>

Voir la position dans l'arbre des classes.

Description détaillée
Les boîtes de dialogue	Touche Echap	Valeur de retour (boîtes de dialogue modales)
Les boîtes de dialogue non modales	Extensibilité	Exemples de code
Bouton par défaut
Type
	DialogCode
Propriétés
modal	sizeGripEnabled
Fonctions membres
QDialog()	eventFilter()	rejected()
~QDialog()	exec()	resizeEvent()
accept()	finished()	result()
accepted()	keyPressEvent()	setResult()
closeEvent()	minimumSizeHint()	setVisible()
contextMenuEvent()	open()	showEvent()
done()	reject()	sizeHint()
event()

Héritage

Hérite de QWidget.

Héritage

Hérité par Q3FileDialog, Q3ProgressDialog, Q3TabDialog, Q3Wizard, QAbstractPrintDialog, QColorDialog, QErrorMessage, QFileDialog, QFontDialog, QInputDialog, QMessageBox, QPageSetupDialog, QPrintPreviewDialog, QProgressDialog et QWizard.

Description détaillée

La classe QDialog est la classe de base des boîtes de dialogue.

Une boîte de dialogue est une fenêtre de premier niveau souvent utilisée pour les tâches de court terme et les communications brèves avec l?utilisateur. Les QDialog peuvent être modales ou non modales. Elles peuvent fournir une valeur de retour et peuvent posséder un bouton par défaut. Elles peuvent aussi posséder une poignée de dimensionnement QSizeGrip sur leur coin inférieur droit, en utilisant la fonction setSizeGripEnabled().

À noter que QDialog (et tout autre objet de type Qt::Dialog) utilise son widget parent de façon un peu différente des autres classes de Qt. Une boîte de dialogue est toujours un widget de premier niveau, mais si elle possède un parent, sa position par défaut est centrée sur le widget de premier niveau du parent (s'il n?est pas de premier niveau lui-même). Elle va également partager l'entrée de la barre des tâches de son parent.

Pour modifier le propriétaire d?un widget QDialog, on surcharge sa fonction QWidget::setParent(). Cette fonction autorise à spécifier explicitement les drapeaux de fenêtre du widget ayant changé de parent ; l?utilisation de la fonction surchargée va nettoyer les drapeaux de fenêtre spécifiant les propriétés liées au système de fenêtres pour le widget (en particulier cela va réinitialiser le drapeau Qt::Dialog).

Les boîtes de dialogue

Une boîte de dialogue modale bloque les entrées des autres fenêtres visibles de la même application. Les fenêtres utilisées pour demander un nom de fichier à l?utilisateur, ou pour définir les préférences de l?application sont généralement modales. Une boîte de dialogue peut être modale à l?application (par défaut) ou modale à la fenêtre.

Lorsqu?une boîte de dialogue modale à l?application est ouverte, l?utilisateur doit terminer son interaction avec la boîte de dialogue et la fermer avant de pouvoir accéder à n?importe quelle autre fenêtre de l?application. Une boîte de dialogue modale à la fenêtre ne bloque que les accès à la fenêtre associée à la boîte de dialogue, permettant à l?utilisateur de continuer à utiliser les autres fenêtres de l?application.

La façon la plus courante d?afficher une boîte de dialogue modale est d?appeler sa fonction exec(). Lorsque l?utilisateur ferme la boîte de dialogue, exec() va retourner une valeur de retour utile. Typiquement, pour obtenir la fermeture de la boîte de dialogue et le retour d?une valeur appropriée, on connecte un bouton par défaut, par exemple OK, au slot accept(), et un bouton Annuler au slot reject(). Sinon, on peut appeler le slot done() avec les arguments Accepted ou Rejected.

Une autre possibilité est d?appeler setModal(true) ou setWindowModality(), puis show(). Contrairement à exec(), show() rend le contrôle à la fonction appelante immédiatement. Appeler setModal(true) est particulièrement utile pour les boîtes de dialogue de progression, lorsque l?utilisateur doit pouvoir interagir avec la boîte de dialogue, par exemple pour annuler une opération longue. Si on utilise show() et setModal(true) ensemble pour réaliser une opération longue, on doit appeler QApplication::processEvents() périodiquement durant le traitement pour permettre à l?utilisateur d?interagir avec la boîte de dialogue (voir QProgressDialog).

Les boîtes de dialogue non modales

Une boîte de dialogue non modale est une boîte de dialogue qui opère indépendamment des autres fenêtres de la même application. Les boîtes de dialogue de recherche et de remplacement de texte dans les traitements de textes sont souvent non modales pour permettre à l?utilisateur d?interagir à la fois avec la fenêtre principale de l?application et avec la boîte de dialogue.

Les boîtes de dialogue non modales sont affichées en utilisant show(), qui redonne la main à la fonction appelante immédiatement.

Si on appelle la fonction show() après avoir caché la boîte de dialogue, cette dernière sera affichée à sa position d?origine. Ceci est dû au fait que le gestionnaire de fenêtres décide de la position d?une fenêtre qui n?a pas été explicitement positionnée par le programmeur. Pour préserver la position d?une boîte de dialogue qui a été déplacée par l?utilisateur, il faut enregistrer sa position dans le gestionnaire closeEvent(), puis déplacer la boîte de dialogue à cette position avant de la montrer à nouveau.

Bouton par défaut

Le bouton par défaut d?une boîte de dialogue est le bouton qui est pressé lorsque l?utilisateur appuie sur la touche Entrée. Ce bouton est utilisé pour indiquer que l?utilisateur accepte les paramètres de la boîte de dialogue et souhaite la fermer. On utilise QPushButton::setDefault(), QPushButton::isDefault() et QPushButton::autoDefault() pour définir et contrôler le bouton par défaut d?une boîte de dialogue.

Touche Echap

Si l?utilisateur appuie sur la touche Echap dans une boîte de dialogue, la fonction QDialog::reject() sera appelée. Ceci provoque la fermeture de la fenêtre : l?événement de fermeture ne peut pas être ignoré.

Extensibilité

L?extensibilité est la capacité d?afficher une boîte de dialogue de deux façons : une boîte de dialogue partielle qui montre les options les plus communément utilisées, et une boîte de dialogue complète qui présente toutes les options. Typiquement, une boîte de dialogue extensible apparaîtra initialement de manière partielle mais avec un bouton de basculement Plus. Si l?utilisateur appuie sur le bouton Plus, la boîte de dialogue sera étendue. L?exemple d?extension montre comment réaliser des boîtes de dialogue extensibles en utilisant Qt.

Les boîtes de dialogue modales sont souvent utilisées dans des situations où une valeur de retour est requise, par exemple pour indiquer si l?utilisateur a appuyé sur OK ou Annuler. Une boîte de dialogue peut être fermée en appelant les slots accept() ou reject(), et exec() va retourner

Accepted

or Rejected selon le cas. Le résultat est également disponible depuis la fonction result() si la boîte de dialogue n?a pas été détruite.

Afin de modifier le comportement de fermeture de la boîte de dialogue, on peut réimplémenter les fonctions accept(), reject() ou done(). La fonction closeEvent() ne devrait être réimplémentée que pour conserver la position de la boîte de dialogue, ou pour écraser les comportements de fermeture ou de refus standard.

Exemples de code

Une boîte de dialogue modale :

 void EditorWindow::countWords()
 {
     WordCountDialog dialog(this);
     dialog.setWordCount(document().wordCount());
     dialog.exec();
 }

Une boîte de dialogue non modale :

 void EditorWindow::find()
 {
     if (!findDialog) {
         findDialog = new FindDialog(this);
         connect(findDialog, SIGNAL(findNext()), this, SLOT(findNext()));
     }
 
     findDialog->show();
     findDialog->raise();
     findDialog->activateWindow();
 }

Voir aussi QDialogButtonBox, QTabWidget, QWidget, QProgressDialog, GUI Design Handbook : Dialogs, Standard, Exemple d?extension et Exemple de boîtes de dialogue standard.

Type

enum QDialog::DialogCode

La valeur retournée par une boîte de dialogue modale.

Constante	Valeur
QDialog::Accepted	1
QDialog::Rejected

Propriétés

modal : bool

Cette propriété définit si show() doit faire apparaître la boîte de dialogue de manière modale ou non modale.

Par défaut, cette propriété est à false et show() fait apparaître la boîte de dialogue de manière non modale. Fixer cette propriété à true est équivalent à fixer QWidget::windowModality à Qt::ApplicationModal.

exec() ignore la valeur de cette propriété et fait toujours apparaître la boîte de dialogue de manière modale.

Fonction d'accès

bool isModal () const

void setModal ( bool modal )

Voir aussi QWidget::windowModality, show() et exec().

sizeGripEnabled : bool

Cette propriété définit si la poignée de dimensionnement est activée.

Une poignée de dimensionnement QSizeGrip est placée dans le coin inférieur droit du dialogue lorsque cette propriété est activée. Par défaut, la poignée de dimensionnement est désactivée.

Fonction d'accès

bool isSizeGripEnabled () const

void setSizeGripEnabled ( bool )

Fonctions membres

QDialog::QDialog ( QWidget * parent = 0, Qt::WindowFlags f = 0 )

Construit une boîte de dialogue avec le parent parent.

Une boîte de dialogue est toujours un widget de premier niveau, mais s?il possède un parent, sa position par défaut est centrée sur le parent. Il va également partager les entrées de la barre des tâches du parent.

Les drapeaux de widget f sont passés au constructeur de QWidget. Si, par exemple, on ne souhaite pas de bouton Qu?est-ce que c?est ? dans la barre de titre de la boîte de dialogue, on passe Qt::WindowTitleHint | Qt::WindowSystemMenuHint dans f.

Voir aussi QWidget::setWindowFlags().

QDialog::~QDialog ()

Détruit la QDialog, effaçant tous ses enfants.

void QDialog::accept () [virtual slot]

Cache la boîte de dialogue modale et fixe le résultat à Accepted.

Voir aussi reject() et done().

void QDialog::accepted () [signal]

Ce signal est émis lorsque la boîte de dialogue a été acceptée, soit par l?utilisateur, soit en appelant accept() ou done() avec l?argument QDialog::Accepted.

À noter que le signal n?est pas émis lorsque la boîte de dialogue est cachée par hide() ou setVisible(false). Ceci inclut la destruction de la boîte de dialogue lorsqu?elle est visible.

Cette fonction a été introduite dans Qt 4.1.

Voir aussi finished() et rejected().

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

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

void QDialog::contextMenuEvent ( QContextMenuEvent * e ) [virtual protected]

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

void QDialog::done ( int r ) [virtual slot]

Ferme la boîte de dialogue et fixe son résultat à r. Si cette boîte de dialogue est affichée par exec(), done() provoque la fin de la boucle d?événements locale, et exec() retourne r.

De même que QWidget::close(), done() détruit la boîte de dialogue si le drapeau Qt::WA_DeleteOnClose est activé. Si la boîte de dialogue est le widget principal de l?application, celle-ci se termine. Si la boîte de dialogue est la dernière fenêtre fermée, le signal QApplication::lastWindowClosed() est émis.

Voir aussi accept(), reject(), QApplication::activeWindow() et QApplication::quit().

bool QDialog::event ( QEvent * e ) [virtual protected]

Réimplémentation de QObject::event().

bool QDialog::eventFilter ( QObject * o, QEvent * e ) [virtual protected]

Réimplémentation de QObject::eventFilter().

int QDialog::exec () [slot]

Affiche la boîte de dialogue en tant que boîte de dialogue modale, bloquante jusqu?à ce que l?utilisateur la ferme. La fonction retourne un code résultat DialogCode.

Si la boîte de dialogue est modale à l?application, l?utilisateur ne peut interagir avec aucune autre fenêtre de la même application jusqu?à ce qu?il ferme la boîte de dialogue. Si la boîte de dialogue est modale à la fenêtre, seule l?interaction avec la fenêtre parente est bloquée tant que la boîte de dialogue est ouverte. Par défaut, la boîte de dialogue est modale à l?application.

Voir aussi open(), show(), result() et setWindowModality().

void QDialog::finished ( int result ) [signal]

Ce signal est émis lorsque le code résultat result de boîte de dialogue a été fixé, par l?utilisateur ou en appelant done(), accept() ou reject().

À noter que le signal n?est pas émis lorsque la boîte de dialogue est cachée par hide() ou setVisible(false). Ceci inclut la destruction de la boîte de dialogue lorsqu?elle est visible.

Cette fonction a été introduite dans Qt 4.1.

Voir aussi accepted() et rejected().

void QDialog::keyPressEvent ( QKeyEvent * e ) [virtual protected]

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

QSize QDialog::minimumSizeHint () const [virtual]

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

void QDialog::open () [slot]

Affiche la boîte de dialogue en tant que boîte de dialogue modale à la fenêtre, et retourne immédiatement.

Cette fonction a été introduite dans Qt 4.5.

Voir aussi exec(), show(), result() et setWindowModality().

void QDialog::reject () [virtual slot]

Cache la boîte de dialogue modale et fixe le code résultat à Rejected

Voir aussi accept() et done().

void QDialog::rejected () [signal]

Ce signal est émis lorsque la boîte de dialogue a été refusée par l?utilisateur ou en appelant reject() ou done() avec l?argument QDialog::Rejected.

À noter que le signal n?est pas émis lorsque la boîte de dialogue est cachée par hide() ou setVisible(false). Ceci inclut la destruction de la boîte de dialogue lorsqu?elle est visible.

Cette fonction a été introduite dans Qt 4.1.

Voir aussi finished() et accepted().

void QDialog::resizeEvent ( QResizeEvent * ) [virtual protected]

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

int QDialog::result () const

Retourne le code résultat de la boîte de dialogue modale, Accepted ou Rejected.

Ne pas appeler cette fonction si la boîte de dialogue a été construite avec l?attribut Qt::WA_DeleteOnClose.

Voir aussi setResult().

void QDialog::setResult ( int i )

Fixe le code résultat de boîte de dialogue modal à i.

À noter : il est recommandé d?utiliser une des valeurs définies par QDialog::DialogCode.

Voir aussi result().

void QDialog::setVisible ( bool visible ) [virtual]

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

void QDialog::showEvent ( QShowEvent * event ) [virtual protected]

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

QSize QDialog::sizeHint () const [virtual]

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

Remerciements

Merci à Lo?c Leguay pour la traduction, ainsi qu'à Ilya Diallo, David Taralla et Claude Leloup pour la relecture !