QItemModelSurfaceDataProxy Class

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

Header: #include <QItemModelSurfaceDataProxy>
CMake: find_package(Qt6 REQUIRED COMPONENTS Graphs)
target_link_libraries(mytarget PRIVATE Qt6::Graphs)
qmake: QT += graphs
Instantiated By: ItemModelSurfaceDataProxy
Inherits: QSurfaceDataProxy
Status: Technical Preview

Public Types

enum class MultiMatchBehavior { First, Last, Average, CumulativeY }

Properties

Public Functions

QItemModelSurfaceDataProxy(QObject *parent = nullptr)
QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, QObject *parent = nullptr)
QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &yPosRole, QObject *parent = nullptr)
QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, QObject *parent = nullptr)
QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, QObject *parent = nullptr)
QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = 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 = nullptr)
virtual ~QItemModelSurfaceDataProxy() override
bool autoColumnCategories() const
bool autoRowCategories() const
QStringList columnCategories() const
int columnCategoryIndex(const QString &category)
QString columnRole() const
QRegularExpression columnRolePattern() const
QString columnRoleReplace() const
QAbstractItemModel *itemModel() const
QItemModelSurfaceDataProxy::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
QRegularExpression 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 QRegularExpression &pattern)
void setColumnRoleReplace(const QString &replace)
void setItemModel(QAbstractItemModel *itemModel)
void setMultiMatchBehavior(QItemModelSurfaceDataProxy::MultiMatchBehavior behavior)
void setRowCategories(const QStringList &categories)
void setRowRole(const QString &role)
void setRowRolePattern(const QRegularExpression &pattern)
void setRowRoleReplace(const QString &replace)
void setUseModelCategories(bool enable)
void setXPosRole(const QString &role)
void setXPosRolePattern(const QRegularExpression &pattern)
void setXPosRoleReplace(const QString &replace)
void setYPosRole(const QString &role)
void setYPosRolePattern(const QRegularExpression &pattern)
void setYPosRoleReplace(const QString &replace)
void setZPosRole(const QString &role)
void setZPosRolePattern(const QRegularExpression &pattern)
void setZPosRoleReplace(const QString &replace)
bool useModelCategories() const
QString xPosRole() const
QRegularExpression xPosRolePattern() const
QString xPosRoleReplace() const
QString yPosRole() const
QRegularExpression yPosRolePattern() const
QString yPosRoleReplace() const
QString zPosRole() const
QRegularExpression zPosRolePattern() const
QString zPosRoleReplace() const

Signals

void autoColumnCategoriesChanged(bool enable)
void autoRowCategoriesChanged(bool enable)
void columnCategoriesChanged()
void columnRoleChanged(const QString &role)
void columnRolePatternChanged(const QRegularExpression &pattern)
void columnRoleReplaceChanged(const QString &replace)
void itemModelChanged(const QAbstractItemModel *itemModel)
void multiMatchBehaviorChanged(QItemModelSurfaceDataProxy::MultiMatchBehavior behavior)
void rowCategoriesChanged()
void rowRoleChanged(const QString &role)
void rowRolePatternChanged(const QRegularExpression &pattern)
void rowRoleReplaceChanged(const QString &replace)
void useModelCategoriesChanged(bool enable)
void xPosRoleChanged(const QString &role)
void xPosRolePatternChanged(const QRegularExpression &pattern)
void xPosRoleReplaceChanged(const QString &replace)
void yPosRoleChanged(const QString &role)
void yPosRolePatternChanged(const QRegularExpression &pattern)
void yPosRoleReplaceChanged(const QString &replace)
void zPosRoleChanged(const QString &role)
void zPosRolePatternChanged(const QRegularExpression &pattern)
void zPosRoleReplaceChanged(const QString &replace)

Detailed Description

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.

Mappings can be used in the following ways:

  • 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.
  • 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.
  • 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 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 ItemModelBarDataProxy usage in Simple Bar Graph.

See also Qt Graphs Data Handling with 3D.

Member Type Documentation

enum class QItemModelSurfaceDataProxy::MultiMatchBehavior

Behavior types for QItemModelSurfaceDataProxy::multiMatchBehavior property.

ConstantValueDescription
QItemModelSurfaceDataProxy::MultiMatchBehavior::First0The position values are taken from the first item in the item model that matches each row/column combination.
QItemModelSurfaceDataProxy::MultiMatchBehavior::Last1The position values are taken from the last item in the item model that matches each row/column combination.
QItemModelSurfaceDataProxy::MultiMatchBehavior::Average2The position values from all items matching each row/column combination are averaged together and the averages are used as the surface point position.
QItemModelSurfaceDataProxy::MultiMatchBehavior::CumulativeY3For X and Z values this acts just like Average, but Y values are added together instead of averaged and the total is used as the surface point Y position.

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 the 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 the 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 item model role to map to the column category.

In addition to defining which column the data belongs to, the value indicated by the column role is also set as the X-coordinate value of QSurfaceDataItem when model data is resolved, unless a separate x position role is also defined.

Access functions:

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

Notifier signal:

