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>

2 files changed, 578 insertions, 0 deletions

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.
+*/