- Qt 6.12
- Qt Graphs
- C++ Classes
- QtGraphs
- QBar3DSeries
- Qt Graphs | Commercial or GPLv3

# QBar3DSeries Class

The QBar3DSeries class represents a data series in a 3D bar graph. More...

Header: | `#include <QBar3DSeries>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Graphs)` `target_link_libraries(mytarget PRIVATE Qt6::Graphs)`
qmake: | `QT += graphs`
In QML: | Bar3DSeries
Inherits: | QAbstract3DSeries

- List of all members, including inherited members
- QBar3DSeries is part of Qt Graphs C++ Classes for 3D.

## Properties

`(since 6.11)` columnAxis : QCategory3DAxis* columnLabels : QStringList `(since 6.11)` customColumnLabels : QStringList `(since 6.11)` customRowLabels : QStringList dataArray : QBarDataArray dataProxy : QBarDataProxy* meshAngle : float | `(since 6.11)` rowAxis : QCategory3DAxis* rowColors : QList<QColor> rowLabels : QStringList selectedBar : QPoint `(since 6.11)` valueAxis : QValue3DAxis* `(since 6.9)` valueColoringEnabled : bool

## Public Functions

| QBar3DSeries(QObject *parent = nullptr)
| QBar3DSeries(QBarDataProxy *dataProxy, QObject *parent = nullptr)
virtual | ~QBar3DSeries() override
void | clearArray()
void | clearRow(qsizetype rowIndex)
QCategory3DAxis * | columnAxis() const
QStringList | columnLabels() const
QStringList | customColumnLabels() const
QStringList | customRowLabels() const
const QBarDataArray & | dataArray() const &
QBarDataArray | dataArray() &&
QBarDataProxy * | dataProxy() const
bool | isValueColoringEnabled() const
float | meshAngle() const
void | resetColumnAxis()
void | resetRowAxis()
void | resetValueAxis()
QCategory3DAxis * | rowAxis() const
QList<QColor> | rowColors() const
QStringList | rowLabels() const
QPoint | selectedBar() const
void | setColumnAxis(QCategory3DAxis *axis)
void | setColumnLabels(const QStringList &labels)
void | setCustomColumnLabels(const QStringList &labels)
void | setCustomRowLabels(const QStringList &labels)
void | setDataArray(const QBarDataArray &newDataArray)
void | setDataProxy(QBarDataProxy *proxy)
void | setMeshAngle(float angle)
void | setRowAxis(QCategory3DAxis *axis)
void | setRowColors(const QList<QColor> &colors)
void | setRowLabels(const QStringList &labels)
void | setSelectedBar(QPoint position)
void | setValueAxis(QValue3DAxis *axis)
void | setValueColoringEnabled(bool enabled)
QValue3DAxis * | valueAxis() const

## Signals

void | columnAxisChanged(QCategory3DAxis *axis)
void | columnLabelsChanged()
void | customColumnLabelsChanged(const QStringList &newCustomColumnLabels)
void | customRowLabelsChanged(const QStringList &newCustomRowLabels)
void | dataArrayChanged(const QBarDataArray &array)
void | dataProxyChanged(QBarDataProxy *proxy)
void | meshAngleChanged(float angle)
void | rowAxisChanged(QCategory3DAxis *axis)
void | rowColorsChanged(const QList<QColor> &rowcolors)
void | rowLabelsChanged()
void | selectedBarChanged(QPoint position)
void | valueAxisChanged(QValue3DAxis *axis)
void | valueColoringEnabledChanged(bool enabled)

## Static Public Members

QPoint | invalidSelectionPosition()

## Detailed Description

This class manages the series specific visual elements, as well as the series data (via a data proxy).

Regarding the proxy-series relationship, it is crucial to highlight a couple of key points. In this context, data is stored in series and users can access the dataset through the series. This series is controlled or represented by a proxy object. Thus, the proxy can be used to manage various operations on the data and update the actual dataset. However, it is necessary to create a series associated with this proxy to edit the dataset.

If no data proxy is set explicitly for the series, the series creates a default proxy. Setting another proxy will destroy the existing proxy and all data added to the series.

