QBarSeries Class | Qt Graphs | Qt 6.12.0
Description: The QBarSeries class presents data in bar graphs.
Keywords: class

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

# QBarSeries Class

The QBarSeries class presents data in bar graphs. More...

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

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

## Public Types

enum class | BarsType { Groups, Stacked, StackedPercent }
enum class | LabelsPosition { Center, InsideEnd, InsideBase, OutsideEnd }

## Properties

barDelegate : QQmlComponent* barSets : QList<QBarSet *> barWidth : qreal barsType : BarsType borderColors : QList<QColor> count : qsizetype labelsAngle : qreal | labelsFormat : QString labelsMargin : qreal labelsPosition : LabelsPosition labelsPrecision : int labelsVisible : bool seriesColors : QList<QColor>

## Public Functions

| QBarSeries(QObject *parent = nullptr)
bool | append(QBarSet *set)
bool | append(const QList<QBarSet *> &sets)
QBarSet * | at(qsizetype index)
QQmlComponent * | barDelegate() const
QList<QBarSet *> | barSets() const
qreal | barWidth() const
QBarSeries::BarsType | barsType() const
QList<QColor> | borderColors() const
void | clear()
qsizetype | count() const
qsizetype | find(QBarSet *set) const
bool | insert(qsizetype index, QBarSet *set)
qreal | labelsAngle() const
QString | labelsFormat() const
qreal | labelsMargin() const
QBarSeries::LabelsPosition | labelsPosition() const
int | labelsPrecision() const
bool | labelsVisible() const
bool | remove(QBarSet *set)
bool | remove(qsizetype index)
void | removeMultiple(qsizetype index, qsizetype count)
bool | replace(const QList<QBarSet *> &sets)
bool | replace(QBarSet *oldValue, QBarSet *newValue)
void | replace(qsizetype index, QBarSet *set)
QList<QColor> | seriesColors() const
void | setBarDelegate(QQmlComponent *newBarDelegate)
void | setBarWidth(qreal width)
void | setBarsType(QBarSeries::BarsType type)
void | setBorderColors(const QList<QColor> &newBorderColors)
void | setLabelsAngle(qreal angle)
void | setLabelsFormat(const QString &format)
void | setLabelsMargin(qreal margin)
void | setLabelsPosition(QBarSeries::LabelsPosition position)
void | setLabelsPrecision(int precision)
void | setLabelsVisible(bool visible = true)
void | setSeriesColors(const QList<QColor> &newSeriesColors)
bool | take(QBarSet *set)

## Reimplemented Public Functions

virtual QAbstractSeries::SeriesType | type() const override

## Signals

void | barDelegateChanged()
void | barSetsChanged()
void | barWidthChanged()
void | barsTypeChanged(QBarSeries::BarsType type)
void | barsetsAdded(const QList<QBarSet *> &sets)
void | barsetsRemoved(const QList<QBarSet *> &sets)
void | borderColorsChanged()
void | countChanged()
void | labelsAngleChanged(qreal angle)
void | labelsFormatChanged(const QString &format)
void | labelsMarginChanged(qreal margin)
void | labelsPositionChanged(QBarSeries::LabelsPosition position)
void | labelsPrecisionChanged(int precision)
void | labelsVisibleChanged(bool visible)
void | seriesColorsChanged()
void | setValueAdded(qsizetype index, qsizetype count, QBarSet *barset)
void | setValueChanged(qsizetype index, QBarSet *barset)
void | setValueRemoved(qsizetype index, qsizetype count, QBarSet *barset)
void | updatedBars()

## Detailed Description

This class draws data by default as a series of bars grouped by category, with one bar per category from each bar set added to the series. It also supports horizontal bars and grouping bars as stacked.

A bar series needs the GraphsView x-axis to be set to a BarCategoryAxis and the y-axis set to ValueAxis.

See also QBarSet and QAbstractSeries.

## Member Type Documentation

### enum class QBarSeries::BarsType

This enum value describes the type of the bar series:

