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 !