From 9ee7b52f3234d12c7617ddf716f54e1923d3cded Mon Sep 17 00:00:00 2001
From: Paul Wicking <paul.wicking@qt.io>
Date: Mon, 16 Jul 2018 15:35:47 +0200
Subject: Doc: Extend ItemSelectionModel QML documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This change provides a bare minimum documentation for the
ItemSelectionModel QML type.

Task-number: QTBUG-58090
Change-Id: I0e232f8e05e7629d6f573f8dce21154d0ec307e5
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
---
 src/qml/types/qqmlitemselectionmodel.qdoc | 63 +++++++++++++++++++++++++++++--
 1 file changed, 59 insertions(+), 4 deletions(-)

(limited to 'src/qml/types/qqmlitemselectionmodel.qdoc')

diff --git a/src/qml/types/qqmlitemselectionmodel.qdoc b/src/qml/types/qqmlitemselectionmodel.qdoc
index 64c0429acd..7ddfd79217 100644
--- a/src/qml/types/qqmlitemselectionmodel.qdoc
+++ b/src/qml/types/qqmlitemselectionmodel.qdoc
@@ -35,9 +35,6 @@
     \brief Instantiates a QItemSelectionModel to be used in conjunction
     with a QAbstractItemModel and any view supporting it.
 
-    This page only enumerates the properties, methods, and signals available in QML.
-    See \l QItemSelectionModel for the actual documentation of this class.
-
     \sa QItemSelectionModel, {Models and Views in Qt Quick}
 */
 
@@ -76,34 +73,67 @@
 
 /*!
     \qmlmethod bool ItemSelectionModel::isSelected(QModelIndex index)
+
+    Returns \c true if the given model item \a index is selected.
 */
 
 /*!
     \qmlmethod bool ItemSelectionModel::isRowSelected(int row, QModelIndex parent)
+
+    Returns \c true if all items are selected in the \a row with the given
+    \a parent.
+
+    Note that this function is usually faster than calling isSelected()
+    on all items in the same row, and that unselectable items are ignored.
 */
 
 /*!
     \qmlmethod bool ItemSelectionModel::isColumnSelected(int column, QModelIndex parent)
+
+    Returns \c true if all items are selected in the \a column with the given
+    \a parent.
+
+    Note that this function is usually faster than calling isSelected()
+    on all items in the same column, and that unselectable items are ignored.
 */
 
 /*!
     \qmlmethod bool ItemSelectionModel::rowIntersectsSelection(int row, QModelIndex parent)
+
+    Returns \c true if there are any items selected in the \a row with the
+    given \a parent.
 */
 
 /*!
     \qmlmethod bool ItemSelectionModel::columnIntersectsSelection(int column, QModelIndex parent)
+
+    Returns \c true if there are any items selected in the \a column with the
+    given \a parent.
 */
 
 /*!
     \qmlmethod QModelIndexList ItemSelectionModel::selectedRows(int column)
+
+    Returns the indexes in the given \a column for the rows where all columns
+    are selected.
+
+    \sa selectedColumns()
 */
 
 /*!
     \qmlmethod QModelIndexList ItemSelectionModel::selectedColumns(int row)
+
+    Returns the indexes in the given \a row for columns where all rows are
+    selected.
+
+    \sa selectedRows()
 */
 
 /*!
-    \qmlmethod QItemSelection ItemSelectionModel::selection()
+    \qmlproperty object ItemSelectionModel::selection
+    \readonly
+
+    Holds the selection ranges stored in the selection model.
 */
 
 /*!
@@ -161,24 +191,49 @@
 
 /*!
     \qmlmethod void ItemSelectionModel::clear()
+
+    Clears the selection model. Emits selectionChanged() and currentChanged().
 */
 
 /*!
     \qmlmethod void ItemSelectionModel::reset()
+
+    Clears the selection model. Does not emit any signals.
 */
 
 /*!
     \qmlmethod void ItemSelectionModel::clearSelection()
+
+    Clears the selection in the selection model. Emits selectionChanged().
 */
 
 /*!
     \qmlmethod void ItemSelectionModel::clearCurrentIndex()
+
+    Clears the current index. Emits currentChanged().
 */
 
 /*!
     \qmlsignal ItemSelectionModel::selectionChanged(QItemSelection selected, QItemSelection deselected)
+
+    This signal is emitted whenever the selection changes. The change in the
+    selection is represented as an item selection of \a deselected items and
+    an item selection of \a selected items.
+
+    Note the that the current index changes independently from the selection.
+    Also note that this signal will not be emitted when the item model is reset.
+
+    \sa select(), currentChanged()
 */
 
 /*!
     \qmlsignal ItemSelectionModel::currentChanged(QModelIndex current, QModelIndex previous)
+
+    This signal is emitted whenever the current item changes. The \a previous
+    model item index is replaced by the \a current index as the selection's
+    current item.
+
+    Note that this signal will not be emitted when the item model is reset.
+
+    \sa currentIndex(), setCurrentIndex(), selectionChanged()
 */
-- 
cgit v1.2.3