Constant | Value | Description
--- | --- | ---
`QBarSeries::BarsType::Groups` | `0` | Bar sets are grouped by category.
`QBarSeries::BarsType::Stacked` | `1` | Bar sets are stacked after each other by category.
`QBarSeries::BarsType::StackedPercent` | `2` | Bar sets are stacked after each other by category. The segment size corresponds to the percentage of the segment value compared with the total value of all segments in the stack.

### enum class QBarSeries::LabelsPosition

This enum value describes the position of the data value labels:

Constant | Value | Description
--- | --- | ---
`QBarSeries::LabelsPosition::Center` | `0` | Label is located in the center of the bar.
`QBarSeries::LabelsPosition::InsideEnd` | `1` | Label is located inside the bar at the top.
`QBarSeries::LabelsPosition::InsideBase` | `2` | Label is located inside the bar at the bottom.
`QBarSeries::LabelsPosition::OutsideEnd` | `3` | Label is located outside the bar at the top.

## Property Documentation

### barDelegate : QQmlComponent*

This property holds a custom QML component used for visualizing each of the bars. Instance of this component is created for each of the bar. When this is not defined, a default rectangle visualization for bars is used.

The dynamic properties available for this component are:

Type | Name | Description
--- | --- | ---
QColor | barColor | The fill color of the bar. This value comes either from the QGraphsTheme or from QBarSet::color if the QBarSet overrides the color.
QColor | barBorderColor | The border color of the bar. This value comes either from the QGraphsTheme or from QBarSet::borderColor if the QBarSet overrides the color.
qreal | barBorderWidth | The width of the bar border. This value comes either from the QGraphsTheme or from QBarSet::borderWidth if the QBarSet overrides the width.
qreal | barValue | The value of the bar. This value comes from the QBarSet::values.
QString | barLabel | The label of the bar. This value comes from the QBarSet::label.
bool | barSelected | This value is true when the bar is selected, meaning that the bar index is in QBarSet::selectedBars.
int | barIndex | Index of the bar, from 0 to the amount of bars - 1. [since 6.9]

To use any of these, add property with the defined name into your custom component. For example `"property color barColor"` and `"property real barValue"`.

Access functions:

QQmlComponent * | barDelegate() const
void | setBarDelegate(QQmlComponent *newBarDelegate)

Notifier signal:

void | barDelegateChanged()

### `[read-only]` barSets : QList<QBarSet *>

This property holds a list of sets added to the series.

Access functions:

QList<QBarSet *> | barSets() const

Notifier signal:

void | barSetsChanged()

### barWidth : qreal

This property holds the width of the bars of the series.

The unit of width is the unit of the x-axis. The minimum width for bars is zero, and negative values are treated as zero. Setting the width to zero means that the width of the bar on the screen is one pixel regardless of the scale of the x-axis. Bars wider than zero are scaled using the x-axis scale.

By default, the barWidth is 0.5 (bars will take 50% of the available width). The valid values range from 0.0 (0%) to 1.0 (100%).

Note: When used with QBarSeries, this value specifies the width of a group of bars instead of that of a single bar.

Access functions:

qreal | barWidth() const
void | setBarWidth(qreal width)

Notifier signal:

void | barWidthChanged()

See also QBarSeries.

### barsType : BarsType

This property holds the type of the bar series.

Access functions:

QBarSeries::BarsType | barsType() const
void | setBarsType(QBarSeries::BarsType type)

Notifier signal:

void | barsTypeChanged(QBarSeries::BarsType type)

### borderColors : QList<QColor>

This property holds the list of border colors to be used for all the objects in the series.

If there are more series than colors, the color list wraps and starts again with the first color in the list. If this is not set (default), colors from the QGraphsTheme::borderColors will be used.

Access functions:

QList<QColor> | borderColors() const
void | setBorderColors(const QList<QColor> &newBorderColors)

Notifier signal:

void | borderColorsChanged()

### `[read-only]` count : qsizetype

This property holds the number of bar sets in a bar series.

Access functions:

qsizetype | count() const | [see note below]

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

Notifier signal:

void | countChanged()

