/****************************************************************************
**
** 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 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 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 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 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 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 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 qmlbars/qml/qmlbars/main.qml 2
*/