diff options
author | Shawn Rutledge <shawn.rutledge@digia.com> | 2014-07-09 10:33:10 +0200 |
---|---|---|
committer | Shawn Rutledge <shawn.rutledge@digia.com> | 2014-07-09 14:59:03 +0200 |
commit | a312fc13d99c20f78d5950a69f4b8b65828bd6c2 (patch) | |
tree | 959dde16d75ffa8df9c2ff52d73c2c32eb1081fc /src/dialogs/qquickdialog.cpp | |
parent | f2a3019e4332b756b5b27092768bf4039dca7c7a (diff) | |
download | qtquickcontrols-a312fc13d99c20f78d5950a69f4b8b65828bd6c2.tar.gz |
Dialog: Add missing docs
Also fixed a qWarning and updated example import statement.
Change-Id: I873b52e297bbefe66c6c131573804eee98c40a2f
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Diffstat (limited to 'src/dialogs/qquickdialog.cpp')
-rw-r--r-- | src/dialogs/qquickdialog.cpp | 229 |
1 files changed, 220 insertions, 9 deletions
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 |