1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
/****************************************************************************
**
** 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
*/
|
