From 423659af18ac3c78bf93a6b6160f863ffe9b82b0 Mon Sep 17 00:00:00 2001 From: Jaishree Vyas Date: Tue, 3 Dec 2024 15:57:38 +0100 Subject: [PATCH] Doc: Add setModel(open) option to the documentation Changed the Model Dialogs section adding open() function. Task-number: QTBUG-127777 Pick-to: 6.8 Change-Id: If5086f4e2226c4d032fe1bcfbf2ef550803973c8 Reviewed-by: Volker Hilsheimer (cherry picked from commit 40f7454c919501f3c984c8fe4eeb379b360d4789) Reviewed-by: Qt Cherry-pick Bot --- src/widgets/dialogs/qdialog.cpp | 38 ++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/src/widgets/dialogs/qdialog.cpp b/src/widgets/dialogs/qdialog.cpp index 9509ea98bcf..b45a189d37b 100644 --- a/src/widgets/dialogs/qdialog.cpp +++ b/src/widgets/dialogs/qdialog.cpp @@ -230,22 +230,30 @@ QVariant QDialogPrivate::styleHint(QPlatformDialogHelper::StyleHint hint) const the user to continue to use other windows in an application. The most common way to display a modal dialog is to call its - exec() function. When the user closes the dialog, exec() will - provide a useful \l{#return}{return value}. To close the dialog - and return the appropriate value, you must connect a default button, - e.g. an \uicontrol OK button to the accept() slot and a - \uicontrol Cancel button to the reject() slot. Alternatively, you - can call the done() slot with \c Accepted or \c Rejected. + \l open() function. Alternatively, you can call \l setModal(true) or + \l setWindowModality(), and then \l show(). In both cases, once the dialog is + displayed, the control is immediately returned to the caller. You must connect + to the \l finished() signal to know when the dialog is closed and what its + \l {#return} {return value} is. Alternatively, you can connect to the + \l accepted() and \l rejected() signals. - An alternative is to call setModal(true) or setWindowModality(), - then show(). Unlike exec(), show() returns control to the caller - immediately. Calling setModal(true) is especially useful for - progress dialogs, where the user must have the ability to interact - with the dialog, e.g. to cancel a long running operation. If you - use show() and setModal(true) together to perform a long operation, - you must call QCoreApplication::processEvents() periodically during - processing to enable the user to interact with the dialog. (See - QProgressDialog.) + When implementing a custom dialog, to close the dialog and return an + appropriate value, connect a default button, for example, an OK button, to the + \l accept() slot, and a Cancel button to the \l reject() slot. Alternatively, + you can call the \l done() slot with \c Accepted or \c Rejected. + + If you show the modal dialog to perform a long-running operation, it is + recommended to perform the operation in a background worker thread, so that + it does not interfere with the GUI thread. + + \warning When using \l open() or \l show(), the modal dialog should not be + created on the stack, so that it does not get destroyed as soon as the control + returns to the caller. + + \note There is a way to show a modal dialog in a blocking mode by calling + \l exec(). In this case, the control returns to the GUI thread only when the + dialog is closed. However, such approach is discouraged, because it creates a + nested event loop, which is not fully supported by some platforms. \section1 Modeless Dialogs