Dialog: Add missing docs

Also fixed a qWarning and updated example import statement.

Change-Id: I873b52e297bbefe66c6c131573804eee98c40a2f
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

3 files changed, 223 insertions, 12 deletions

diff --git a/examples/quick/dialogs/systemdialogs/CustomDialogs.qml b/examples/quick/dialogs/systemdialogs/CustomDialogs.qml
index 81c06b7e..ffc3265b 100644
--- a/examples/quick/dialogs/systemdialogs/CustomDialogs.qml
+++ b/examples/quick/dialogs/systemdialogs/CustomDialogs.qml
@@ -38,7 +38,7 @@
 **
 ****************************************************************************/
 
-import QtQuick 2.2
+import QtQuick 2.3
 import QtQuick.Controls 1.2
 import QtQuick.Dialogs 1.2
 import QtQuick.Layouts 1.1
diff --git a/src/dialogs/plugin.cpp b/src/dialogs/plugin.cpp
index 74672f65..aef31e50 100644
--- a/src/dialogs/plugin.cpp
+++ b/src/dialogs/plugin.cpp
@@ -70,7 +70,7 @@ static void initResources()
 QT_BEGIN_NAMESPACE
 
 /*!
-    \qmlmodule QtQuick.Dialogs 1.1
+    \qmlmodule QtQuick.Dialogs 1.2
     \title Qt Quick Dialogs QML Types
     \ingroup qmlmodules
     \brief Provides QML types for standard file, color picker and message dialogs
@@ -80,7 +80,7 @@ QT_BEGIN_NAMESPACE
     To use the types in this module, import the module with the following line:
 
     \code
-    import QtQuick.Dialogs 1.1
+    import QtQuick.Dialogs 1.2
     \endcode
 */
 
diff --git a/src/dialogs/qquickdialog.cpp b/src/dialogs/qquickdialog.cpp
index bed69e7b..788c1e4c 100644
--- a/src/dialogs/qquickdialog.cpp
+++ b/src/dialogs/qquickdialog.cpp
@@ -51,17 +51,35 @@ QT_BEGIN_NAMESPACE
     \qmltype Dialog
     \instantiates QQuickDialog
     \inqmlmodule QtQuick.Dialogs
-    \ingroup qtquick-visual
-    \brief A generic QtQuick dialog wrapper with standard buttons
+    \ingroup dialogs
+    \brief A generic QtQuick dialog wrapper with standard buttons.
     \since 5.3
 
