Qt 5.7 | Qt Data Visualization | C++ Classes | QItemModelSurfaceDataProxy

Qt 5.7.1 Reference Documentation

# QItemModelSurfaceDataProxy Class

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

Header: | #include <QItemModelSurfaceDataProxy>
Since: | QtDataVisualization 1.0
Instantiated By: | ItemModelSurfaceDataProxy
Inherits: | QSurfaceDataProxy

- List of all members, including inherited members

## Public Types

enum | MultiMatchBehavior { MMBFirst, MMBLast, MMBAverage, MMBCumulativeY }

## Properties

autoColumnCategories : bool autoRowCategories : bool columnCategories : QStringList columnRole : QString columnRolePattern : QRegExp columnRoleReplace : QString itemModel : QAbstractItemModel * multiMatchBehavior : MultiMatchBehavior rowCategories : QStringList rowRole : QString rowRolePattern : QRegExp | rowRoleReplace : QString useModelCategories : bool xPosRole : QString xPosRolePattern : QRegExp xPosRoleReplace : QString yPosRole : QString yPosRolePattern : QRegExp yPosRoleReplace : QString zPosRole : QString zPosRolePattern : QRegExp zPosRoleReplace : QString

- 3 properties inherited from QSurfaceDataProxy
- 1 property inherited from QAbstractDataProxy

## Public Functions

| QItemModelSurfaceDataProxy(QObject *parent = Q_NULLPTR)
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, QObject *parent = Q_NULLPTR)
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &yPosRole, QObject *parent = Q_NULLPTR)
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, QObject *parent = Q_NULLPTR)
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, QObject *parent = Q_NULLPTR)
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = Q_NULLPTR)
| QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = Q_NULLPTR)
virtual | ~QItemModelSurfaceDataProxy()
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
MultiMatchBehavior | multiMatchBehavior() const
void | remap(const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, const QStringList &rowCategories, const QStringList &columnCategories)
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(MultiMatchBehavior behavior)
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 | setXPosRole(const QString &role)
void | setXPosRolePattern(const QRegExp &pattern)
void | setXPosRoleReplace(const QString &replace)
void | setYPosRole(const QString &role)
void | setYPosRolePattern(const QRegExp &pattern)
void | setYPosRoleReplace(const QString &replace)
void | setZPosRole(const QString &role)
void | setZPosRolePattern(const QRegExp &pattern)
void | setZPosRoleReplace(const QString &replace)
bool | useModelCategories() const
QString | xPosRole() const
QRegExp | xPosRolePattern() const
QString | xPosRoleReplace() const
QString | yPosRole() const
QRegExp | yPosRolePattern() const
QString | yPosRoleReplace() const
QString | zPosRole() const
QRegExp | zPosRolePattern() const
QString | zPosRoleReplace() const

- 16 public functions inherited from QSurfaceDataProxy
- 1 public function inherited from QAbstractDataProxy

## 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(MultiMatchBehavior behavior)
void | rowCategoriesChanged()
void | rowRoleChanged(const QString &role)
void | rowRolePatternChanged(const QRegExp &pattern)
void | rowRoleReplaceChanged(const QString &replace)
void | useModelCategoriesChanged(bool enable)
void | xPosRoleChanged(const QString &role)
void | xPosRolePatternChanged(const QRegExp &pattern)
void | xPosRoleReplaceChanged(const QString &replace)
void | yPosRoleChanged(const QString &role)
void | yPosRolePatternChanged(const QRegExp &pattern)
void | yPosRoleReplaceChanged(const QString &replace)
void | zPosRoleChanged(const QString &role)
void | zPosRolePatternChanged(const QRegExp &pattern)
void | zPosRoleReplaceChanged(const QString &replace)

- 9 signals inherited from QSurfaceDataProxy

## Detailed Description

Proxy class for presenting data in item models with Q3DSurface.

QItemModelSurfaceDataProxy allows you to use QAbstractItemModel derived models as a data source for Q3DSurface. It uses the defined mappings to map data from the model to rows, columns, and surface points of Q3DSurface graph.

Data is resolved asynchronously whenever the mapping or the model changes. QSurfaceDataProxy::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.

There are three ways to use mappings:

1) If useModelCategories property is set to true, this proxy will map rows and columns of QAbstractItemModel to rows and columns of Q3DSurface, and uses the value returned for Qt::DisplayRole as Y-position by default. Row and column headers are used for Z-position and X-position by default, if they can be converted to floats. Otherwise row and column indices are used. The Y-position role to be used can be redefined if Qt::DisplayRole is not suitable. The Z-position and X-position roles to be used can be redefined if the headers or indices are not suitable.

