Document qmlbars example

Task-number: QTRD-2395

Change-Id: If5b3d2e1deafb03c7255543596f316e0decbe027
Reviewed-by: Tomi Korpipää <tomi.korpipaa@digia.com>

4 files changed, 68 insertions, 4 deletions

diff --git a/examples/qmlbars/doc/src/qmlbars.qdoc b/examples/qmlbars/doc/src/qmlbars.qdoc
index c9fb564a..185956ea 100644
--- a/examples/qmlbars/doc/src/qmlbars.qdoc
+++ b/examples/qmlbars/doc/src/qmlbars.qdoc
@@ -22,10 +22,62 @@
     \ingroup qtdatavisualization_examples
     \brief Using Bars3D in a QML application.
 
-    The Qt Quick 2 bars example shows how to make a simple 3D bar graph using Q3DBars and Qt
+    The Qt Quick 2 bars example shows how to make a simple 3D bar graph using Bars3D and Qt
     Quick 2.
 
     \image qmlbars-example.png
 
-    TODO
+    The interesting thing about this example is remapping the data, so we concentrate on that
+    and skip explaining the basic Bars3D functionality - for more detailed QML example documentation,
+    see \l{Qt Quick 2 Scatter Example}.
+
+    \section1 Data
+
+    The example data is monthly income and expenses of a fictional company over several years.
+    The data is defined in a list model in \c data.qml like this:
+
+    \snippet ../examples/qmlbars/qml/qmlbars/data.qml 0
+    \dots 4
+
+    Each data item has four roles: year, month, income, and expenses. Years and months are natural to
+    map to rows and columns of a bar chart, but we can only show either income or expenses as the value.
+    We choose to default to showing expenses when we initialize the mapping item:
+
+    \snippet ../examples/qmlbars/qml/qmlbars/data.qml 1
+
+    Final piece we need for handling data is the proxy to bring the model and mapping together:
+
+    \snippet ../examples/qmlbars/qml/qmlbars/data.qml 2
+
+    \section1 Custom axis labels
+
+    One interesting tidbit about axes is that we redefine the category labels for column axis in
+    \c axes.qml. This is done because the data contains abbreviated month names, which we don't want
+    to use for our column labels:
+
+    \snippet ../examples/qmlbars/qml/qmlbars/axes.qml 0
+
+    \section1 Using mapping
+
+    In the \c main.qml, we set up the graph and various UI elements. There are three interesting
+    mapping related code blocks we want to highlight here. The first one shows how to change the
+    visualized data from expenses to income, and vice versa, by simply changing the value role on the
+    BarDataMapping item:
+
+    \snippet ../examples/qmlbars/qml/qmlbars/main.qml 0
+
+    The axis change is done because income and expenses have different label format. The same could have
+    been achieved using a single axis and just changing the label format.
+
+    The second interesting block is where we filter some of the rows away from the visualized data:
+
+    \snippet ../examples/qmlbars/qml/qmlbars/main.qml 1
+
+    The filtering is done by setting \c autoRowCategories to false on the BarDataMapping item and defining
+    the row categories explicitly. This way, only the items in specified rows are visualized.
+
+    The third interesting block shows how to get the row and column index of an item if you know the
+    row and column values by using BarDataMapping methods \c rowCategoryIndex() and \c columnCategoryIndex():
+
+    \snippet ../examples/qmlbars/qml/qmlbars/main.qml 2
 */
diff --git a/examples/qmlbars/qml/qmlbars/axes.qml b/examples/qmlbars/qml/qmlbars/axes.qml
index b0ba3eb2..66be99a0 100644
--- a/examples/qmlbars/qml/qmlbars/axes.qml
+++ b/examples/qmlbars/qml/qmlbars/axes.qml
@@ -28,11 +28,13 @@ Item {
     // suffices for rows.
 
     // Custom labels for columns, since the data contains abbreviated month names.
+    //! [0]
     CategoryAxis3D {
         id: columnAxis
         categoryLabels: ["January", "February", "March", "April", "May", "June",
             "July", "August", "September", "October", "November", "December"]
     }
+    //! [0]
     ValueAxis3D {
         id: incomeAxis
         min: 0
diff --git a/examples/qmlbars/qml/qmlbars/data.qml b/examples/qmlbars/qml/qmlbars/data.qml
index fff568cc..ecb05030 100644
--- a/examples/qmlbars/qml/qmlbars/data.qml
+++ b/examples/qmlbars/qml/qmlbars/data.qml
@@ -24,24 +24,28 @@ Item {
     property alias model: dataModel
     property alias proxy: modelProxy
 
+    //! [1]
     BarDataMapping {
         id: valueMapping
         rowRole: "year"
         columnRole: "month"
         valueRole: "expenses"
     }
-
+    //! [1]
+    //! [2]
     ItemModelBarDataProxy {
         id: modelProxy
         activeMapping: valueMapping
         itemModel: dataModel
     }
-
+    //! [2]
+    //! [0]
     ListModel {
         id: dataModel
         ListElement{ year: "2006"; month: "Jan"; expenses: "4";  income: "5" }
         ListElement{ year: "2006"; month: "Feb"; expenses: "5";  income: "6" }
         ListElement{ year: "2006"; month: "Mar"; expenses: "7";  income: "4" }
+        //! [0]
         ListElement{ year: "2006"; month: "Apr"; expenses: "3";  income: "2" }
         ListElement{ year: "2006"; month: "May"; expenses: "4";  income: "1" }
         ListElement{ year: "2006"; month: "Jun"; expenses: "2";  income: "2" }
diff --git a/examples/qmlbars/qml/qmlbars/main.qml b/examples/qmlbars/qml/qmlbars/main.qml
index d349ef97..9f3a3484 100644
--- a/examples/qmlbars/qml/qmlbars/main.qml
+++ b/examples/qmlbars/qml/qmlbars/main.qml
@@ -86,6 +86,7 @@ Item {
         width: tableView.width
         height: 60
         text: "Show Income"
+        //! [0]
         onClicked: {
             if (graphData.mapping.valueRole === "expenses") {
                 graphData.mapping.valueRole = "income"
@@ -97,6 +98,7 @@ Item {
                 testGraph.valueAxis = graphAxes.expenses
             }
         }
+        //! [0]
     }
 
     Button {
@@ -122,6 +124,7 @@ Item {
         width: tableView.width
         height: 60
         text: "Show 2010 - 2012"
+        //! [1]
         onClicked: {
             if (testGraph.rowAxis.max !== 6) {
                 text = "Show 2010 - 2012"
@@ -134,6 +137,7 @@ Item {
                 graphData.mapping.rowCategories = ["2010", "2011", "2012"]
             }
         }
+        //! [1]
     }
 
     TableView {
@@ -148,10 +152,12 @@ Item {
         TableViewColumn{ role: "income" ; title: "Income" ; width: 60 }
         model: graphData.model
 
+        //! [2]
         onCurrentRowChanged: {
             var rowIndex = graphData.proxy.activeMapping.rowCategoryIndex(graphData.model.get(currentRow).year)
             var colIndex = graphData.proxy.activeMapping.columnCategoryIndex(graphData.model.get(currentRow).month)
             testGraph.selectedBarPos = Qt.point(rowIndex, colIndex)
         }
+        //! [2]
     }
 }