From b32cd6480c332ca14e472d7e164914c7d3f7aaa5 Mon Sep 17 00:00:00 2001 From: Mitch Curtis Date: Fri, 7 Oct 2016 13:31:54 +0200 Subject: ComboBox: fix documentation review findings Change-Id: Iba9bdd74ab5b9865a2314ccc460fa44b9ea35be5 Task-number: QTBUG-55904 Reviewed-by: J-P Nurmi --- .../doc/images/qtquickcontrols2-combobox.gif | Bin 0 -> 7873 bytes .../doc/images/qtquickcontrols2-combobox.png | Bin 4984 -> 0 bytes .../controls/doc/src/qtquickcontrols2-input.qdoc | 2 +- src/quicktemplates2/qquickcombobox.cpp | 56 ++++++++++++++++++--- 4 files changed, 50 insertions(+), 8 deletions(-) create mode 100644 src/imports/controls/doc/images/qtquickcontrols2-combobox.gif delete mode 100644 src/imports/controls/doc/images/qtquickcontrols2-combobox.png (limited to 'src') diff --git a/src/imports/controls/doc/images/qtquickcontrols2-combobox.gif b/src/imports/controls/doc/images/qtquickcontrols2-combobox.gif new file mode 100644 index 00000000..966a2d4a Binary files /dev/null and b/src/imports/controls/doc/images/qtquickcontrols2-combobox.gif differ diff --git a/src/imports/controls/doc/images/qtquickcontrols2-combobox.png b/src/imports/controls/doc/images/qtquickcontrols2-combobox.png deleted file mode 100644 index e687fb0e..00000000 Binary files a/src/imports/controls/doc/images/qtquickcontrols2-combobox.png and /dev/null differ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc index c3583fd1..ce7b6aa4 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc @@ -42,7 +42,7 @@ \section1 ComboBox Control - \image qtquickcontrols2-combobox.png + \image qtquickcontrols2-combobox.gif \l ComboBox is used to select a value from a static multiple-line drop-down list. It is not possible to add new values, and only one option can be selected. diff --git a/src/quicktemplates2/qquickcombobox.cpp b/src/quicktemplates2/qquickcombobox.cpp index 278f8608..52ee2b49 100644 --- a/src/quicktemplates2/qquickcombobox.cpp +++ b/src/quicktemplates2/qquickcombobox.cpp @@ -58,15 +58,15 @@ QT_BEGIN_NAMESPACE \ingroup qtquickcontrols2-input \brief A combined button and popup list taking minimal space. - \image qtquickcontrols2-combobox.png + \image qtquickcontrols2-combobox.gif ComboBox is a combined button and popup list. It provides a means of presenting a list of options to the user in a way that takes up the minimum amount of screen space. ComboBox is populated with a data model. The data model is commonly - a JavaScript array, a \l ListModel or an integer, but also other types - of \l {qml-data-models}{data models} are supported. + a JavaScript array, a \l ListModel or an integer, but other types + of \l {qml-data-models}{data models} are also supported. \code ComboBox { @@ -74,6 +74,8 @@ QT_BEGIN_NAMESPACE } \endcode + \section1 ComboBox Model Roles + ComboBox is able to visualize standard \l {qml-data-models}{data models} that provide the \c modelData role: \list @@ -108,6 +110,12 @@ QT_BEGIN_NAMESPACE This signal is emitted when the item at \a index is activated by the user. + An item is activated when it is selected while the popup is open, + causing the popup to close (and \l currentIndex to change), + or while the popup is closed and the combo box is navigated via + keyboard, causing the \l currentIndex to change. + The \l currentIndex property is set to \a index. + \sa currentIndex */ @@ -116,6 +124,9 @@ QT_BEGIN_NAMESPACE This signal is emitted when the item at \a index in the popup list is highlighted by the user. + The highlighted signal is only emitted when the popup is open and an item + is highlighted, but not necessarily \l activated. + \sa highlightedIndex */ @@ -468,6 +479,10 @@ void QQuickComboBox::setPressed(bool pressed) This property holds the index of the highlighted item in the combo box popup list. + When a highlighted item is activated, the popup is closed, \l currentIndex + is set to \c highlightedIndex, and the value of this property is reset to + \c -1, as there is no longer a highlighted item. + \sa highlighted(), currentIndex */ int QQuickComboBox::highlightedIndex() const @@ -481,7 +496,7 @@ int QQuickComboBox::highlightedIndex() const This property holds the index of the current item in the combo box. - \sa activated(), currentText + \sa activated(), currentText, highlightedIndex */ int QQuickComboBox::currentIndex() const { @@ -567,7 +582,10 @@ void QQuickComboBox::resetDisplayText() This property holds the model role used for populating the combo box. - \sa model, currentText, displayText + When the model has multiple roles, \c textRole can be set to determine + which role should be displayed. + + \sa model, currentText, displayText, {ComboBox Model Roles} */ QString QQuickComboBox::textRole() const { @@ -592,6 +610,22 @@ void QQuickComboBox::setTextRole(const QString &role) This property holds a delegate that presents an item in the combo box popup. + It is recommended to use \l ItemDelegate (or any other \l AbstractButton + derivatives) as the delegate. This ensures that the interaction works as + expected, and the popup will automatically close when appropriate. When + other types are used as the delegate, the popup must be closed manually. + For example, if \l MouseArea is used: + + \code + delegate: Rectangle { + // ... + MouseArea { + // ... + onClicked: comboBox.popup.close() + } + } + \endcode + \sa ItemDelegate, {Customizing ComboBox} */ QQmlComponent *QQuickComboBox::delegate() const @@ -618,6 +652,8 @@ void QQuickComboBox::setDelegate(QQmlComponent* delegate) \qmlproperty Item QtQuick.Controls::ComboBox::indicator This property holds the drop indicator item. + + \sa {Customizing ComboBox} */ QQuickItem *QQuickComboBox::indicator() const { @@ -645,6 +681,12 @@ void QQuickComboBox::setIndicator(QQuickItem *indicator) This property holds the popup. + The popup can be opened or closed manually, if necessary: + + \code + onSpecialEvent: comboBox.popup.close() + \endcode + \sa {Customizing ComboBox} */ QQuickPopup *QQuickComboBox::popup() const @@ -761,7 +803,7 @@ int QQuickComboBox::find(const QString &text, Qt::MatchFlags flags) const \qmlmethod void QtQuick.Controls::ComboBox::incrementCurrentIndex() Increments the current index of the combo box, or the highlighted - index if the popup list when it is visible. + index if the popup list is visible. \sa currentIndex, highlightedIndex */ @@ -775,7 +817,7 @@ void QQuickComboBox::incrementCurrentIndex() \qmlmethod void QtQuick.Controls::ComboBox::decrementCurrentIndex() Decrements the current index of the combo box, or the highlighted - index if the popup list when it is visible. + index if the popup list is visible. \sa currentIndex, highlightedIndex */ -- cgit v1.2.3