### labelsAngle : qreal

This property holds the angle of the value labels in degrees.

Access functions:

qreal | labelsAngle() const
void | setLabelsAngle(qreal angle)

Notifier signal:

void | labelsAngleChanged(qreal angle)

### labelsFormat : QString

This property holds the format used for showing labels in a bar series.

QBarSeries supports the following format tag:

@value | The value of the bar

For example, the following usage of the format tags would produce labels that show the value followed by the unit (u):

     series->setLabelsFormat("@value u");

By default, the labels show the value of the bar. For the percent bar series, % is added after the value. The labels are shown on the plot area, if the bars are close to each other, the labels may overlap.

Access functions:

QString | labelsFormat() const
void | setLabelsFormat(const QString &format)

Notifier signal:

void | labelsFormatChanged(const QString &format)

See also labelsVisible, labelsPosition, and labelsPrecision.

### labelsMargin : qreal

This property holds the margin of the value labels in pixels.

This margin from side is used when labelsPosition is set to something else than `LabelsPosition.Center`. The default value is `0`.

Access functions:

qreal | labelsMargin() const
void | setLabelsMargin(qreal margin)

Notifier signal:

void | labelsMarginChanged(qreal margin)

### labelsPosition : LabelsPosition

This property holds the position of value labels.

Access functions:

QBarSeries::LabelsPosition | labelsPosition() const
void | setLabelsPosition(QBarSeries::LabelsPosition position)

Notifier signal:

void | labelsPositionChanged(QBarSeries::LabelsPosition position)

See also labelsVisible and labelsFormat.

### labelsPrecision : int

This property holds the maximum amount of significant digits shown in value labels.

Default value is 6.

Access functions:

int | labelsPrecision() const
void | setLabelsPrecision(int precision)

Notifier signal:

void | labelsPrecisionChanged(int precision)

### labelsVisible : bool

This property holds the visibility of the labels in a bar series. The default label visibility is `false`.

Note: The default label only displays the value for the set. You can create custom labels with a barDelegate.

Access functions:

bool | labelsVisible() const
void | setLabelsVisible(bool visible = true)

Notifier signal:

void | labelsVisibleChanged(bool visible)

See also barDelegate.

### seriesColors : QList<QColor>

This property holds the list of base colors to be used for all the objects in the series.

If there are more series than colors, the color list wraps and starts again with the first color in the list. If this is not set (default), colors from the QGraphsTheme::seriesColors will be used.

Access functions:

QList<QColor> | seriesColors() const
void | setSeriesColors(const QList<QColor> &newSeriesColors)

Notifier signal:

void | seriesColorsChanged()

## Member Function Documentation

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

Constructs an empty bar series that is a QObject and a child of parent.

### `[invokable]` bool QBarSeries::append(QBarSet *set)

Adds a set of bars specified by set to the bar series and takes ownership of it. If the set is null or it already belongs to the series, it will not be appended. Returns `true` if appending succeeded.

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

### `[invokable]` bool QBarSeries::append(const QList<QBarSet *> &sets)

Adds a list of bar sets specified by sets to a bar series and takes ownership of the sets. Returns `true` if all sets were appended successfully. If any of the sets is null or was previously appended to the series, nothing is appended and this function returns `false`. If any of the sets appears in the list more than once, nothing is appended and this function returns `false`.

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

### `[invokable]` QBarSet *QBarSeries::at(qsizetype index)

Retrieves the BarSet specified at the location index. Returns null if no BarSet was found.

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

### QList<QBarSet *> QBarSeries::barSets() const

Returns a list of bar sets in a bar series. Keeps the ownership of the bar sets.

Note: Getter function for property barSets.

### qreal QBarSeries::barWidth() const

Returns the width of the bars of the series.

Note: Getter function for property barWidth.

See also setBarWidth().

### `[signal]` void QBarSeries::barsetsAdded(const QList<QBarSet *> &sets)

This signal is emitted when the bar sets specified by sets are added to the series.

See also append() and insert().

