Revision control
Copy as Markdown
// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example 3d/bars
\meta tags {Graphs, Bars3D, Multiple Series}
\examplecategory {Data Visualization}
\title Simple Bar Graph
\ingroup qtgraphs_qmlexamples_3D
\brief Using Bars3D in a QML application.
\e {Simple Bar Graph} shows how to make a simple 3D bar graph using Bars3D and QML.
\image bars-example.png
{3D bar charts showing expense and income data for a range of years}
The following sections describe how to switch series and display more than one series
at a time. For more information about basic QML application functionality, see
\l{Simple Scatter Graph}.
\include examples-run.qdocinc
\section1 Data
The example data set is the 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 3d/bars/qml/bars/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>}. Usually, you would map years and months to rows
and columns of a bar graph, but you can only show either income or expenses as the value.
Now, add the data to the Bars3D graph. Create two Bar3DSeries inside it, starting with a series
for the income:
\snippet 3d/bars/qml/bars/main.qml 3
\dots
The data is attached to the \c itemModel property of the ItemModelBarDataProxy inside the
series. For the \c{valueRole}, specify the \c income field as it contains the desired value.
Getting the years and months is a bit more complicated since they are both found
in the same field. To extract these values, specify the \c timestamp field for both
\c rowRole and \c columnRole. 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, 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 about the replace functionality with regular expressions, see
the 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, add their values together.
This property has no effect when showing values for each month, as there are no
duplicate months in our item model. However, it becomes relevant later when you want to show
the yearly totals.
Then, add another series for the expenses:
\snippet 3d/bars/qml/bars/main.qml 4
\dots
The model contains expenses as negative values, but they could be shown as positive bars for
easy comparison to income bars. Use the \c valueRolePattern to remove the minus sign, and no
replacement string needs to be specified as the default replacement is an empty string.
Use the \c visible property of the series to hide the second series for now.
\section1 Custom Axis Labels
\c Axes.qml redefines the category labels for the column axis because the data contains numbers
for months, which would clutter the labels:
\snippet 3d/bars/qml/bars/Axes.qml 0
To make axis labels more readable at low camera angles, set automatic axis label rotation.
\section1 Switching Series
In \c main.qml, set up the graph and various UI elements. There are three interesting
code blocks to highlight here. The first one shows how to change the visualized data between
income, expenses, and both, by simply changing the visibility of the two series:
\snippet 3d/bars/qml/bars/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 the visualized data is changed by adjusting the proxy
properties:
\snippet 3d/bars/qml/bars/main.qml 1
To show the yearly totals, combine the twelve months of each year into a single bar.
This is achieved by specifying a \c columnRolePattern that matches all model items. In this way,
the series will only have a single column. The cumulative \c multiMatchBehavior
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, set \c autoRowCategories to false on the ItemModelBarDataProxy
item and define the row categories explicitly. This way, only the items in the 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 3d/bars/qml/bars/main.qml 2
*/