QBar3DSeries supports the following format tags for QAbstract3DSeries::setItemLabelFormat():

@rowTitle | Title from row axis
@colTitle | Title from column axis
@valueTitle | Title from value axis
@rowIdx | Visible row index. Localized using the graph locale.
@colIdx | Visible column index. Localized using the graph locale.
@rowLabel | Label from row axis
@colLabel | Label from column axis
@valueLabel | Item value formatted using the format of the value axis attached to the graph. For more information, see QValue3DAxis::labelFormat.
@seriesName | Name of the series
%<format spec> | Item value in the specified format. Formatted using the same rules as QValue3DAxis::labelFormat.

For example:

     proxy->setItemLabelFormat(QStringLiteral("@valueTitle for (@rowLabel, @colLabel): %.1f"));

See also Qt Graphs Data Handling with 3D and Q3DGraphsWidgetItem::locale.

## Property Documentation

### `[since 6.11]` columnAxis : QCategory3DAxis*

Holds an additional column axis for the series

Note: The additional axis does not adjust the fitting of the graph, but allows for an extra set of labels and an axis grid.

This enumeration was introduced in Qt 6.11.

Access functions:

QCategory3DAxis * | columnAxis() const
void | setColumnAxis(QCategory3DAxis *axis)
void | resetColumnAxis()

Notifier signal:

void | columnAxisChanged(QCategory3DAxis *axis)

### columnLabels : QStringList

This property holds the optional column labels for the array.

Indexes in this array match column indexes in rows. If the list is shorter than the longest row, all columns will not get labels.

Access functions:

QStringList | columnLabels() const
void | setColumnLabels(const QStringList &labels)

Notifier signal:

void | columnLabelsChanged()

### `[since 6.11]` customColumnLabels : QStringList

This property holds the optional custom column labels for the array.

These labels will override any labels generated by a proxy. Indexes in this array match column indexes in rows. If the list is shorter than the longest row, all columns will not get labels.

This enumeration was introduced in Qt 6.11.

Access functions:

QStringList | customColumnLabels() const
void | setCustomColumnLabels(const QStringList &labels)

Notifier signal:

void | customColumnLabelsChanged(const QStringList &newCustomColumnLabels)

### `[since 6.11]` customRowLabels : QStringList

This property holds the optional custom row labels for the array.

These labels will override any labels generated by a proxy. Indexes in this array match the row indexes in the data array. If the list is shorter than the number of rows, all rows will not get labels.

This enumeration was introduced in Qt 6.11.

Access functions:

QStringList | customRowLabels() const
void | setCustomRowLabels(const QStringList &labels)

Notifier signal:

void | customRowLabelsChanged(const QStringList &newCustomRowLabels)

### dataArray : QBarDataArray

Data array for the series.

Holds the reference of the data array.

dataArrayChanged signal is emitted when data array is set, unless newDataArray is identical to the previous one.

Note: Before doing anything regarding the dataArray, a series must be created for the relevant proxy.

Access functions:

const QBarDataArray & | dataArray() const &
QBarDataArray | dataArray() &&
void | setDataArray(const QBarDataArray &newDataArray)

Notifier signal:

void | dataArrayChanged(const QBarDataArray &array)

See also clearRow(qsizetype rowIndex) and clearArray().

### dataProxy : QBarDataProxy*

This property holds the active data proxy.

The series assumes ownership of any proxy set to it and deletes any previously set proxy when a new one is added. The proxy cannot be null or set to another series.

Access functions:

QBarDataProxy * | dataProxy() const
void | setDataProxy(QBarDataProxy *proxy)

Notifier signal:

void | dataProxyChanged(QBarDataProxy *proxy)

### meshAngle : float

This property holds the series rotation angle in degrees.

Setting this property is equivalent to the following call:

     setMeshRotation(QQuaternion::fromAxisAndAngle(0.0f, 1.0f, 0.0f, angle))

Note: When reading this property, it is calculated from the QAbstract3DSeries::meshRotation value using floating point precision and always returns a value from zero to 360 degrees.

Access functions:

float | meshAngle() const
void | setMeshAngle(float angle)

Notifier signal:

