diff options
author | Gabriel de Dietrich <gabriel.dedietrich@theqtcompany.com> | 2015-03-27 16:34:42 +0100 |
---|---|---|
committer | Gabriel de Dietrich <gabriel.dedietrich@theqtcompany.com> | 2015-04-16 12:13:10 +0000 |
commit | 5da5925ca6c676a8b36ebd863267b04906ef57d2 (patch) | |
tree | ddb6095f818093ec7c31a2c960eb6742c2bd4747 | |
parent | 235abf6486c221e4dc763b614ac33771abdd8f3f (diff) | |
download | qtquickcontrols-5da5925ca6c676a8b36ebd863267b04906ef57d2.tar.gz |
TableView, TreeView: Refactor documentation
The problematic property is itemDelegate which has different
properties attached in both cases. But it seems we can't over-
ride a property documentation blob unless we use .qdoc files.
We also update TreeViewStyle documentation.
Change-Id: Ie358e17767f67737b9fbf8ef96d8e646063fdca9
Reviewed-by: Caroline Chao <caroline.chao@theqtcompany.com>
-rw-r--r-- | src/controls/Private/BasicTableView.qml | 44 | ||||
-rw-r--r-- | src/controls/Styles/Base/TreeViewStyle.qml | 5 | ||||
-rw-r--r-- | src/controls/TableView.qml | 221 | ||||
-rw-r--r-- | src/controls/TreeView.qml | 194 | ||||
-rw-r--r-- | src/controls/doc/qtquickcontrols.qdocconf | 2 | ||||
-rw-r--r-- | src/controls/doc/src/qtquickcontrols-tableview.qdoc | 297 | ||||
-rw-r--r-- | src/controls/doc/src/qtquickcontrols-treeview.qdoc | 281 |
7 files changed, 596 insertions, 448 deletions
diff --git a/src/controls/Private/BasicTableView.qml b/src/controls/Private/BasicTableView.qml index f9753166..518f43af 100644 --- a/src/controls/Private/BasicTableView.qml +++ b/src/controls/Private/BasicTableView.qml @@ -86,40 +86,10 @@ ScrollView { property alias backgroundVisible: colorRect.visible /*! \qmlproperty Component BasicTableView::itemDelegate + \internal - This property defines a delegate to draw a specific cell. - - In the item delegate you have access to the following special properties: - \list - \li styleData.selected - if the item is currently selected - \li styleData.value - the value or text for this item - \li styleData.textColor - the default text color for an item - \li styleData.row - the index of the row - \li styleData.column - the index of the column - \li styleData.elideMode - the elide mode of the column - \li styleData.textAlignment - the horizontal text alignment of the column - \li styleData.pressed - true when the item is pressed (since QtQuick.Controls 1.3) - \li styleData.hasActiveFocus - true when the row has focus (since QtQuick.Controls 1.3) - \endlist - - Example: - \code - itemDelegate: Item { - Text { - anchors.verticalCenter: parent.verticalCenter - color: styleData.textColor - elide: styleData.elideMode - text: styleData.value - } - } - \endcode - - \note For performance reasons, created delegates can be recycled - across multiple table rows. This implies that when you make use of implicit - properties such as \c styleData.row or \c model, these values can change - after the delegate has been constructed. This means that you should not assume - that content is fixed when \c Component.onCompleted is called, but instead rely on - bindings to such properties. + Documentation differs between TableView and TreeView. + See qtquickcontrols-treeview.qdoc and qtquickcontrols-tableview.qdoc */ property Component itemDelegate: __style ? __style.itemDelegate : null @@ -201,13 +171,15 @@ ScrollView { */ readonly property alias columnCount: columnModel.count - /*! \qmlproperty string BasicTableView::section.property + /*! \qmlpropertygroup BasicTableView::section + \internal + \qmlproperty string BasicTableView::section.property \qmlproperty enumeration BasicTableView::section.criteria \qmlproperty Component BasicTableView::section.delegate \qmlproperty enumeration BasicTableView::section.labelPositioning - These properties determine the section labels. - \sa ListView::section + Moved to the qdoc files to keep the grouped property layout. + See qtquickcontrols-treeview.qdoc and qtquickcontrols-tableview.qdoc */ property alias section: listView.section diff --git a/src/controls/Styles/Base/TreeViewStyle.qml b/src/controls/Styles/Base/TreeViewStyle.qml index 774b1738..16b7b862 100644 --- a/src/controls/Styles/Base/TreeViewStyle.qml +++ b/src/controls/Styles/Base/TreeViewStyle.qml @@ -63,9 +63,12 @@ BasicTableViewStyle { In the branch delegate you have access to the following special properties: \list - \li styleData.column - the index of the column + \li styleData.row - the index of the view row + \li styleData.column - the index of the view column. Will always be 0 \li styleData.selected - if the item is currently selected \li styleData.textColor - the default text color for an item + \li styleData.index - the QModelIndex of the current item in the model + \li styleData.depth - the depth of the current item in the tree model \li styleData.isExpanded - true when the item is expanded \li styleData.hasChildren - true if the model index of the current item has children \li styleData.hasSibling - true if the model index of the current item has sibling diff --git a/src/controls/TableView.qml b/src/controls/TableView.qml index a5d67faf..f80aebbe 100644 --- a/src/controls/TableView.qml +++ b/src/controls/TableView.qml @@ -40,251 +40,38 @@ import QtQuick.Controls.Private 1.0 import QtQuick.Controls.Styles 1.1 import QtQuick.Window 2.1 -/*! - \qmltype TableView - \inqmlmodule QtQuick.Controls - \since 5.1 - \ingroup views - \brief Provides a list view with scroll bars, styling and header sections. - - \image tableview.png - - A TableView is similar to \l ListView, and adds scroll bars, selection, and - resizable header sections. As with \l ListView, data for each row is provided through a \l model: - - \code - ListModel { - id: libraryModel - ListElement { - title: "A Masterpiece" - author: "Gabriel" - } - ListElement { - title: "Brilliance" - author: "Jens" - } - ListElement { - title: "Outstanding" - author: "Frederik" - } - } - \endcode - - You provide title and size of a column header - by adding a \l TableViewColumn as demonstrated below. - - \code - TableView { - TableViewColumn { - role: "title" - title: "Title" - width: 100 - } - TableViewColumn { - role: "author" - title: "Author" - width: 200 - } - model: libraryModel - } - \endcode - - The header sections are attached to values in the \l model by defining - the model role they attach to. Each property in the model will - then be shown in their corresponding column. - - You can customize the look by overriding the \l {BasicTableView::}{itemDelegate}, - \l {BasicTableView::}{rowDelegate}, or \l {BasicTableView::}{headerDelegate} properties. - - The view itself does not provide sorting. This has to - be done on the model itself. However you can provide sorting - on the model, and enable sort indicators on headers. - -\list - \li int sortIndicatorColumn - The index of the current sort column - \li bool sortIndicatorVisible - Whether the sort indicator should be enabled - \li enum sortIndicatorOrder - Qt.AscendingOrder or Qt.DescendingOrder depending on state -\endlist - - You can create a custom appearance for a TableView by - assigning a \l {TableViewStyle}. -*/ - BasicTableView { id: root - /*! \qmlproperty model TableView::model - This property holds the model providing data for the table view. - - The model provides the set of data that is used to create the items in the view. - Models can be created directly in QML using ListModel, XmlListModel or VisualItemModel, - or provided by C++ model classes. \sa ListView::model - - Example model: - - \code - model: ListModel { - ListElement { - column1: "value 1" - column2: "value 2" - } - ListElement { - column1: "value 3" - column2: "value 4" - } - } - \endcode - \sa {qml-data-models}{Data Models} - */ property var model - /*! \qmlproperty int TableView::rowCount - The current number of rows */ readonly property int rowCount: __listView.count - - /*! \qmlproperty int TableView::currentRow - The current row index of the view. - The default value is \c -1 to indicate that no row is selected. - */ property alias currentRow: root.__currentRow - /*! \qmlsignal TableView::activated(int row) - - Emitted when the user activates an item by mouse or keyboard interaction. - Mouse activation is triggered by single- or double-clicking, depending on the platform. - - \a row int provides access to the activated row index. - - \note This signal is only emitted for mouse interaction that is not blocked in the row or item delegate. - - The corresponding handler is \c onActivated. - */ signal activated(int row) - - /*! \qmlsignal TableView::clicked(int row) - - Emitted when the user clicks a valid row by single clicking - - \a row int provides access to the clicked row index. - - \note This signal is only emitted if the row or item delegate does not accept mouse events. - - The corresponding handler is \c onClicked. - */ signal clicked(int row) - - /*! \qmlsignal TableView::doubleClicked(int row) - - Emitted when the user double clicks a valid row. - - \a row int provides access to the clicked row index. - - \note This signal is only emitted if the row or item delegate does not accept mouse events. - - The corresponding handler is \c onDoubleClicked. - */ signal doubleClicked(int row) - - /*! \qmlsignal TableView::pressAndHold(int row) - \since QtQuick.Controls 1.3 - - Emitted when the user presses and holds a valid row. - - \a row int provides access to the pressed row index. - - \note This signal is only emitted if the row or item delegate does not accept mouse events. - - The corresponding handler is \c onPressAndHold. - */ signal pressAndHold(int row) - /*! - \qmlmethod void TableView::positionViewAtRow( int row, PositionMode mode ) - - Positions the view such that the specified \a row is at the position defined by \a mode: - \list - \li ListView.Beginning - position item at the top of the view. - \li ListView.Center - position item in the center of the view. - \li ListView.End - position item at bottom of the view. - \li ListView.Visible - if any part of the item is visible then take no action, otherwise bring the item into view. - \li ListView.Contain - ensure the entire item is visible. If the item is larger than the view the item is positioned - at the top of the view. - \endlist - - If positioning the \a row creates an empty space at the beginning - or end of the view, then the view is positioned at the boundary. - - For example, to position the view at the end at startup: - - \code - Component.onCompleted: table.positionViewAtRow(rowCount -1, ListView.Contain) - \endcode - - Depending on how the model is populated, the model may not be ready when - TableView Component.onCompleted is called. In that case you may need to - delay the call to positionViewAtRow by using a \l [QtQml]{Timer}. - - \note This method should only be called after the component has completed. - */ function positionViewAtRow(row, mode) { __listView.positionViewAtIndex(row, mode) } - /*! - \qmlmethod int TableView::rowAt( int x, int y ) - - Returns the index of the visible row at the point \a x, \a y in content - coordinates. If there is no visible row at the point specified, \c -1 is returned. - - \note This method should only be called after the component has completed. - */ function rowAt(x, y) { var obj = root.mapToItem(__listView.contentItem, x, y) return __listView.indexAt(obj.x, obj.y) } - /*! \qmlproperty Selection TableView::selection - \since QtQuick.Controls 1.1 - - This property contains the current row-selection of the \l TableView. - The selection allows you to select, deselect or iterate over selected rows. - - \list - \li function \b clear() - deselects all rows - \li function \b selectAll() - selects all rows - \li function \b select(from, to) - select a range - \li functton \b deselect(from, to) - de-selects a range - \li function \b forEach(callback) - iterates over all selected rows - \li function \b contains(index) - checks whether the selection includes the given index - \li signal \b selectionChanged() - the current row selection changed - \li readonly property int \b count - the number of selected rows - \endlist - - \b Example: - \code - tableview.selection.select(0) // select row index 0 - - tableview.selection.select(1, 3) // select row indexes 1, 2 and 3 - - tableview.selection.deselect(0, 1) // deselects row index 0 and 1 - - tableview.selection.deselect(2) // deselects row index 2 - \endcode - - \b Example: To iterate over selected indexes, you can pass a callback function. - \a rowIndex is passed as as an argument to the callback function. - \code - tableview.selection.forEach( function(rowIndex) {console.log(rowIndex)} ) - \endcode - */ readonly property alias selection: selectionObject - onModelChanged: selection.clear() - style: Settings.styleComponent(Settings.style, "TableViewStyle.qml", root) Accessible.role: Accessible.Table + // Internal stuff. Do not look + + onModelChanged: selection.clear() + __viewTypeName: "TableView" __model: model diff --git a/src/controls/TreeView.qml b/src/controls/TreeView.qml index 534f2e91..08f0da4d 100644 --- a/src/controls/TreeView.qml +++ b/src/controls/TreeView.qml @@ -40,227 +40,33 @@ import QtQuick.Controls.Private 1.0 import QtQuick.Controls.Styles 1.2 import QtQml.Models 2.2 -/*! - \qmltype TreeView - \inqmlmodule QtQuick.Controls - \since 5.5 - \ingroup views - \brief Provides a tree view with scroll bars, styling and header sections. - - \image treeview.png - - A TreeView implements a tree representation of items from a model. - - Data for each row in the TreeView - is provided by the model. TreeView accepts models derived from the QAbstractItemModel class. - - You provide title and size of a column header - by adding a \l TableViewColumn as demonstrated below. - - \code - TreeView { - TableViewColumn { - title: "Name" - role: "fileName" - width: 300 - } - TableViewColumn { - title: "Permissions" - role: "filePermissions" - width: 100 - } - model: fileSystemModel - } - \endcode - - The header sections are attached to values in the \l model by defining - the model role they attach to. Each property in the model will - then be shown in their corresponding column. - - You can customize the look by overriding the \l {BasicTableView::itemDelegate}{itemDelegate}, - \l {BasicTableView::rowDelegate}{rowDelegate}, or \l {BasicTableView::headerDelegate}{headerDelegate} properties. - - The view itself does not provide sorting. This has to - be done on the model itself. However you can provide sorting - on the model, and enable sort indicators on headers. - -\list - \li int sortIndicatorColumn - The index of the current sort column - \li bool sortIndicatorVisible - Whether the sort indicator should be enabled - \li enum sortIndicatorOrder - Qt.AscendingOrder or Qt.DescendingOrder depending on state -\endlist - - You can create a custom appearance for a TreeView by - assigning a \l {TreeViewStyle}. -*/ - BasicTableView { id: root - /*! - \qmlproperty QAbstractItemModel TreeView::model - This property holds the model providing data for the tree view. - - The model provides the set of data that is displayed by the view. - The TreeView accept models derived from the QAbstractItemModel class. - */ property var model: null - /*! - \qmlproperty QModelIndex TreeView::currentIndex - The model index of the current row in the tree view. - */ readonly property var currentIndex: modelAdaptor.mapRowToModelIndex(__currentRow) - - /*! - \qmlproperty ItemSelectionModel TreeView::selection - - By default the selection model is \c null and only single selection is supported. - - To use a different selection mode as described in \l {BasicTableView::selectionMode}{selectionMode}, - an ItemSelectionModel must by set to the selection. - - For example: - - \code - TreeView { - model: myModel - selection: ItemSelectionModel { - model: myModel - } - TableViewColumn { - role: "name" - title: "Name - } - } - \endcode - - \sa {BasicTableView::selectionMode}{selectionMode} - - */ property ItemSelectionModel selection: null - /*! - \qmlsignal TreeView::activated(QModelIndex index) - - Emitted when the user activates a row in the tree by mouse or keyboard interaction. - Mouse activation is triggered by single- or double-clicking, depending on the platform. - - \a index is the model index of the activated row in the tree. - - \note This signal is only emitted for mouse interaction that is not blocked in the row or item delegate. - - The corresponding handler is \c onActivated. - */ signal activated(var index) - - /*! - \qmlsignal TreeView::clicked(QModelIndex index) - - Emitted when the user clicks a valid row in the tree by single clicking - - \a index is the model index of the clicked row in the tree. - - \note This signal is only emitted if the row or item delegate does not accept mouse events. - - The corresponding handler is \c onClicked. - */ signal clicked(var index) - - /*! - \qmlsignal TreeView::doubleClicked(QModelIndex index) - - Emitted when the user presses and holds a valid row in the tree. - - \a index is the model index of the double clicked row in the tree. - - \note This signal is only emitted if the row or item delegate does not accept mouse events. - - The corresponding handler is \c onPressAndHold. - */ signal doubleClicked(var index) - - /*! - \qmlsignal TreeView::pressAndHold(QModelIndex index) - - Emitted when the user presses and holds a valid row in the tree. - - \a index is the model index of the pressed row in the tree. - - \note This signal is only emitted if the row or item delegate does not accept mouse events. - - The corresponding handler is \c onPressAndHold. - */ signal pressAndHold(var index) - - /*! - \qmlsignal TreeView::expanded(QModelIndex index) - - Emitted when a valid row in the tree is expanded, displaying its children. - - \a index is the model index of the expanded row in the tree. - - \note This signal is only emitted if the row or item delegate does not accept mouse events. - - The corresponding handler is \c onExpanded. - */ signal expanded(var index) - - /*! - \qmlsignal TreeView::collapsed(QModelIndex index) - - Emitted when a valid row in the tree is collapsed, hiding its children. - - \a index is the model index of the collapsed row in the tree. - - \note This signal is only emitted if the row or item delegate does not accept mouse events. - - The corresponding handler is \c onCollapsed. - */ signal collapsed(var index) - /*! - \qmlmethod bool TreeView::isExpanded(QModelIndex index) - - Returns true if the model item index is expanded; otherwise returns false. - - \sa {expanded}, {expand} - */ function isExpanded(index) { return modelAdaptor.isExpanded(index) } - /*! - \qmlmethod void TreeView::collapse(QModelIndex index) - - Collapses the model item specified by the index. - - \sa {collapsed}, {isExpanded} - */ function collapse(index) { modelAdaptor.collapse(index) } - /*! - \qmlmethod void TreeView::expand(QModelIndex index) - - Expands the model item specified by the index. - - \sa {expanded}, {isExpanded} - */ function expand(index) { modelAdaptor.expand(index) } - /*! - \qmlmethod QModelIndex TreeView::indexAt( int x, int y ) - - Returns the model index of the visible row at the point \a x, \a y in content - coordinates. If there is no visible row at the point specified, an invalid - \l QModelIndex is returned. - - \note This method should only be called after the component has completed. - */ function indexAt(x, y) { var obj = root.mapToItem(__listView.contentItem, x, y) return modelAdaptor.mapRowToModelIndex(__listView.indexAt(obj.x, obj.y)) diff --git a/src/controls/doc/qtquickcontrols.qdocconf b/src/controls/doc/qtquickcontrols.qdocconf index 8d41247e..e9e5cacf 100644 --- a/src/controls/doc/qtquickcontrols.qdocconf +++ b/src/controls/doc/qtquickcontrols.qdocconf @@ -55,6 +55,8 @@ sources += ../Private/AbstractCheckable.qml \ ../Private/qquickabstractstyle.h \ ../Private/qquickabstractstyle.cpp +excludefiles += ../TableView.qml ../TreeView.qml + imagedirs += images \ ../../extras/doc/images diff --git a/src/controls/doc/src/qtquickcontrols-tableview.qdoc b/src/controls/doc/src/qtquickcontrols-tableview.qdoc new file mode 100644 index 00000000..15b99c18 --- /dev/null +++ b/src/controls/doc/src/qtquickcontrols-tableview.qdoc @@ -0,0 +1,297 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \qmltype TableView + \inqmlmodule QtQuick.Controls + \inherits BasicTableView + \since 5.1 + \ingroup views + \brief Provides a list view with scroll bars, styling and header sections. + + \image tableview.png + + A TableView is similar to \l ListView, and adds scroll bars, selection, and + resizable header sections. As with \l ListView, data for each row is provided through a \l model: + + \code + ListModel { + id: libraryModel + ListElement { + title: "A Masterpiece" + author: "Gabriel" + } + ListElement { + title: "Brilliance" + author: "Jens" + } + ListElement { + title: "Outstanding" + author: "Frederik" + } + } + \endcode + + You provide title and size of a column header + by adding a \l TableViewColumn as demonstrated below. + + \code + TableView { + TableViewColumn { + role: "title" + title: "Title" + width: 100 + } + TableViewColumn { + role: "author" + title: "Author" + width: 200 + } + model: libraryModel + } + \endcode + + The header sections are attached to values in the \l model by defining + the model role they attach to. Each property in the model will + then be shown in their corresponding column. + + You can customize the look by overriding the \l {BasicTableView::}{itemDelegate}, + \l {BasicTableView::}{rowDelegate}, or \l {BasicTableView::}{headerDelegate} properties. + + The view itself does not provide sorting. This has to + be done on the model itself. However you can provide sorting + on the model, and enable sort indicators on headers. + + \list + \li int sortIndicatorColumn - The index of the current sort column + \li bool sortIndicatorVisible - Whether the sort indicator should be enabled + \li enum sortIndicatorOrder - Qt.AscendingOrder or Qt.DescendingOrder depending on state + \endlist + + You can create a custom appearance for a TableView by + assigning a \l {TableViewStyle}. +*/ + +/*! \qmlproperty model TableView::model + This property holds the model providing data for the table view. + + The model provides the set of data that is used to create the items in the view. + Models can be created directly in QML using ListModel, XmlListModel or VisualItemModel, + or provided by C++ model classes. \sa ListView::model + + Example model: + + \code + model: ListModel { + ListElement { + column1: "value 1" + column2: "value 2" + } + ListElement { + column1: "value 3" + column2: "value 4" + } + } + \endcode + \sa {qml-data-models}{Data Models} +*/ + +/*! \qmlproperty int TableView::rowCount + The current number of rows +*/ + +/*! \qmlproperty int TableView::currentRow + The current row index of the view. + The default value is \c -1 to indicate that no row is selected. +*/ + +/*! \qmlsignal TableView::activated(int row) + + Emitted when the user activates an item by mouse or keyboard interaction. + Mouse activation is triggered by single- or double-clicking, depending on the platform. + + \a row int provides access to the activated row index. + + \note This signal is only emitted for mouse interaction that is not blocked in the row or item delegate. + + The corresponding handler is \c onActivated. +*/ + +/*! \qmlsignal TableView::clicked(int row) + + Emitted when the user clicks a valid row by single clicking + + \a row int provides access to the clicked row index. + + \note This signal is only emitted if the row or item delegate does not accept mouse events. + + The corresponding handler is \c onClicked. +*/ + +/*! \qmlsignal TableView::doubleClicked(int row) + + Emitted when the user double clicks a valid row. + + \a row int provides access to the clicked row index. + + \note This signal is only emitted if the row or item delegate does not accept mouse events. + + The corresponding handler is \c onDoubleClicked. +*/ + +/*! \qmlsignal TableView::pressAndHold(int row) + \since QtQuick.Controls 1.3 + + Emitted when the user presses and holds a valid row. + + \a row int provides access to the pressed row index. + + \note This signal is only emitted if the row or item delegate does not accept mouse events. + + The corresponding handler is \c onPressAndHold. +*/ + +/*! + \qmlmethod void TableView::positionViewAtRow( int row, PositionMode mode ) + + Positions the view such that the specified \a row is at the position defined by \a mode: + \list + \li ListView.Beginning - position item at the top of the view. + \li ListView.Center - position item in the center of the view. + \li ListView.End - position item at bottom of the view. + \li ListView.Visible - if any part of the item is visible then take no action, otherwise bring the item into view. + \li ListView.Contain - ensure the entire item is visible. If the item is larger than the view the item is positioned + at the top of the view. + \endlist + + If positioning the \a row creates an empty space at the beginning + or end of the view, then the view is positioned at the boundary. + + For example, to position the view at the end at startup: + + \code + Component.onCompleted: table.positionViewAtRow(rowCount -1, ListView.Contain) + \endcode + + Depending on how the model is populated, the model may not be ready when + TableView Component.onCompleted is called. In that case you may need to + delay the call to positionViewAtRow by using a \l [QtQml]{Timer}. + + \note This method should only be called after the component has completed. +*/ + +/*! + \qmlmethod int TableView::rowAt( int x, int y ) + + Returns the index of the visible row at the point \a x, \a y in content + coordinates. If there is no visible row at the point specified, \c -1 is returned. + + \note This method should only be called after the component has completed. +*/ + +/*! \qmlproperty Selection TableView::selection + \since QtQuick.Controls 1.1 + + This property contains the current row-selection of the \l TableView. + The selection allows you to select, deselect or iterate over selected rows. + + \list + \li function \b clear() - deselects all rows + \li function \b selectAll() - selects all rows + \li function \b select(from, to) - select a range + \li functton \b deselect(from, to) - de-selects a range + \li function \b forEach(callback) - iterates over all selected rows + \li function \b contains(index) - checks whether the selection includes the given index + \li signal \b selectionChanged() - the current row selection changed + \li readonly property int \b count - the number of selected rows + \endlist + + \b Example: + \code + tableview.selection.select(0) // select row index 0 + + tableview.selection.select(1, 3) // select row indexes 1, 2 and 3 + + tableview.selection.deselect(0, 1) // deselects row index 0 and 1 + + tableview.selection.deselect(2) // deselects row index 2 + \endcode + + \b Example: To iterate over selected indexes, you can pass a callback function. + \a rowIndex is passed as as an argument to the callback function. + \code + tableview.selection.forEach( function(rowIndex) {console.log(rowIndex)} ) + \endcode +*/ + +/*! + \qmlproperty Component TableView::itemDelegate + + This property defines a delegate to draw a specific cell. + + In the item delegate you have access to the following special properties: + \list + \li styleData.selected - if the item is currently selected + \li styleData.value - the value or text for this item + \li styleData.textColor - the default text color for an item + \li styleData.row - the index of the view row + \li styleData.column - the index of the view column + \li styleData.elideMode - the elide mode of the column + \li styleData.textAlignment - the horizontal text alignment of the column + \li styleData.pressed - true when the item is pressed (since QtQuick.Controls 1.3) + \li styleData.hasActiveFocus - true when the row has focus (since QtQuick.Controls 1.3) + \endlist + + Example: + \code + itemDelegate: Item { + Text { + anchors.verticalCenter: parent.verticalCenter + color: styleData.textColor + elide: styleData.elideMode + text: styleData.value + } + } + \endcode + + \note For performance reasons, created delegates can be recycled + across multiple table rows. This implies that when you make use of implicit + properties such as \c styleData.row or \c model, these values can change + after the delegate has been constructed. This means that you should not assume + that content is fixed when \c Component.onCompleted is called, but instead rely on + bindings to such properties. +*/ + +/*! + \qmlproperty string TableView::section.property + \qmlproperty enumeration TableView::section.criteria + \qmlproperty Component TableView::section.delegate + \qmlproperty enumeration TableView::section.labelPositioning + + These properties determine the section labels. + \sa ListView::section +*/ diff --git a/src/controls/doc/src/qtquickcontrols-treeview.qdoc b/src/controls/doc/src/qtquickcontrols-treeview.qdoc new file mode 100644 index 00000000..fb186059 --- /dev/null +++ b/src/controls/doc/src/qtquickcontrols-treeview.qdoc @@ -0,0 +1,281 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \qmltype TreeView + \inqmlmodule QtQuick.Controls + \inherits BasicTableView + \since 5.5 + \ingroup views + \brief Provides a tree view with scroll bars, styling and header sections. + + \image treeview.png + + A TreeView implements a tree representation of items from a model. + + Data for each row in the TreeView + is provided by the model. TreeView accepts models derived from the QAbstractItemModel class. + + You provide title and size of a column header + by adding a \l TableViewColumn as demonstrated below. + + \code + TreeView { + TableViewColumn { + title: "Name" + role: "fileName" + width: 300 + } + TableViewColumn { + title: "Permissions" + role: "filePermissions" + width: 100 + } + model: fileSystemModel + } + \endcode + + The header sections are attached to values in the \l model by defining + the model role they attach to. Each property in the model will + then be shown in their corresponding column. + + You can customize the look by overriding the \l {TreeView::itemDelegate}{itemDelegate}, + \l {TreeView::rowDelegate}{rowDelegate}, or \l {TreeView::headerDelegate}{headerDelegate} properties. + + The view itself does not provide sorting. This has to + be done on the model itself. However you can provide sorting + on the model, and enable sort indicators on headers. + + \list + \li int sortIndicatorColumn - The index of the current sort column + \li bool sortIndicatorVisible - Whether the sort indicator should be enabled + \li enum sortIndicatorOrder - Qt.AscendingOrder or Qt.DescendingOrder depending on state + \endlist + + You can create a custom appearance for a TreeView by + assigning a \l {TreeViewStyle}. +*/ + +/*! + \qmlproperty Component TreeView::itemDelegate + + This property defines a delegate to draw a specific cell. + + In the item delegate you have access to the following special properties: + \list + \li styleData.selected - if the item is currently selected + \li styleData.value - the value or text for this item + \li styleData.textColor - the default text color for an item + \li styleData.row - the index of the view row + \li styleData.column - the index of the view column + \li styleData.elideMode - the elide mode of the column + \li styleData.textAlignment - the horizontal text alignment of the column + \li styleData.pressed - true when the item is pressed + \li styleData.hasActiveFocus - true when the row has focus + \li styleData.index - the QModelIndex of the current item in the model + \li styleData.depth - the depth of the current item in the model + \li styleData.isExpanded - true when the item is expanded + \li styleData.hasChildren - true if the model index of the current item has or can have children + \li styleData.hasSibling - true if the model index of the current item has a sibling + \endlist + + Example: + \code + itemDelegate: Item { + Text { + anchors.verticalCenter: parent.verticalCenter + color: styleData.textColor + elide: styleData.elideMode + text: styleData.value + } + } + \endcode + + \note For performance reasons, created delegates can be recycled + across multiple table rows. This implies that when you make use of implicit + properties such as \c styleData.row or \c model, these values can change + after the delegate has been constructed. This means that you should not assume + that content is fixed when \c Component.onCompleted is called, but instead rely on + bindings to such properties. +*/ + +/*! + \qmlproperty string TreeView::section.property + \qmlproperty enumeration TreeView::section.criteria + \qmlproperty Component TreeView::section.delegate + \qmlproperty enumeration TreeView::section.labelPositioning + + These properties determine the section labels. + \sa ListView::section +*/ + +/*! + \qmlproperty QAbstractItemModel TreeView::model + This property holds the model providing data for the tree view. + + The model provides the set of data that is displayed by the view. + The TreeView accept models derived from the QAbstractItemModel class. +*/ + +/*! + \qmlproperty QModelIndex TreeView::currentIndex + The model index of the current row in the tree view. +*/ + +/*! + \qmlproperty ItemSelectionModel TreeView::selection + + By default the selection model is \c null and only single selection is supported. + + To use a different selection mode as described in \l {BasicTableView::selectionMode}{selectionMode}, + an ItemSelectionModel must by set to the selection. + + For example: + + \code + TreeView { + model: myModel + selection: ItemSelectionModel { + model: myModel + } + TableViewColumn { + role: "name" + title: "Name + } + } + \endcode + + \sa {BasicTableView::selectionMode}{selectionMode} + +*/ + +/*! + \qmlsignal TreeView::activated(QModelIndex index) + + Emitted when the user activates a row in the tree by mouse or keyboard interaction. + Mouse activation is triggered by single- or double-clicking, depending on the platform. + + \a index is the model index of the activated row in the tree. + + \note This signal is only emitted for mouse interaction that is not blocked in the row or item delegate. + + The corresponding handler is \c onActivated. +*/ + +/*! + \qmlsignal TreeView::clicked(QModelIndex index) + + Emitted when the user clicks a valid row in the tree by single clicking + + \a index is the model index of the clicked row in the tree. + + \note This signal is only emitted if the row or item delegate does not accept mouse events. + + The corresponding handler is \c onClicked. +*/ + +/*! + \qmlsignal TreeView::doubleClicked(QModelIndex index) + + Emitted when the user presses and holds a valid row in the tree. + + \a index is the model index of the double clicked row in the tree. + + \note This signal is only emitted if the row or item delegate does not accept mouse events. + + The corresponding handler is \c onPressAndHold. +*/ + +/*! + \qmlsignal TreeView::pressAndHold(QModelIndex index) + + Emitted when the user presses and holds a valid row in the tree. + + \a index is the model index of the pressed row in the tree. + + \note This signal is only emitted if the row or item delegate does not accept mouse events. + + The corresponding handler is \c onPressAndHold. +*/ + +/*! + \qmlsignal TreeView::expanded(QModelIndex index) + + Emitted when a valid row in the tree is expanded, displaying its children. + + \a index is the model index of the expanded row in the tree. + + \note This signal is only emitted if the row or item delegate does not accept mouse events. + + The corresponding handler is \c onExpanded. +*/ + +/*! + \qmlsignal TreeView::collapsed(QModelIndex index) + + Emitted when a valid row in the tree is collapsed, hiding its children. + + \a index is the model index of the collapsed row in the tree. + + \note This signal is only emitted if the row or item delegate does not accept mouse events. + + The corresponding handler is \c onCollapsed. +*/ + +/*! + \qmlmethod bool TreeView::isExpanded(QModelIndex index) + + Returns true if the model item index is expanded; otherwise returns false. + + \sa {expanded}, {expand} +*/ + +/*! + \qmlmethod void TreeView::collapse(QModelIndex index) + + Collapses the model item specified by the index. + + \sa {collapsed}, {isExpanded} +*/ + +/*! + \qmlmethod void TreeView::expand(QModelIndex index) + + Expands the model item specified by the index. + + \sa {expanded}, {isExpanded} +*/ + +/*! + \qmlmethod QModelIndex TreeView::indexAt( int x, int y ) + + Returns the model index of the visible row at the point \a x, \a y in content + coordinates. If there is no visible row at the point specified, an invalid + \l QModelIndex is returned. + + \note This method should only be called after the component has completed. +*/ |