QItemModelBarDataProxy Class

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

• List of all members, including inherited members

Public Types

Properties

Public Functions

Signals

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 QRegularExpression &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.

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.

[invokable] 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: 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.

[invokable] 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: 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().