QItemModelBarDataProxy Class

Proxy class for presenting data in item models with Q3DBars. More...

Header: #include <QItemModelBarDataProxy>
qmake: QT += datavisualization
Since: QtDataVisualization 1.0
Instantiated By: ItemModelBarDataProxy
Inherits: QBarDataProxy

This class was introduced in QtDataVisualization 1.0.

Public Types

enum MultiMatchBehavior { MMBFirst, MMBLast, MMBAverage, MMBCumulative }

Properties

Public Functions

QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &valueRole, QObject *parent = nullptr)
QItemModelBarDataProxy(QAbstractItemModel *itemModel, QObject *parent = nullptr)
QItemModelBarDataProxy(QObject *parent = nullptr)
virtual ~QItemModelBarDataProxy()
bool autoColumnCategories() const
bool autoRowCategories() const
QStringList columnCategories() const
int columnCategoryIndex(const QString &category)
QString columnRole() const
QRegExp columnRolePattern() const
QString columnRoleReplace() const
QAbstractItemModel *itemModel() const
QItemModelBarDataProxy::MultiMatchBehavior multiMatchBehavior() const
void remap(const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, const QStringList &rowCategories, const QStringList &columnCategories)
QString rotationRole() const
QRegExp rotationRolePattern() const
QString rotationRoleReplace() const
QStringList rowCategories() const
int rowCategoryIndex(const QString &category)
QString rowRole() const
QRegExp rowRolePattern() const
QString rowRoleReplace() const
void setAutoColumnCategories(bool enable)
void setAutoRowCategories(bool enable)
void setColumnCategories(const QStringList &categories)
void setColumnRole(const QString &role)
void setColumnRolePattern(const QRegExp &pattern)
void setColumnRoleReplace(const QString &replace)
void setItemModel(QAbstractItemModel *itemModel)
void setMultiMatchBehavior(QItemModelBarDataProxy::MultiMatchBehavior behavior)
void setRotationRole(const QString &role)
void setRotationRolePattern(const QRegExp &pattern)
void setRotationRoleReplace(const QString &replace)
void setRowCategories(const QStringList &categories)
void setRowRole(const QString &role)
void setRowRolePattern(const QRegExp &pattern)
void setRowRoleReplace(const QString &replace)
void setUseModelCategories(bool enable)
void setValueRole(const QString &role)
void setValueRolePattern(const QRegExp &pattern)
void setValueRoleReplace(const QString &replace)
bool useModelCategories() const
QString valueRole() const
QRegExp valueRolePattern() const
QString valueRoleReplace() const

Signals

void autoColumnCategoriesChanged(bool enable)
void autoRowCategoriesChanged(bool enable)
void columnCategoriesChanged()
void columnRoleChanged(const QString &role)
void columnRolePatternChanged(const QRegExp &pattern)
void columnRoleReplaceChanged(const QString &replace)
void itemModelChanged(const QAbstractItemModel *itemModel)
void multiMatchBehaviorChanged(QItemModelBarDataProxy::MultiMatchBehavior behavior)
void rotationRoleChanged(const QString &role)
void rotationRolePatternChanged(const QRegExp &pattern)
void rotationRoleReplaceChanged(const QString &replace)
void rowCategoriesChanged()
void rowRoleChanged(const QString &role)
void rowRolePatternChanged(const QRegExp &pattern)
void rowRoleReplaceChanged(const QString &replace)
void useModelCategoriesChanged(bool enable)
void valueRoleChanged(const QString &role)
void valueRolePatternChanged(const QRegExp &pattern)
void valueRoleReplaceChanged(const QString &replace)

Detailed Description

QItemModelBarDataProxy allows you to use QAbstractItemModel derived models as a data source for Q3DBars. It uses the defined mappings to map data from the model to rows, columns, and values of Q3DBars graph.

The data is resolved asynchronously whenever mappings or the model changes. QBarDataProxy::arrayReset() is emitted when the data has been resolved. However, when useModelCategories property is set to true, single item changes are resolved synchronously, unless the same frame also contains a change that causes the whole model to be resolved.

Mappings can be used in the following ways:

  • If useModelCategories property is set to true, this proxy will map rows and columns of QAbstractItemModel directly to rows and columns of Q3DBars, and uses the value returned for Qt::DisplayRole as bar value by default. The value role to be used can be redefined if Qt::DisplayRole is not suitable.
  • For models that do not have data already neatly sorted into rows and columns, such as QAbstractListModel based models, you can define a role from the model to map for each of row, column and value.
  • If you do not want to include all data contained in the model, or the autogenerated rows and columns are not ordered as you wish, you can specify which rows and columns should be included and in which order by defining an explicit list of categories for either or both of rows and columns.