2) 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 Y-position.

3) 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 storing surface topography data. Each item in the model has the roles "longitude", "latitude", and "height". The item model already contains the data properly sorted so that longitudes and latitudes are first encountered in correct order, which enables us to utilize the row and column category autogeneration. You could do the following to display the data in a surface graph:

      QItemModelSurfaceDataProxy *proxy = new QItemModelSurfaceDataProxy(customModel,
                                                                         QStringLiteral("longitude"), // Row role
                                                                         QStringLiteral("latitude"), // Column role
                                                                         QStringLiteral("height")); // Y-position role

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 ItemModelBarDataProxy usage in Qt Quick 2 Bars Example.

See also Qt Data Visualization Data Handling.

## Member Type Documentation

### enum QItemModelSurfaceDataProxy::MultiMatchBehavior

Behavior types for QItemModelSurfaceDataProxy::multiMatchBehavior property.

Constant | Value | Description
--- | --- | ---
`QItemModelSurfaceDataProxy::MMBFirst` | `0` | The position values are taken from the first item in the item model that matches each row/column combination.
`QItemModelSurfaceDataProxy::MMBLast` | `1` | The position values are taken from the last item in the item model that matches each row/column combination.
`QItemModelSurfaceDataProxy::MMBAverage` | `2` | The position values from all items matching each row/column combination are averaged together and the averages are used as the surface point position.
`QItemModelSurfaceDataProxy::MMBCumulativeY` | `3` | For X and Z values this acts just like `MMBAverage`, but Y values are added together instead of averaged and the total is used as the surface point Y position.

## Property Documentation

### autoColumnCategories : bool

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

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

Defines the column categories for the mapping.

Access functions:

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

Notifier signal:

void | columnCategoriesChanged()

### columnRole : QString

Defines the item model role to map into column category. In addition to defining which column the data belongs to, the value indicated by column role is also set as the X-coordinate value of the QSurfaceDataItem when model data is resolved, unless a separate xPos role is also defined.

Access functions:

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

Notifier signal:

void | columnRoleChanged(const QString &role)

### columnRolePattern : QRegExp

When set, 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.

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 defines 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 *

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

Access functions:

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

Notifier signal:

void | itemModelChanged(const QAbstractItemModel *itemModel)

### multiMatchBehavior : MultiMatchBehavior

This property defines how multiple matches for each row/column combination are handled. Defaults to QItemModelSurfaceDataProxy::MMBLast.

For example, you might have an item model with timestamped data taken at irregular intervals and you want to visualize an average position of data items on each hour with a surface graph. This can be done by specifying row and column categories so that each surface point represents an hour, and setting multiMatchBehavior to QItemModelSurfaceDataProxy::MMBAverage.

Access functions:

MultiMatchBehavior | multiMatchBehavior() const
void | setMultiMatchBehavior(MultiMatchBehavior behavior)

Notifier signal:

void | multiMatchBehaviorChanged(MultiMatchBehavior behavior)

### rowCategories : QStringList

Defines the row categories for the mapping.

Access functions:

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

Notifier signal:

void | rowCategoriesChanged()

### rowRole : QString

Defines the item model role to map into row category. In addition to defining which row the data belongs to, the value indicated by row role is also set as the Z-coordinate value of the QSurfaceDataItem when model data is resolved, unless a separate zPos role is also defined.

Access functions:

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

Notifier signal:

void | rowRoleChanged(const QString &role)

### rowRolePattern : QRegExp

When set, a search and replace is done 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.

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 defines 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

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)

### xPosRole : QString

Defines the item model role to map into X position. If this role is not defined, columnRole is used to determine the X-coordinate value of resolved QSurfaceDataItems.

Access functions:

QString | xPosRole() const
void | setXPosRole(const QString &role)

Notifier signal:

void | xPosRoleChanged(const QString &role)

### xPosRolePattern : QRegExp

When set, a search and replace is done on the value mapped by xPos role before it is used as a item position value. This property specifies the regular expression to find the portion of the mapped value to replace and xPosRoleReplace property contains the replacement string.

Access functions:

QRegExp | xPosRolePattern() const
void | setXPosRolePattern(const QRegExp &pattern)

Notifier signal:

void | xPosRolePatternChanged(const QRegExp &pattern)

See also xPosRole and xPosRoleReplace.

