| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://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 https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \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}. |
| |
| \include examples-run.qdocinc |
| |
| \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 three roles: timestamp, income, and expenses. The timestamp value is in |
| format: \c{<four digit year>-<two digit month>}. 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. For \c valueRole we simply specify the \c income field, as it contains the value we |
| want, but getting the years and months is a bit more complicated, since they are both found |
| in the same field. To extract those values, we specify the \c timestamp field for both |
| \c rowRole and \c columnRole, and additionally specify a search pattern and a replace rule |
| for those roles to extract the correct portion of the field contents for each role. |
| The search pattern is a normal JavaScript regular expression and the replace rule specifies |
| what the field content that matches the regular expression is replaced with. |
| In this case we want to replace the entire field content with just the year or the month, |
| which is the first captured substring for both rows and columns. |
| For more information how the replace using regular expressions works, see |
| QString::replace(const QRegExp &rx, const QString &after) function documentation. |
| |
| The \c multiMatchBehavior property specifies what to do in case multiple item model items match |
| the same row/column combination. In this case we want to add their values together. |
| This property has no effect when we are showing values for each month, as there are no |
| duplicate months in our item model, but it becomes relevant later when we want to show |
| the yearly totals. |
| |
| Then we add another series for the expenses: |
| |
| \snippet qmlbars/qml/qmlbars/main.qml 4 |
| \dots |
| |
| The model contains expenses as negative values, but we want to show them as positive bars, so |
| that we can easily compare them to income bars. We use \c valueRolePattern to remove the minus |
| sign to achieve this. No replacement string needs to be specified as the default replacement |
| is an empty string. |
| |
| 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 numbers for months, which we don't want |
| to use for our column labels: |
| |
| \snippet qmlbars/qml/qmlbars/Axes.qml 0 |
| |
| We also set automatic axis label rotation to make axis labels more readable at low camera |
| angles. |
| |
| \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 label format and item selection label formats are tweaked to get the negative sign |
| showing properly for expenses, which were actually resolved as positive values. |
| |
| The second interesting block is where we change the visualized data by adjusting the proxy |
| propertes: |
| |
| \snippet qmlbars/qml/qmlbars/main.qml 1 |
| |
| To show yearly totals, we need to combine the twelve months of each year into a single bar. |
| We achieve this by specifying a \c columnRolePattern that matches all model items. That way |
| the data proxy will only have a single column. The cumulative \c multiMatchBehavior we |
| specified earlier for the proxy becomes relevant now, causing the values of all twelve months |
| of each year to be added up into a single bar. |
| |
| To show just a subset of years, we set \c autoRowCategories to false on the |
| ItemModelBarDataProxy item and define the row categories explicitly. This way, only the items |
| in specified row categories 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 |
| */ |