For example, assume that you have a custom QAbstractItemModel for storing various monthly values related to a business. Each item in the model has the roles "year", "month", "income", and "expenses". You could do the following to display the data in a bar graph:

// By defining row and column categories, you tell the mapping which row and column each item
// belongs to. The categories must match the data stored in the model in the roles you define
// for row and column mapping. In this example we expect "year" role to return four digit year
// and "month" to return three letter designation for the month.
//
// An example of an item in model would be:
// Requested role -> Returned data
// "year" -> "2006" // Matches the first row category, so this item is added to the first row.
// "month" -> "jan" // Matches the first column category, so this item is added as first item in the row.
// "income" -> "12.1"
// "expenses" -> "9.2"
QStringList years;
QStringList months;
years << "2006" << "2007" << "2008" << "2009" << "2010" << "2011" << "2012";
months << "jan" << "feb" << "mar" << "apr" << "may" << "jun" << "jul" << "aug" << "sep" << "oct" << "nov" << "dec";

QItemModelBarDataProxy *proxy = new QItemModelBarDataProxy(customModel,
                                                           QStringLiteral("year"), // Row role
                                                           QStringLiteral("month"), // Column role
                                                           QStringLiteral("income"), // Value role
                                                           years, // Row categories
                                                           months); // Column categories

//...

// To display different data later, you can simply change the mapping.
proxy->setValueRole(QStringLiteral("expenses"));

If the fields of the model do not contain the data in the exact format you need, you can specify a search pattern regular expression and a replace rule for each role to get the value in a format you need. For more information how the replace using regular expressions works, see QString::replace(const QRegExp &rx, const QString &after) function documentation. Note that using regular expressions has an impact on the performance, so it's more efficient to utilize item models where doing search and replace is not necessary to get the desired values.

For example about using the search patterns in conjunction with the roles, see Qt Quick 2 Bars Example.

See also Qt Data Visualization Data Handling.

Member Type Documentation

enum QItemModelBarDataProxy::MultiMatchBehavior

Behavior types for QItemModelBarDataProxy::multiMatchBehavior property.

ConstantValueDescription
QItemModelBarDataProxy::MMBFirst0The value is taken from the first item in the item model that matches each row/column combination.
QItemModelBarDataProxy::MMBLast1The value is taken from the last item in the item model that matches each row/column combination.
QItemModelBarDataProxy::MMBAverage2The values from all items matching each row/column combination are averaged together and the average is used as the bar value.
QItemModelBarDataProxy::MMBCumulative3The values from all items matching each row/column combination are added together and the total is used as the bar value.

Property Documentation

autoColumnCategories : bool

This property holds whether column categories are generated automatically.

When set to true, the mapping ignores any explicitly set column categories and overwrites them with automatically generated ones whenever the data from model is resolved. Defaults to true.

Access functions:

bool autoColumnCategories() const
void setAutoColumnCategories(bool enable)

Notifier signal:

void autoColumnCategoriesChanged(bool enable)

autoRowCategories : bool

This property holds whether row categories are generated automatically.

When set to true, the mapping ignores any explicitly set row categories and overwrites them with automatically generated ones whenever the data from model is resolved. Defaults to true.

Access functions:

bool autoRowCategories() const
void setAutoRowCategories(bool enable)

Notifier signal:

void autoRowCategoriesChanged(bool enable)

columnCategories : QStringList

This property holds the column categories for the mapping.

Access functions:

QStringList columnCategories() const
void setColumnCategories(const QStringList &categories)

Notifier signal:

void columnCategoriesChanged()

columnRole : QString

This property holds the column role for the mapping.

Access functions:

QString columnRole() const
void setColumnRole(const QString &role)

Notifier signal:

void columnRoleChanged(const QString &role)

columnRolePattern : QRegExp

This property holds whether a search and replace is done on the value mapped by column role before it is used as a column category.

This property specifies the regular expression to find the portion of the mapped value to replace and columnRoleReplace property contains the replacement string. This is useful for example in parsing row and column categories from a single timestamp field in the item model.

Access functions:

QRegExp columnRolePattern() const
void setColumnRolePattern(const QRegExp &pattern)

Notifier signal:

void columnRolePatternChanged(const QRegExp &pattern)

See also columnRole and columnRoleReplace.

columnRoleReplace : QString

This property holds the replace content to be used in conjunction with columnRolePattern.

Defaults to empty string. For more information on how the search and replace using regular expressions works, see QString::replace(const QRegExp &rx, const QString &after) function documentation.

Access functions:

QString columnRoleReplace() const
void setColumnRoleReplace(const QString &replace)

Notifier signal:

void columnRoleReplaceChanged(const QString &replace)

See also columnRole and columnRolePattern.

itemModel : QAbstractItemModel*

This property holds the item model.

Access functions:

QAbstractItemModel *itemModel() const
void setItemModel(QAbstractItemModel *itemModel)

Notifier signal:

void itemModelChanged(const QAbstractItemModel *itemModel)

multiMatchBehavior : MultiMatchBehavior

How multiple matches for each row/column combination are handled.

Defaults to QItemModelBarDataProxy::MMBLast. The chosen behavior affects both bar value and rotation.

For example, you might have an item model with timestamped data taken at irregular intervals and you want to visualize total value of data items on each day with a bar graph. This can be done by specifying row and column categories so that each bar represents a day, and setting multiMatchBehavior to QItemModelBarDataProxy::MMBCumulative.

Access functions:

QItemModelBarDataProxy::MultiMatchBehavior multiMatchBehavior() const
void setMultiMatchBehavior(QItemModelBarDataProxy::MultiMatchBehavior behavior)

Notifier signal:

void multiMatchBehaviorChanged(QItemModelBarDataProxy::MultiMatchBehavior behavior)

rotationRole : QString

This property holds the rotation role for the mapping.

Access functions:

QString rotationRole() const
void setRotationRole(const QString &role)

Notifier signal:

void rotationRoleChanged(const QString &role)

rotationRolePattern : QRegExp

This property holds whether a search and replace is done on the value mapped by rotation role before it is used as a bar rotation angle.

This property specifies the regular expression to find the portion of the mapped value to replace and rotationRoleReplace property contains the replacement string.

Access functions:

QRegExp rotationRolePattern() const
void setRotationRolePattern(const QRegExp &pattern)

Notifier signal:

void rotationRolePatternChanged(const QRegExp &pattern)

See also rotationRole and rotationRoleReplace.

rotationRoleReplace : QString

This property holds the replace content to be used in conjunction with rotationRolePattern.

Defaults to empty string. For more information on how the search and replace using regular expressions works, see QString::replace(const QRegExp &rx, const QString &after) function documentation.

Access functions:

QString rotationRoleReplace() const
void setRotationRoleReplace(const QString &replace)

Notifier signal:

void rotationRoleReplaceChanged(const QString &replace)

See also rotationRole and rotationRolePattern.

rowCategories : QStringList

This property holds the row categories for the mapping.

Access functions:

QStringList rowCategories() const
void setRowCategories(const QStringList &categories)

Notifier signal:

void rowCategoriesChanged()

rowRole : QString

This property holds the row role for the mapping.

Access functions:

QString rowRole() const
void setRowRole(const QString &role)

Notifier signal:

void rowRoleChanged(const QString &role)

rowRolePattern : QRegExp

This property holds whether a search and replace is performed on the value mapped by row role before it is used as a row category.

This property specifies the regular expression to find the portion of the mapped value to replace and rowRoleReplace property contains the replacement string. This is useful for example in parsing row and column categories from a single timestamp field in the item model.

Access functions:

QRegExp rowRolePattern() const
void setRowRolePattern(const QRegExp &pattern)

Notifier signal:

void rowRolePatternChanged(const QRegExp &pattern)

See also rowRole and rowRoleReplace.

rowRoleReplace : QString

This property holds the replace content to be used in conjunction with rowRolePattern.

Defaults to empty string. For more information on how the search and replace using regular expressions works, see QString::replace(const QRegExp &rx, const QString &after) function documentation.

Access functions:

QString rowRoleReplace() const
void setRowRoleReplace(const QString &replace)

Notifier signal:

void rowRoleReplaceChanged(const QString &replace)

See also rowRole and rowRolePattern.

useModelCategories : bool

This property holds whether row and column roles and categories are used for mapping.

When set to true, the mapping ignores row and column roles and categories, and uses the rows and columns from the model instead. Defaults to false.

Access functions:

bool useModelCategories() const
void setUseModelCategories(bool enable)