void columnRoleChanged(const QString &role)

columnRolePattern : QRegularExpression

This property holds whether a search and replace is done on the value mapped by the 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 the columnRoleReplace property contains the replacement string.

Access functions:

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

Notifier signal:

void columnRolePatternChanged(const QRegularExpression &pattern)

See also columnRole and columnRoleReplace.

columnRoleReplace : QString

This property holds the replace content to be used in conjunction with a column role pattern.

Defaults to an empty string. For more information on how the search and replace using regular expressions works, see the QString::replace(const QRegularExpression &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 used as a data source for the 3D surface.

Access functions:

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

Notifier signal:

void itemModelChanged(const QAbstractItemModel *itemModel)

multiMatchBehavior : QItemModelSurfaceDataProxy::MultiMatchBehavior

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

Defaults to Last.

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 this property to Average.

Access functions:

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

Notifier signal:

void multiMatchBehaviorChanged(QItemModelSurfaceDataProxy::MultiMatchBehavior behavior)

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 item model role to map to the row category.

In addition to defining which row the data belongs to, the value indicated by the row role is also set as the Z-coordinate value of QSurfaceDataItem when model data is resolved, unless a separate z position role is also defined.

Access functions:

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

Notifier signal:

void rowRoleChanged(const QString &role)

rowRolePattern : QRegularExpression

This property holds whether a search and replace is performed on the value mapped by the 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 the rowRoleReplace property contains the replacement string.

Access functions:

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

Notifier signal:

void rowRolePatternChanged(const QRegularExpression &pattern)

See also rowRole and rowRoleReplace.

rowRoleReplace : QString

This property holds the replace content to be used in conjunction with the row role pattern.

Defaults to an empty string. For more information on how the search and replace using regular expressions works, see QString::replace(const QRegularExpression &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)

xPosRole : QString

This property holds the item model role to map to the X position.

If this role is not defined, columnRole is used to determine the X-coordinate value of the resolved QSurfaceDataItem objects.

Access functions:

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

Notifier signal:

void xPosRoleChanged(const QString &role)

xPosRolePattern : QRegularExpression

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

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

Access functions:

QRegularExpression xPosRolePattern() const
void setXPosRolePattern(const QRegularExpression &pattern)

Notifier signal:

void xPosRolePatternChanged(const QRegularExpression &pattern)

See also xPosRole and xPosRoleReplace.

xPosRoleReplace : QString

This property holds the replace content to be used in conjunction with an x position role pattern.

Defaults to an empty string. For more information on how the search and replace using regular expressions works, see the QString::replace(const QRegularExpression &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

This property holds the item model role to map to the Y position.

Access functions:

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

Notifier signal:

void yPosRoleChanged(const QString &role)

yPosRolePattern : QRegularExpression

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

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

Access functions:

QRegularExpression yPosRolePattern() const
void setYPosRolePattern(const QRegularExpression &pattern)

Notifier signal:

void yPosRolePatternChanged(const QRegularExpression &pattern)

See also yPosRole and yPosRoleReplace.

yPosRoleReplace : QString

This property holds the replace content to be used in conjunction with an y position role pattern.

Defaults to an empty string. For more information on how the search and replace using regular expressions works, see the QString::replace(const QRegularExpression &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

This property holds the item model role to map to the Z position.

If this role is not defined, rowRole is used to determine the Z-coordinate value of resolved QSurfaceDataItem objects.

Access functions:

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

Notifier signal:

void zPosRoleChanged(const QString &role)

zPosRolePattern : QRegularExpression

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

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

Access functions:

QRegularExpression zPosRolePattern() const
void setZPosRolePattern(const QRegularExpression &pattern)

Notifier signal:

void zPosRolePatternChanged(const QRegularExpression &pattern)

See also zPosRole and zPosRoleReplace.

zPosRoleReplace : QString

This property holds the replace content to be used in conjunction with a z position role pattern.

Defaults to an empty string. For more information on how the search and replace using regular expressions works, see the QString::replace(const QRegularExpression &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

[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QObject *parent = nullptr)

Constructs QItemModelSurfaceDataProxy with optional parent.

[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, QObject *parent = 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.

[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &yPosRole, QObject *parent = 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.

[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, QObject *parent = 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.

[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, QObject *parent = 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.

[explicit] QItemModelSurfaceDataProxy::QItemModelSurfaceDataProxy(QAbstractItemModel *itemModel, const QString &rowRole, const QString &columnRole, const QString &yPosRole, const QStringList &rowCategories, const QStringList &columnCategories, QObject *parent = 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.

[explicit] 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 = 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.

[override virtual noexcept] QItemModelSurfaceDataProxy::~QItemModelSurfaceDataProxy()

Destroys QItemModelSurfaceDataProxy.

[invokable] int QItemModelSurfaceDataProxy::columnCategoryIndex(const QString &category)

Returns the index of the specified category in the 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 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.

[invokable] int QItemModelSurfaceDataProxy::rowCategoryIndex(const QString &category)

Returns the index of the specified category in the 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 QItemModelSurfaceDataProxy::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().