-    Dialog provides an item with a platform-tailored button box for a dialog.
-    The \l implementation Item is the default property (the only allowed child
-    element).
+    The purpose of Dialog is to wrap arbitrary content into a \e {dialog window}
+    including a row of platform-tailored buttons.
+
+    The \l contentItem is the default property (the only allowed child
+    element), and items declared inside the Dialog will actually be children of
+    another Item inside the \c contentItem. The row of \l standardButtons will
+    also be inside \c contentItem below the declared content, and Dialog will
+    attempt to size itself to fit the content and the buttons.
+
+    Alternatively it is possible to bind \l contentItem to a custom Item, in
+    which case there will be no buttons, no margins, and the custom content
+    will fill the whole dialog.  This is much like creating a \l Window,
+    except that on platforms which do not support showing multiple windows,
+    the window borders will be simulated and it will be shown in same scene.
+
+    \note do not attempt to bind the width or height of the dialog to the width
+    or height of its content, because Dialog already tries to size itself
+    to the content. If your goal is to change or eliminate the margins, you
+    must override \l contentItem. If your goal is simply to show a window
+    (whether modal or not), and your platform supports it, it is simpler to use
+    \l Window instead.
 */
 
 /*!
-    \qmlsignal QtQuick::Dialogs::Dialog::accepted
+    \qmlsignal Dialog::accepted()
 
     This signal is emitted by \l accept().
 
@@ -69,7 +87,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \qmlsignal QtQuick::Dialogs::Dialog::rejected
+    \qmlsignal Dialog::rejected()
 
     This signal is emitted by \l reject().
 
@@ -77,6 +95,106 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \qmlsignal Dialog::discard()
+
+    This signal is emitted when the user has pressed the \gui Discard button.
+
+    The corresponding handler is \c onDiscard.
+*/
+
+/*!
+    \qmlsignal Dialog::help()
+
+    This signal is emitted when the user has pressed the \gui Help button.
+    Depending on platform, the dialog may not be automatically dismissed
+    because the help that your application provides may need to be relevant to
+    the text shown in this dialog in order to assist the user in making a
+    decision. However on other platforms it's not possible to show a dialog and
+    a help window at the same time. If you want to be sure that the dialog will
+    close, you can set \l visible to \c false in your handler.
+
+    The corresponding handler is \c onHelp.
+*/
+
+/*!
+    \qmlsignal Dialog::yes()
+
+    This signal is emitted when the user has pressed any button which has
+    the \l {QMessageBox::YesRole} {YesRole}: \gui Yes or \gui {Yes to All}.
+
+    The corresponding handler is \c onYes.
+*/
+
+/*!
+    \qmlsignal Dialog::no()
+
+    This signal is emitted when the user has pressed any button which has
+    the \l {QMessageBox::NoRole} {NoRole}: \gui No or \gui {No to All}.
+
+    The corresponding handler is \c onNo.
+*/
+
+/*!
+    \qmlsignal Dialog::apply()
+
+    This signal is emitted when the user has pressed the \gui Apply button.
+
+    The corresponding handler is \c onApply.
+*/
+
+/*!
+    \qmlsignal Dialog::reset()
+
+    This signal is emitted when the user has pressed any button which has
+    the \l {QMessageBox::ResetRole} {ResetRole}: \gui Reset or \gui {Restore Defaults}.
+
+    The corresponding handler is \c onReset.
+*/
+
+/*!
+    \qmlproperty bool Dialog::visible
+
+    This property holds whether the dialog is visible. By default this is
+    \c false.
+
+    \sa modality
+*/
+
+/*!
+    \qmlproperty Qt::WindowModality Dialog::modality
+
+    Whether the dialog should be shown modal with respect to the window
+    containing the dialog's parent Item, modal with respect to the whole
+    application, or non-modal.
+
+    By default it is \c Qt.WindowModal.
+
+    Modality does not mean that there are any blocking calls to wait for the
+    dialog to be accepted or rejected: only that the user will be prevented
+    from interacting with the parent window or the application windows
+    until the dialog is dismissed.
+*/
+
+/*!
+    \qmlmethod void Dialog::open()
+
+    Shows the dialog to the user. It is equivalent to setting \l visible to
+    \c true.
+*/
+
+/*!
+    \qmlmethod void Dialog::close()
+
+    Closes the dialog.
+*/
+
+/*!
+    \qmlproperty string Dialog::title
+
+    The title of the dialog window.
+*/
+
+/*!
     \class QQuickDialog
     \inmodule QtQuick.Dialogs
     \internal
@@ -182,9 +300,33 @@ void QQuickDialog::setStandardButtons(StandardButtons buttons)
 */
 
 /*!
-    \qmlproperty QObject Dialog::implementation
+    \qmlproperty QObject Dialog::contentItem
 
     The QML object which implements the dialog contents. Should be an \l Item.
+
+    For example the following dialog will show custom content and no buttons:
+
+    \qml
+    import QtQuick 2.3
+    import QtQuick.Controls 1.2
+    import QtQuick.Dialogs 1.2
+
+    Dialog {
+        visible: true
+        title: "Blue sky dialog"
+
+        contentItem: Rectangle {
+            color: "lightskyblue"
+            implicitWidth: 400
+            implicitHeight: 100
+            Text {
+                text: "Hello blue sky!"
+                color: "navy"
+                anchors.centerIn: parent
+            }
+        }
+    }
+    \endqml
 */
 
 void QQuickDialog::click(QPlatformDialogHelper::StandardButton button, QPlatformDialogHelper::ButtonRole role)
@@ -218,7 +360,7 @@ void QQuickDialog::click(QPlatformDialogHelper::StandardButton button, QPlatform
         emit reset();
         break;
     default:
-        qWarning("unhandled MessageDialog button %d with role %d", (int)button, (int)role);
+        qWarning("unhandled Dialog button %d with role %d", (int)button, (int)role);
     }
 }
 
@@ -274,4 +416,73 @@ void QQuickDialog::reject() {
     QQuickAbstractDialog::reject();
 }
 
