Update API and documentation of TableView

Note that I renamed Column to TableViewColumn

Change-Id: I8968797cede9a117a6acac09997fba385ff76b30
Reviewed-by: Gabriel de Dietrich <gabriel.dedietrich@digia.com>

examples/ApplicationTemplate/qml/main.qml

@@ -71,7 +71,7 @@ ApplicationWindow {
             frame: false
             highlightOnFocus: false
             model: 40
-            TableColumn { title: "Left Column" }
+            TableViewColumn { title: "Left Column" }
         }
         TextArea {
             frame: false

examples/gallery/content/ModelView.qml

@@ -72,17 +72,17 @@ Item {
         model: dummyModel
         anchors.fill: parent
 
-        TableColumn {
+        TableViewColumn {
             role: "title"
             title: "Title"
             width: 120
         }
-        TableColumn {
+        TableViewColumn {
             role: "credit"
             title: "Credit"
             width: 120
         }
-        TableColumn {
+        TableViewColumn {
             role: "imagesource"
             title: "Image source"
             width: 200

examples/tableview/main.qml

@@ -132,17 +132,17 @@ Rectangle {
                     anchors.fill: parent
                     anchors.margins: 12
 
-                    TableColumn {
+                    TableViewColumn {
                         role: "title"
                         title: "Title"
                         width: 120
                     }
-                    TableColumn {
+                    TableViewColumn {
                         role: "credit"
                         title: "Credit"
                         width: 120
                     }
-                    TableColumn {
+                    TableViewColumn {
                         role: "imagesource"
                         title: "Image source"
                         width: 200
@@ -163,7 +163,7 @@ Rectangle {
                     anchors.fill: parent
                     anchors.margins: 12
 
-                    TableColumn {
+                    TableViewColumn {
                         role: "attributes"
                         title: "Text and Color"
                         width: 220
@@ -204,17 +204,17 @@ Rectangle {
                     model: largeModel
                     anchors.margins: 12
                     anchors.fill: parent
-                    TableColumn {
+                    TableViewColumn {
                         role: "name"
                         title: "Name"
                         width: 120
                     }
-                    TableColumn {
+                    TableViewColumn {
                         role: "age"
                         title: "Age"
                         width: 120
                     }
-                    TableColumn {
+                    TableViewColumn {
                         role: "gender"
                         title: "Gender"
                         width: 120
@@ -307,17 +307,17 @@ Rectangle {
                     sortIndicatorVisible: sortableCheckbox.checked
                     alternateRowColor: alternateCheckbox.checked
 
-                    TableColumn {
+                    TableViewColumn {
                         role: "name"
                         title: "Name"
                         width: 120
                     }
-                    TableColumn {
+                    TableViewColumn {
                         role: "age"
                         title: "Age"
                         width: 120
                     }
-                    TableColumn {
+                    TableViewColumn {
                         role: "sex"
                         title: "Sex"
                         width: 120

src/qtdesktop/TableView.qml

@@ -45,134 +45,190 @@ import QtDesktop.Private 1.0
 /*!
    \qmltype TableView
    \inqmlmodule QtDesktop 1.0
-   \ingroup tables
-   \brief TableView is an extended ListView that provides column and header support.
+   \ingroup views
+   \brief Provides a list view with scroll bars, styling and header sections.
 
+   \image tableview.png
 
- This component provides an item-view with resizable
- header sections.
+   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:
 
- You can style the drawn delegate by overriding the itemDelegate
- property. The following properties are supported for custom
- delegates:
-
- Note: Currently only row selection is available for this component
-
-\list
-\li  itemHeight - default platform size of item
-\li  itemWidth - default platform width of item
-\li  itemSelected - if the row is currently selected
-\li  itemValue - The text for this item
-\li  itemForeground - The default text color for an item
-\endlist
-
-\code
- For example:
-   itemDelegate: Item {
-       Text {
-           anchors.verticalCenter: parent.verticalCenter
-           color: itemForeground
-           elide: Text.ElideRight
-           text: itemValue
-        }
-    }
-\endcode
-
- Data for each row is provided through a model:
-
-\code
+ \code
  ListModel {
-    ListElement{ column1: "value 1"; column2: "value 2"}
-    ListElement{ column1: "value 3"; column2: "value 4"}
+    id: libraryModel
+    ListElement{ title: "A Masterpiece" ; author: "Gabriel" }
+    ListElement{ title: "Brilliance"    ; author: "Jens" }
+    ListElement{ title: "Outstanding"   ; author: "Frederik" }
  }
-\endcode
+ \endcode
 
- You provide title and size properties on TableColumns
- by setting the default header property :
+   You provide title and size of a column header
+   by adding a \l TableViewColumn to the default \l header property
+   as demonstrated below.
+ \code
 
-\code
  TableView {
-    TableColumn{ role: "column1" ; title: "Column 1" ; width:100}
-    TableColumn{ role: "column2" ; title: "Column 2" ; width:200}
-    model: datamodel
+    TableViewColumn{ role: "title"  ; title: "Title" ; width: 100 }
+    TableViewColumn{ role: "author" ; title: "Author" ; width: 200 }
+    model: libraryModel
  }
-\endcode
+ \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 itemDelegate,
+   \l rowDelegate or \l headerDelegate properties.
 
- The header sections are attached to values in the datamodel by defining
- the listmodel property they attach to. Each property in the model, will
- then be shown in each column section.
+   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.
 
- 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 sortColumn - The index of the currently selected sort header
-\li sortIndicatorVisible - If sort indicators should be enabled
-\li sortIndicatorDirection - "up" or "down" depending on state
+    \li sortColumn - The index of the currently selected sort header
+    \li sortIndicatorVisible - If sort indicators should be enabled
+    \li sortIndicatorDirection - "up" or "down" depending on state
 \endlist
 */
 
 ScrollArea {
     id: root
 
+    /*! This property holds the model providing data for the list.
+
+    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 */
     property variant model
 
     width: 200
     height: 200
 
+    /*! \internal */
     __scrollBarTopMargin: styleitem.style == "mac" ? headerrow.height : 0
 
-    // Cosmetic properties
+    /*! This property sets if the frame should paint the focus frame around its contents.
+        The default value is \c false.
+        \Note Only certain platforms such as Mac OS X will be affected by this property */
     property bool highlightOnFocus: false
+
+    /*! This property is set to \c true if the view alternates the row color.
+        The default value is \c true. */
     property bool alternateRowColor: true
+
+    /*! This property determines if the header is visible.
+        The default value is \c true. */
     property bool headerVisible: true
 
-    // Styling properties
+    /*! This property defines a delegate to draw a specific cell.
+
+    In the item delegate you have access to the following special properties:
+    \list
+    \li  itemHeight - default platform size of item
+    \li  itemWidth - default platform width of item
+    \li  itemSelected - if the row is currently selected
+    \li  itemValue - The text for this item
+    \li  itemForeground - The default text color for an item
+    \endlist
+    Example:
+     \code
+       itemDelegate: Item {
+           Text {
+               anchors.verticalCenter: parent.verticalCenter
+               color: itemForeground
+               elide: Text.ElideRight
+               text: itemValue
+            }
+        }
+    \endcode */
     property Component itemDelegate: standardDelegate
+
+    /*! This property defines a delegate to draw a row. */
     property Component rowDelegate: rowDelegate
+
+    /*! This property defines a delegate to draw a header. */
     property Component headerDelegate: headerDelegate
 
-    /*!
-        \qmlproperty color ScrollArea:backgroundColor
+    /*! \qmlproperty color TableView::backgroundColor
 
         This property sets the background color of the viewport.
-
-        The default value is the base color of the SystemPalette.
-
-    */
+        The default value is the base color of the SystemPalette. */
     property alias backgroundColor: colorRect.color
 
+    /*! This property sets if the frame should be visible.
+        The default value is \c true. */
     frame: true
 
-    // Sort properties
-    property int sortColumn // Index of currently selected sort column
-    property bool sortIndicatorVisible: false // enables or disables sort indicator
-    property string sortIndicatorDirection: "down" // "up" or "down" depending on current state
-
-    // Item properties
+    /*! Index of the currently selected sort column
+        The default value is \c 0. */
+    property int sortColumn
+
+    /*! This property shows or hides the sort indicator
+        \ Note the view itself does not sort the data.
+        The default value is \c false. */
+    property bool sortIndicatorVisible: false
+
+    /*! This sets the sorting direction of the sort indicator
+       The allowed values are:
+       \list
+       \li "up"
+       \li "down" - the default
+       \endlist  */
+    property string sortIndicatorDirection: "down"
+
+    /*! \qmlproperty Component TableView::header
+    This property contains the TableViewHeader items */
     default property alias header: listView.columnheader
+
+    /*! \qmlproperty Component TableView::contentHeader
+    This is the content header of the TableView */
     property alias contentHeader: listView.header
+
+    /*! \qmlproperty Component TableView::contentFooter
+    This is the content footer of the TableView */
     property alias contentFooter: listView.footer
+
+    /*! \qmlproperty Item TableView::currentItem
+    This is the current item of the TableView */
     property alias currentItem: listView.currentItem
 
-    // Viewport properties
+    /*! \qmlproperty int TableView::count
+    The current number of rows */
     property alias count: listView.count
-    property alias section: listView.section
 
-    property alias currentIndex: listView.currentIndex // Should this be currentRowIndex?
+    /*! \qmlproperty string TableView::section
+    The section of the view. See \l ListView::section */
+    readonly property alias section: listView.section
+
+    /*! \qmlproperty int TableView::currentIndex
+    The current row index of the view. */
+    property alias currentIndex: listView.currentIndex
 
     Accessible.role: Accessible.Table
 
-    // Signals
+    /*! \qmlsignal TableView::activated()
+        Emitted when a new row is selected by the user. */
     signal activated
 
-    function decrementCurrentIndex() {
+    /*! \internal */
+    function __decrementCurrentIndex() {
         __scroller.blockUpdates = true;
         listView.decrementCurrentIndex();
         __scroller.blockUpdates = false;
     }
 
-    function incrementCurrentIndex() {
+    /*! \internal */
+    function __incrementCurrentIndex() {
         __scroller.blockUpdates = true;
         listView.incrementCurrentIndex();
         __scroller.blockUpdates = false;
@@ -217,8 +273,8 @@ ScrollArea {
             }
 
             // Handle vertical scrolling whem dragging mouse outside boundraries
-            Timer { running: mousearea.autoincrement && __scroller.verticalScrollBar.visible; repeat: true; interval: 20 ; onTriggered: incrementCurrentIndex()}
-            Timer { running: mousearea.autodecrement && __scroller.verticalScrollBar.visible; repeat: true; interval: 20 ; onTriggered: decrementCurrentIndex()}
+            Timer { running: mousearea.autoincrement && __scroller.verticalScrollBar.visible; repeat: true; interval: 20 ; onTriggered: __incrementCurrentIndex()}
+            Timer { running: mousearea.autodecrement && __scroller.verticalScrollBar.visible; repeat: true; interval: 20 ; onTriggered: __decrementCurrentIndex()}
 
             onPositionChanged: {
                 if (mouseY > listView.height && pressed) {
@@ -277,7 +333,7 @@ ScrollArea {
             }
         }
 
-        property list<TableColumn> columnheader
+        property list<TableViewColumn> columnheader
         highlightFollowsCurrentItem: true
         model: root.model
 
@@ -307,7 +363,7 @@ ScrollArea {
                 id: rowstyle
                 // row delegate
                 sourceComponent: root.rowDelegate
-                // Row fills the tree width regardless of item size
+                // Row fills the view width regardless of item size
                 // But scrollbar should not adjust to it
                 width: parent.width + __scroller.horizontalScrollBar.width
                 x: flickableItem.contentX
@@ -353,7 +409,7 @@ ScrollArea {
                         property int rowIndex: rowitem.rowIndex
                         property int columnIndex: index
                         property int itemElideMode: header[index].elideMode
-                        property int itemTextAlignment: header[index].textAlignment
+                        property int itemTextAlignment: header[index].horizontalAlignment
                     }
                 }
                 onWidthChanged: listView.contentWidth = width

src/qtdesktop/TableColumn.qml → src/qtdesktop/TableViewColumn.qml

@@ -41,19 +41,45 @@
 import QtQuick 2.0
 
 /*!
-    \qmltype TableColumn
+    \qmltype TableViewColumn
     \inqmlmodule QtDesktop 1.0
-    \ingroup tables
-    \brief TableColumn is doing bla...bla...
+    \ingroup views
+    \brief Used by the \l TableView to define a column header.
 */
 
 QtObject {
+    /*! The title text of the column. */
     property string title
+
+    /*! The model \c role of the column. */
     property string role
+
+    /*! The current width of the column
+    The default value depends on platform.  */
     property int width: 160
+
+    /*! The horizontal offset of the column. */
     property int x
+
+    /*! The visible status of the column.*/
     property bool visible: true
+
+    /*! The text elide mode of the column.
+    Allowed values are:
+    \list
+        \li Text.AlignLeft - the default
+        \li Text.AligntRight
+        \li Text.AlignHCenter
+        \li Text.AlignJustify
+    \endlist
+    \sa Text::elide */
     property int elideMode: Text.ElideRight
-    property int textAlignment: Text.AlignLeft
+
+    /*! The text elide mode of the column.
+    \sa Text::horizontalAlignment: */
+    property int horizontalAlignment: Text.AlignLeft
+
+    /*! The delegate of the column. This can be used to set the
+    \l TableView::itemDelegate for a specific column. */
     property Component delegate
 }

src/qtdesktop/qmldir

@@ -24,7 +24,7 @@ StatusBar 1.0 StatusBar.qml
 Tab 1.0 Tab.qml
 TabFrame 1.0 TabFrame.qml
 TableView 1.0 TableView.qml
-TableColumn 1.0 TableColumn.qml
+TableViewColumn 1.0 TableViewColumn.qml
 TextArea 1.0 TextArea.qml
 TextField 1.0 TextField.qml
 ToolBar 1.0 ToolBar.qml

src/qtdesktop/qtdesktop.pro

@@ -30,8 +30,8 @@ QML_FILES = \
     StatusBar.qml \
     Tab.qml \
     TabFrame.qml \
-    TableColumn.qml \
     TableView.qml \
+    TableViewColumn.qml \
     TextArea.qml \
     TextField.qml \
     ToolBar.qml \

tests/auto/qtdesktop/data/tableview/table1_qobjectmodel.qml

@@ -45,7 +45,7 @@ import QtDesktopTest 1.0
 TableView {
     model: TestObject {}
     height: 70
-    TableColumn {
+    TableViewColumn {
         role: "value"
         width: 100
     }

tests/auto/qtdesktop/data/tableview/table2_qabstractitemmodel.qml

@@ -45,7 +45,7 @@ import QtDesktopTest 1.0
 TableView {
     model: TestItemModel {}
     height: 70
-    TableColumn {
+    TableViewColumn {
         role: "test"
         width: 100
     }

tests/auto/qtdesktop/data/tableview/table3_qobjectlist.qml

@@ -45,7 +45,7 @@ import QtDesktopTest 1.0
 TableView {
     model: model_qobjectlist
     height: 70
-    TableColumn {
+    TableViewColumn {
         role: "value"
         width: 100
     }

tests/auto/qtdesktop/data/tableview/table4_qstringlist.qml

@@ -45,7 +45,7 @@ import QtDesktopTest 1.0
 TableView {
     model: model_qstringlist
     height: 70
-    TableColumn {
+    TableViewColumn {
         width: 100
     }
 }

tests/auto/qtdesktop/data/tableview/table5_listmodel.qml

@@ -49,7 +49,7 @@ TableView {
         ListElement { value: "C" }
     } // qml
     height: 70
-    TableColumn {
+    TableViewColumn {
         role: "value"
         width: 100
     }

tests/auto/qtdesktop/data/tableview/table6_countmodel.qml

@@ -44,7 +44,7 @@ import QtDesktop 1.0
 TableView {
     model: 3 // qml
     height: 70
-    TableColumn {
+    TableViewColumn {
         width: 100
     }
 }

tests/auto/qtdesktop/data/tableview/table7_arraymodel.qml

@@ -44,7 +44,7 @@ import QtDesktop 1.0
 TableView {
     model: ["A", "B", "C"] // qml
     height: 70
-    TableColumn {
+    TableViewColumn {
         width: 100
     }
 }

tests/auto/qtdesktop/data/tableview/table8_itemmodel.qml

@@ -44,7 +44,7 @@ import QtDesktop 1.0
 TableView {
     model: Item { x: 10 }// qml
     height: 70
-    TableColumn {
+    TableViewColumn {
         role: "x"
         width: 100
     }

tests/auto/qtdesktop/data/tst_tableview.qml

@@ -100,7 +100,7 @@ TestCase {
         table.forceActiveFocus();
 
         // to go to next row (this model has 10 rows)
-        table.incrementCurrentIndex()
+        table.__incrementCurrentIndex()
 
         // read data from the model directly
         var valuefrommodel = table.model.dataAt(table.currentIndex)
@@ -128,7 +128,7 @@ TestCase {
         table.forceActiveFocus();
 
         // to go to next row (this model has 3 rows, read the second row)
-        table.incrementCurrentIndex()
+        table.__incrementCurrentIndex()
 
         verify(table.currentItem !== undefined, "No current item found")
         var label = findAChild(table.currentItem, "label")

tests/manual/scrollbars.qml

@@ -176,7 +176,7 @@ ApplicationWindow {
                 model: 10
                 frame: frameCheck.checked
 
-                TableColumn {title: "first"
+                TableViewColumn {title: "first"
                     width: view.viewport.width
                 }
             }

tests/manual/tableviewmodels/qml/main.qml

@@ -58,7 +58,7 @@ Rectangle {
       model: model_listmodel // qml
       anchors { left: parent.left; right: parent.right }
       height: 70
-      TableColumn {
+      TableViewColumn {
         role: "value"
         width: 100
       }
@@ -67,7 +67,7 @@ Rectangle {
       model: 3 // qml
       anchors { left: parent.left; right: parent.right }
       height: 70
-      TableColumn {
+      TableViewColumn {
         width: 100
       }
     }
@@ -75,7 +75,7 @@ Rectangle {
       model: ["A", "B", "C"] // qml
       anchors { left: parent.left; right: parent.right }
       height: 70
-      TableColumn {
+      TableViewColumn {
         width: 100
       }
     }
@@ -83,7 +83,7 @@ Rectangle {
       model: Item { x: 10 } // qml
       anchors { left: parent.left; right: parent.right }
       height: 70
-      TableColumn {
+      TableViewColumn {
         role: "x"
         width: 100
       }
@@ -92,7 +92,7 @@ Rectangle {
       model: model_qobjectlist // c++
       anchors { left: parent.left; right: parent.right }
       height: 70
-      TableColumn {
+      TableViewColumn {
         role: "value"
         width: 100
       }
@@ -101,7 +101,7 @@ Rectangle {
       model: model_qaim // c++
       anchors { left: parent.left; right: parent.right }
       height: 70
-      TableColumn {
+      TableViewColumn {
         role: "test"
         width: 100
       }
@@ -110,7 +110,7 @@ Rectangle {
       model: model_qstringlist // c++
       anchors { left: parent.left; right: parent.right }
       height: 70
-      TableColumn {
+      TableViewColumn {
         width: 100
       }
     }
@@ -118,7 +118,7 @@ Rectangle {
       model: model_qobject // c++
       anchors { left: parent.left; right: parent.right }
       height: 70
-      TableColumn {
+      TableViewColumn {
         role: "value"
         width: 100
       }