Notifier signal:

void useModelCategoriesChanged(bool enable)

valueRole : QString

This property holds the value role for the mapping.

Access functions:

QString valueRole() const
void setValueRole(const QString &role)

Notifier signal:

void valueRoleChanged(const QString &role)

valueRolePattern : QRegExp

This property holds whether a search and replace is done on the value mapped by value role before it is used as a bar value.

This property specifies the regular expression to find the portion of the mapped value to replace and valueRoleReplace property contains the replacement string.

Access functions:

QRegExp valueRolePattern() const
void setValueRolePattern(const QRegExp &pattern)

Notifier signal:

void valueRolePatternChanged(const QRegExp &pattern)

See also valueRole and valueRoleReplace.

valueRoleReplace : QString

This property holds the replace content to be used in conjunction with valueRolePattern.

Defaults to empty string. For more information on how the search and replace using regular expressions works, see QString::replace(const QRegExp &rx, const QString &after) function documentation.

Access functions:

QString valueRoleReplace() const
void setValueRoleReplace(const QString &replace)

Notifier signal:

void valueRoleReplaceChanged(const QString &replace)

See also valueRole and valueRolePattern.

Member Function Documentation

QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr)

Constructs QItemModelBarDataProxy with itemModel and optional parent. Proxy doesn't take ownership of the itemModel, as typically item models are owned by other controls. The role mappings are set with rowRole, columnRole, valueRole, and rotationRole. Row and column categories are set with rowCategories and columnCategories. This constructor also sets autoRowCategories and autoColumnCategories to false.

QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = nullptr)

Constructs QItemModelBarDataProxy with itemModel and optional parent. Proxy doesn't take ownership of the itemModel, as typically item models are owned by other controls. The role mappings are set with rowRole, columnRole, and valueRole. Row and column categories are set with rowCategories and columnCategories. This constructor also sets autoRowCategories and autoColumnCategories to false.

QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, QObject *parent = nullptr)

Constructs QItemModelBarDataProxy with itemModel and optional parent. Proxy doesn't take ownership of the itemModel, as typically item models are owned by other controls. The role mappings are set with rowRole, columnRole, valueRole, and rotationRole.

QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &valueRole, QObject *parent = nullptr)

Constructs QItemModelBarDataProxy with itemModel and optional parent. Proxy doesn't take ownership of the itemModel, as typically item models are owned by other controls. The role mappings are set with rowRole, columnRole, and valueRole.

QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, const QString &valueRole, QObject *parent = nullptr)

Constructs QItemModelBarDataProxy with itemModel and optional parent. Proxy doesn't take ownership of the itemModel, as typically item models are owned by other controls. The value role is set to valueRole. This constructor is meant to be used with models that have data properly sorted in rows and columns already, so it also sets useModelCategories property to true.

QItemModelBarDataProxy::QItemModelBarDataProxy(QAbstractItemModel *itemModel, QObject *parent = nullptr)

Constructs QItemModelBarDataProxy with itemModel and optional parent. Proxy doesn't take ownership of the itemModel, as typically item models are owned by other controls.

QItemModelBarDataProxy::QItemModelBarDataProxy(QObject *parent = nullptr)

Constructs QItemModelBarDataProxy with optional parent.

[virtual] QItemModelBarDataProxy::~QItemModelBarDataProxy()

Destroys QItemModelBarDataProxy.

int QItemModelBarDataProxy::columnCategoryIndex(const QString &category)

Returns the index of the specified category in column categories list. If the category is not found, -1 is returned.

Note: If the automatic column categories generation is in use, this method will not return a valid index before the data in the model is resolved for the first time.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

void QItemModelBarDataProxy::remap(const QString &rowRole, const QString &columnRole, const QString &valueRole, const QString &rotationRole, const QStringList &rowCategories, const QStringList &columnCategories)

Changes rowRole, columnRole, valueRole, rotationRole, rowCategories and columnCategories to the mapping.

int QItemModelBarDataProxy::rowCategoryIndex(const QString &category)

Returns the index of the specified category in row categories list. If the row categories list is empty, -1 is returned.

Note: If the automatic row categories generation is in use, this method will not return a valid index before the data in the model is resolved for the first time.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

void QItemModelBarDataProxy::setItemModel(QAbstractItemModel *itemModel)

Sets the item model to itemModel. Does not take ownership of the model, but does connect to it to listen for changes.

Note: Setter function for property itemModel.

See also itemModel().

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.