+// TODO after QTBUG-35019 is fixed: fix links to this module's enums
+// rather than linking to those in QMessageBox
+/*!
+    \enum QQuickStandardButton::StandardButton
+
+    This enum specifies a button with a standard label to be used on a dialog.
+*/
+
+/*!
+    \qmlproperty StandardButtons Dialog::standardButtons
+
+    Dialog has a row of buttons along the bottom, each of which has a
+    \l {QMessageBox::ButtonRole} {ButtonRole} that determines which signal
+    will be emitted when the button is pressed. You can also find out which
+    specific button was pressed after the fact via the \l clickedButton
+    property. You can control which buttons are available by setting
+    standardButtons to a bitwise-or combination of the following flags:
+
+    \table
+    \row \li StandardButton.Ok          \li An \gui OK button defined with the \l {QMessageBox::AcceptRole} {AcceptRole}.
+    \row \li  StandardButton.Open       \li An \gui Open button defined with the \l {QMessageBox::AcceptRole} {AcceptRole}.
+    \row \li  StandardButton.Save       \li A \gui Save button defined with the \l {QMessageBox::AcceptRole} {AcceptRole}.
+    \row \li  StandardButton.Cancel     \li A \gui Cancel button defined with the \l {QMessageBox::RejectRole} {RejectRole}.
+    \row \li  StandardButton.Close      \li A \gui Close button defined with the \l {QMessageBox::RejectRole} {RejectRole}.
+    \row \li  StandardButton.Discard    \li A \gui Discard or \gui {Don't Save} button, depending on the platform,
+                                        defined with the \l {QMessageBox::DestructiveRole} {DestructiveRole}.
+    \row \li  StandardButton.Apply      \li An \gui Apply button defined with the \l {QMessageBox::ApplyRole} {ApplyRole}.
+    \row \li  StandardButton.Reset      \li A \gui Reset button defined with the \l {QMessageBox::ResetRole} {ResetRole}.
+    \row \li  StandardButton.RestoreDefaults \li A \gui {Restore Defaults} button defined with the \l {QMessageBox::ResetRole} {ResetRole}.
+    \row \li  StandardButton.Help       \li A \gui Help button defined with the \l {QMessageBox::HelpRole} {HelpRole}.
+    \row \li  StandardButton.SaveAll    \li A \gui {Save All} button defined with the \l {QMessageBox::AcceptRole} {AcceptRole}.
+    \row \li  StandardButton.Yes        \li A \gui Yes button defined with the \l {QMessageBox::YesRole} {YesRole}.
+    \row \li  StandardButton.YesToAll   \li A \gui {Yes to All} button defined with the \l {QMessageBox::YesRole} {YesRole}.
+    \row \li  StandardButton.No         \li A \gui No button defined with the \l {QMessageBox::NoRole} {NoRole}.
+    \row \li  StandardButton.NoToAll    \li A \gui {No to All} button defined with the \l {QMessageBox::NoRole} {NoRole}.
+    \row \li  StandardButton.Abort      \li An \gui Abort button defined with the \l {QMessageBox::RejectRole} {RejectRole}.
+    \row \li  StandardButton.Retry      \li A \gui Retry button defined with the \l {QMessageBox::AcceptRole} {AcceptRole}.
+    \row \li  StandardButton.Ignore     \li An \gui Ignore button defined with the \l {QMessageBox::AcceptRole} {AcceptRole}.
+    \endtable
+
+    For example the following dialog will show a calendar with the ability to
+    save or cancel a date:
+
+    \qml
+    import QtQuick 2.3
+    import QtQuick.Controls 1.2
+    import QtQuick.Dialogs 1.2
+
+    Dialog {
+        id: dateDialog
+        visible: true
+        title: "Choose a date"
+        standardButtons: StandardButton.Save | StandardButton.Cancel
+
+        onAccepted: console.log("Saving the date " +
+            calendar.selectedDate.toLocaleDateString())
+
+        Calendar {
+            id: calendar
+            onDoubleClicked: dateDialog.click(StandardButton.Save)
+        }
+    }
+    \endqml
+
+    The default is \c StandardButton.Ok.
+
+    The enum values are the same as in \l QMessageBox::StandardButtons.
+*/
+
 QT_END_NAMESPACE