Doc: Add setModel(open) option to the documentation

Changed the Model Dialogs section adding open() function.

Task-number: QTBUG-127777
Change-Id: If5086f4e2226c4d032fe1bcfbf2ef550803973c8
Reviewed-by: Volker Hilsheimer <[email protected]>
(cherry picked from commit 40f7454c919501f3c984c8fe4eeb379b360d4789)
Reviewed-by: Qt Cherry-pick Bot <[email protected]>
(cherry picked from commit 423659af18ac3c78bf93a6b6160f863ffe9b82b0)

1 files changed, 24 insertions, 16 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.
-
-    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.)
+    \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.
+
+    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