### `[signal]` void QBarSeries::barsetsRemoved(const QList<QBarSet *> &sets)

This signal is emitted when the bar sets specified by sets are removed from the series.

See also remove().

### `[invokable]` void QBarSeries::clear()

Removes all bar sets from the series and permanently deletes them.

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

### `[invokable]` qsizetype QBarSeries::count() const

Returns the number of bar sets in a bar series.

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

Note: Getter function for property count.

### `[invokable]` qsizetype QBarSeries::find(QBarSet *set) const

Returns the index of the first BarSet found as defined by set. Returns -1 if no BarSet was found.

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

### `[invokable]` bool QBarSeries::insert(qsizetype index, QBarSet *set)

Inserts a bar set specified by set to a series at the position specified by index and takes ownership of the set. If the set is null or already belongs to the series, it will not be appended. Returns `true` if inserting succeeds.

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

### bool QBarSeries::labelsVisible() const

Returns the visibility of labels.

Note: Getter function for property labelsVisible.

See also setLabelsVisible().

### `[signal]` void QBarSeries::labelsVisibleChanged(bool visible)

This signal is emitted when the labels' visibility changes to visible.

Note: Notifier signal for property labelsVisible.

See also labelsVisible() and setLabelsVisible().

### `[invokable]` bool QBarSeries::remove(QBarSet *set)

Removes the bar set specified by set from the series and permanently deletes it if the removal succeeds. Returns `true` if the set was removed.

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

### `[invokable]` bool QBarSeries::remove(qsizetype index)

Removes the BarSet at the location index. The BarSet will be permanently deleted.

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

### `[invokable]` void QBarSeries::removeMultiple(qsizetype index, qsizetype count)

Removes multiple BarSets from the series starting from index to a number of count. The BarSets will be permanently deleted.

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

### `[invokable]` bool QBarSeries::replace(const QList<QBarSet *> &sets)

Replaces the entire BarSet list inside of this BarSeries with the BarSets specified by sets. All of the original BarSets will be permanently deleted. Returns `true` if all BarSets are replaced.

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

### `[invokable]` bool QBarSeries::replace(QBarSet *oldValue, QBarSet *newValue)

Replaces the BarSet specified by oldValue with the one in newValue. The BarSet in oldValue will be permanently deleted if found inside the series. Returns `true` if the replace is successful.

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

### `[invokable]` void QBarSeries::replace(qsizetype index, QBarSet *set)

Replaces the BarSet which is present at index with set. The original BarSet will be permanently deleted.

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

### void QBarSeries::setBarWidth(qreal width)

Sets the width of the bars of the series to width.

Note: Setter function for property barWidth.

See also barWidth().

### void QBarSeries::setLabelsVisible(bool visible = true)

Sets the visibility of labels in a bar series to visible.

Note: Setter function for property labelsVisible.

See also labelsVisible().

### `[signal]` void QBarSeries::setValueAdded(qsizetype index, qsizetype count, QBarSet *barset)

This signal is emitted when a barset's value is changed. index is the index of the barset in the series. The number of the added values is indicated count. The barset is a pointer to the changed set.

### `[signal]` void QBarSeries::setValueChanged(qsizetype index, QBarSet *barset)

This signal is emitted when a barset's value is changed. index is the index of the barset in the series. The barset is a pointer to the changed set.

### `[signal]` void QBarSeries::setValueRemoved(qsizetype index, qsizetype count, QBarSet *barset)

This signal is emitted when a barset's value is changed. index is the index of the barset in the series. The number of the removed values is indicated count. The barset is a pointer to the changed set.

### `[invokable]` bool QBarSeries::take(QBarSet *set)

Takes a single set from the series. Does not delete the bar set object.

Note: The series remains the barset's parent object. You must set the parent object to take full ownership.

Returns `true` if the take operation succeeds.

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

### `[override virtual]` QAbstractSeries::SeriesType QBarSeries::type() const

Reimplements an access function for property: QAbstractSeries::type.

Returns the bar series.

### `[signal]` void QBarSeries::updatedBars()

This signal is emitted when bars are updated.