2 files changed, 93 insertions, 0 deletions
diff --git a/examples/datavisualization/qmlbars/doc/images/qmlbars-example.png b/examples/datavisualization/qmlbars/doc/images/qmlbars-example.png
new file mode 100644
index 00000000..64ad6b0e
--- /dev/null
+++ b/examples/datavisualization/qmlbars/doc/images/qmlbars-example.png
diff --git a/examples/datavisualization/qmlbars/doc/src/qmlbars.qdoc b/examples/datavisualization/qmlbars/doc/src/qmlbars.qdoc
new file mode 100644
index 00000000..cc344c9c
--- /dev/null
+++ b/examples/datavisualization/qmlbars/doc/src/qmlbars.qdoc
@@ -0,0 +1,93 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+/*!
+    \example qmlbars
+    \title Qt Quick 2 Bars Example
+    \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 Bars3D and Qt
+    Quick 2.
+
+    \image qmlbars-example.png
+
+    The interesting thing about this example is switching series and displaying more than one series
+    at once. We'll concentrate on those 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
+
+    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.
+
+    Now we need to add the data to the Bars3D graph. We will create two Bar3DSeries inside it,
+    starting with a series for the income:
+
+    \snippet ../examples/qmlbars/qml/qmlbars/main.qml 3
+    \dots
+
+    The data is attached to the \c itemModel property of the ItemModelBarDataProxy inside the
+    series.
+
+    Then we add another series for the expenses:
+
+    \snippet ../examples/qmlbars/qml/qmlbars/main.qml 4
+    \dots
+
+    We use the \c visible property of the series to hide the second series for now.
+
+    \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 Switching series
+
+    In the \c main.qml, we set up the graph and various UI elements. There are three interesting
+    code blocks we want to highlight here. The first one shows how to change the
+    visualized data between income, expenses, and both, by simply changing visibility of the two
+    series:
+
+    \snippet ../examples/qmlbars/qml/qmlbars/main.qml 0
+
+    The axis change is done because income and expenses have a 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 ItemModelBarDataProxy 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 ItemModelBarDataProxy methods \c rowCategoryIndex() and \c columnCategoryIndex():
+
+    \snippet ../examples/qmlbars/qml/qmlbars/main.qml 2
+*/