QDialog Class

Description détaillée

Une fenêtre de dialogue est une fenêtre de premier niveau principalement utilisée pour des tâches de courte durée et des communications brèves avec l’utilisateur. Les QDialogs peuvent être modales ou non modales. Les QDialogs peuvent fournir une « return value » et disposer d’une « default buttons ». Les QDialogs peuvent également afficher une « QSizeGrip » dans leur coin inférieur droit, à l’aide de la fonction « setSizeGripEnabled()».

Notez que QDialog (et tout autre widget de type Qt::Dialog) utilise le widget parent de manière légèrement différente des autres classes de Qt. Une boîte de dialogue est toujours un widget de niveau supérieur, mais si elle possède un parent, son emplacement par défaut est centré au-dessus du widget de niveau supérieur de ce parent (si elle n'est pas elle-même de niveau supérieur). Il partagera également l’entrée de la barre des tâches de son parent.

Utilisez la surcharge de la fonction ` QWidget::setParent()` pour modifier la propriété d’un widget `QDialog`. Cette fonction vous permet de définir explicitement les indicateurs de fenêtre du widget dont le parent a été modifié ; l’utilisation de la fonction surchargée effacera les indicateurs de fenêtre spécifiant les propriétés du système de fenêtrage pour le widget (en particulier, elle réinitialisera l’indicateur ` Qt::Dialog `).

Boîtes de dialogue modales

Une boîte de dialogue modale est une boîte de dialogue qui bloque les interactions avec les autres fenêtres visibles de la même application. Les boîtes de dialogue 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. Les boîtes de dialogue peuvent être « application modal » (par défaut) ou « window modal ».

Lorsqu’une boîte de dialogue modale d’application est ouverte, l’utilisateur doit terminer son interaction avec celle-ci et la fermer avant de pouvoir accéder à toute autre fenêtre de l’application. Les boîtes de dialogue modales de fenêtre bloquent uniquement l’accès à la fenêtre associée à la boîte de dialogue, ce qui permet à l’utilisateur de continuer à utiliser les autres fenêtres de l’application.

La méthode la plus courante pour afficher une boîte de dialogue modale consiste à appeler sa fonction ` open()`. Vous pouvez également appeler ` setModal(true)` ou ` setWindowModality()`, puis ` show()`. Dans les deux cas, une fois la boîte de dialogue affichée, le contrôle est immédiatement restitué à l’appelant. Vous devez vous connecter au signal finished() pour savoir quand la boîte de dialogue est fermée et quelle est son return value. Vous pouvez également vous connecter aux signaux accepted() et rejected().

Lors de l’implémentation d’une boîte de dialogue personnalisée, pour fermer la boîte de dialogue et renvoyer une valeur appropriée, connectez un bouton par défaut, par exemple un bouton OK, au slot accept(), et un bouton Annuler au slot reject(). Vous pouvez également appeler le slot done() avec Accepted ou Rejected.

Si vous affichez la boîte de dialogue modale pour effectuer une opération de longue durée, il est recommandé d’exécuter cette opération dans un thread de travail en arrière-plan, afin qu’elle n’interfère pas avec le thread de l’interface graphique.

Boîtes de dialogue non modales

Une boîte de dialogue non modale est une boîte de dialogue qui fonctionne indépendamment des autres fenêtres de la même application. Les boîtes de dialogue « Rechercher et remplacer » des traitements de texte sont souvent non modales afin de 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 s'affichent à l'aide de la fonction ` show()`, qui renvoie immédiatement le contrôle à l'appelant.

Si vous appelez la fonction ` show()` après avoir masqué une boîte de dialogue, celle-ci s'affichera à son emplacement d'origine. En effet, c'est le gestionnaire de fenêtres qui détermine la position des fenêtres qui n'ont pas été explicitement positionnées par le programmeur. Pour conserver la position d’une boîte de dialogue qui a été déplacée par l’utilisateur, enregistrez sa position dans votre gestionnaire d’ closeEvent() puis déplacez la boîte de dialogue à cette position avant de l’afficher à nouveau.

Bouton par défaut

Le bouton par défaut d’une boîte de dialogue est celui sur lequel l’utilisateur clique lorsqu’il appuie sur la touche Entrée (Retour). Ce bouton sert à indiquer que l’utilisateur accepte les paramètres de la boîte de dialogue et souhaite la fermer. Utilisez les fonctions QPushButton::setDefault(), QPushButton::isDefault() et QPushButton::autoDefault() pour définir et contrôler le bouton par défaut de la boîte de dialogue.

Touche Échap

Si l’utilisateur appuie sur la touche Échap dans une boîte de dialogue, la fonction QDialog::reject() sera appelée. Cela provoquera la fermeture de la fenêtre : la fonction close event ne peut pas être ignored.

Extensibilité

L'extensibilité est la possibilité d'afficher la boîte de dialogue de deux manières : une boîte de dialogue partielle qui affiche les options les plus couramment utilisées, et une boîte de dialogue complète qui affiche toutes les options. En général, une boîte de dialogue extensible s'affiche initialement sous forme de boîte de dialogue partielle, mais avec un bouton bascule « More ». Si l'utilisateur appuie sur le bouton « More », la boîte de dialogue s'agrandit.

Valeur de retour (boîtes de dialogue modales)

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 cliqué sur « OK » ou « Cancel ». Une boîte de dialogue peut être fermée en appelant les slots ` accept()` ou ` reject()`, et la fonction ` exec()` renverra ` Accepted ` ou ` Rejected ` selon le cas. L'appel à ` exec()` renvoie le résultat de la boîte de dialogue. Ce résultat est également accessible via ` result()` si la boîte de dialogue n'a pas été détruite.

Pour modifier le comportement de fermeture de votre boîte de dialogue, vous pouvez réimplémenter les fonctions ` accept()`, ` reject()` ou ` done()`. La fonction ` closeEvent()` ne doit être réimplémentée que pour conserver la position de la boîte de dialogue ou pour remplacer le comportement standard de fermeture ou de rejet.

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, &FindDialog::findNext,
                this, &EditorWindow::findNext);
    }

    findDialog->show();
    findDialog->raise();
    findDialog->activateWindow();
}

Une boîte de dialogue avec une extension :

mainLayout->setSizeConstraint(QLayout::SetFixedSize);

findButton = new QPushButton(tr("&Find"));
moreButton = new QPushButton(tr("&More..."));
moreButton->setCheckable(true);

extension = new ExtendedControls;
mainLayout->addWidget(extension);
extension->hide();

connect(moreButton, &QAbstractButton::toggled, extension, &QWidget::setVisible);

En définissant la propriété « sizeConstraint » de la mise en page de la boîte de dialogue sur « SetFixedSize », celle-ci ne pourra pas être redimensionnée par l'utilisateur et se réduira automatiquement lorsque l'extension sera masquée.