void | meshAngleChanged(float angle)

See also QAbstract3DSeries::meshRotation.

### `[since 6.11]` rowAxis : QCategory3DAxis*

Holds an additional row axis for the series

Note: The additional axis does not adjust the fitting of the graph, but allows for an extra set of labels and an axis grid.

This enumeration was introduced in Qt 6.11.

Access functions:

QCategory3DAxis * | rowAxis() const
void | setRowAxis(QCategory3DAxis *axis)
void | resetRowAxis()

Notifier signal:

void | rowAxisChanged(QCategory3DAxis *axis)

### rowColors : QList<QColor>

This property holds the list of row colors in the series.

This property can be used to color the rows of the series in different colors. The QGraphsTheme::ColorStyle must be set to QGraphsTheme::ColorStyle::Uniform to use this property.

Access functions:

QList<QColor> | rowColors() const
void | setRowColors(const QList<QColor> &colors)

Notifier signal:

void | rowColorsChanged(const QList<QColor> &rowcolors)

See also QGraphsTheme::ColorStyle::Uniform.

### rowLabels : QStringList

This property holds the optional row labels for the array.

Indexes in this array match the row indexes in the data array. If the list is shorter than the number of rows, all rows will not get labels.

Access functions:

QStringList | rowLabels() const
void | setRowLabels(const QStringList &labels)

Notifier signal:

void | rowLabelsChanged()

### selectedBar : QPoint

This property holds the bar in the series that is selected.

Access functions:

QPoint | selectedBar() const
void | setSelectedBar(QPoint position)

Notifier signal:

void | selectedBarChanged(QPoint position)

### `[since 6.11]` valueAxis : QValue3DAxis*

Holds an additional value axis for the series If an axis is given, the series will be fitted to the minimum and maximum values of the axis.

This enumeration was introduced in Qt 6.11.

Access functions:

QValue3DAxis * | valueAxis() const
void | setValueAxis(QValue3DAxis *axis)
void | resetValueAxis()

Notifier signal:

void | valueAxisChanged(QValue3DAxis *axis)

### `[since 6.9]` valueColoringEnabled : bool

Use the given value to color the whole bar based on the range gradient

This property can be used to color each bar separately based on its value and given range gradient. The QGraphsTheme::ColorStyle must be set to QGraphsTheme::ColorStyle::RangeGradient to use this property.

This enumeration was introduced in Qt 6.9.

Access functions:

bool | isValueColoringEnabled() const
void | setValueColoringEnabled(bool enabled)

Notifier signal:

void | valueColoringEnabledChanged(bool enabled)

See also QGraphsTheme::ColorStyle::RangeGradient.

## Member Function Documentation

### `[explicit]` QBar3DSeries::QBar3DSeries(QObject *parent = nullptr)

Constructs a bar 3D series with the parent parent.

### `[explicit]` QBar3DSeries::QBar3DSeries(QBarDataProxy *dataProxy, QObject *parent = nullptr)

Constructs a bar 3D series with the data proxy dataProxy and the parent parent.

### `[override virtual noexcept]` QBar3DSeries::~QBar3DSeries()

Deletes a bar 3D series.

### void QBar3DSeries::clearArray()

Clears the existing array.

### void QBar3DSeries::clearRow(qsizetype rowIndex)

Clears the existing row in the array according to given rowIndex.

### `[static]` QPoint QBar3DSeries::invalidSelectionPosition()

Returns an invalid position for selection. This position is set to the selectedBar property to clear the selection from this series.

See also Q3DGraphsWidgetItem::clearSelection().

### void QBar3DSeries::setSelectedBar(QPoint position)

Selects the bar at the position position, specified as a row and column in the data array of the series.

Only one bar can be selected at a time.

To clear the selection from this series, invalidSelectionPosition() is set as position.

If this series is added to a graph, the graph can adjust the selection according to user interaction or if it becomes invalid. Selecting a bar on another added series will also clear the selection.

Removing rows from or inserting rows into the series before the row of the selected bar will adjust the selection so that the same bar will stay selected.

Note: Setter function for property selectedBar.

See also selectedBar() and Q3DGraphsWidgetItem::clearSelection().