### xPosRoleReplace : QString

This property defines the replace content to be used in conjunction with xPosRolePattern. 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 | xPosRoleReplace() const
void | setXPosRoleReplace(const QString &replace)

Notifier signal:

void | xPosRoleReplaceChanged(const QString &replace)

See also xPosRole and xPosRolePattern.

### yPosRole : QString

Defines the item model role to map into Y position.

Access functions:

QString | yPosRole() const
void | setYPosRole(const QString &role)

Notifier signal:

void | yPosRoleChanged(const QString &role)

### yPosRolePattern : QRegExp

When set, a search and replace is done on the value mapped by yPos role before it is used as a item position value. This property specifies the regular expression to find the portion of the mapped value to replace and yPosRoleReplace property contains the replacement string.

Access functions:

QRegExp | yPosRolePattern() const
void | setYPosRolePattern(const QRegExp &pattern)

Notifier signal:

void | yPosRolePatternChanged(const QRegExp &pattern)

See also yPosRole and yPosRoleReplace.

### yPosRoleReplace : QString

This property defines the replace content to be used in conjunction with yPosRolePattern. 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 | yPosRoleReplace() const
void | setYPosRoleReplace(const QString &replace)

Notifier signal:

void | yPosRoleReplaceChanged(const QString &replace)

See also yPosRole and yPosRolePattern.

### zPosRole : QString

Defines the item model role to map into Z position. If this role is not defined, rowRole is used to determine the Z-coordinate value of resolved QSurfaceDataItems.

Access functions:

QString | zPosRole() const
void | setZPosRole(const QString &role)

Notifier signal:

void | zPosRoleChanged(const QString &role)

### zPosRolePattern : QRegExp

When set, a search and replace is done on the value mapped by zPos role before it is used as a item position value. This property specifies the regular expression to find the portion of the mapped value to replace and zPosRoleReplace property contains the replacement string.

Access functions:

QRegExp | zPosRolePattern() const
void | setZPosRolePattern(const QRegExp &pattern)

Notifier signal:

void | zPosRolePatternChanged(const QRegExp &pattern)

See also zPosRole and zPosRoleReplace.

### zPosRoleReplace : QString

This property defines the replace content to be used in conjunction with zPosRolePattern. 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 | zPosRoleReplace() const
void | setZPosRoleReplace(const QString &replace)

Notifier signal:

void | zPosRoleReplaceChanged(const QString &replace)

See also zPosRole and zPosRolePattern.

## Member Function Documentation

### QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QObject *parent = Q_NULLPTR)

Constructs QItemModelSurfaceDataProxy with optional parent.

### QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, QObject *parent = Q_NULLPTR)

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

### QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &yPosRole, QObject *parent = Q_NULLPTR)

Constructs QItemModelSurfaceDataProxy with itemModel and optional parent. Proxy doesn't take ownership of the itemModel, as typically item models are owned by other controls. The yPosRole role is set to yPosRole. 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.

### QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, QObject *parent = Q_NULLPTR)

Constructs QItemModelSurfaceDataProxy 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 yPosRole. The zPosRole and the xPosRole are set to rowRole and columnRole, respectively.

### QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, QObject *parent = Q_NULLPTR)

Constructs QItemModelSurfaceDataProxy 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, xPosRole, yPosRole, and zPosRole.

### QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = Q_NULLPTR)

Constructs QItemModelSurfaceDataProxy 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 yPosRole. The zPosRole and the xPosRole are set to rowRole and columnRole, respectively. Row and column categories are set with rowCategories and columnCategories. This constructor also sets autoRowCategories and autoColumnCategories to false.

### QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = Q_NULLPTR)

Constructs QItemModelSurfaceDataProxy 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, xPosRole, yPosRole, and zPosRole. Row and column categories are set with rowCategories and columnCategories. This constructor also sets autoRowCategories and autoColumnCategories to false.

### `[virtual]` QItemModelSurfaceDataProxy::~QItemModelSurfaceDataProxy()

Destroys QItemModelSurfaceDataProxy.

### int QItemModelSurfaceDataProxy::columnCategoryIndex(const QString &category)

Returns 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.

### void QItemModelSurfaceDataProxy::remap(const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, const QStringList &rowCategories, const QStringList &columnCategories)

Changes rowRole, columnRole, xPosRole, yPosRole, zPosRole, rowCategories and columnCategories to the mapping.

### int QItemModelSurfaceDataProxy::rowCategoryIndex(const QString &category)

Returns 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.