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
Instantiated By: BarSeries
Inherits: QAbstractSeries

Public Types

enum BarsOrientation { BarsVertical, BarsHorizontal }
enum BarsType { BarsGroups, BarsStacked }
enum LabelsPosition { LabelsCenter, LabelsInsideEnd, LabelsInsideBase, LabelsOutsideEnd }

Properties

Public Functions

QBarSeries(QObject *parent = nullptr)
virtual ~QBarSeries() override
bool append(QBarSet *set)
bool append(const QList<QBarSet *> &sets)
QAbstractAxis *axisX()
QAbstractAxis *axisY()
QQmlComponent *barComponent() const
QList<QBarSet *> barSets() const
qreal barWidth() const
QBarSeries::BarsOrientation barsOrientation() const
QBarSeries::BarsType barsType() const
void clear()
int count() const
bool insert(int index, QBarSet *set)
bool isLabelsVisible() const
qreal labelsAngle() const
QString labelsFormat() const
QBarSeries::LabelsPosition labelsPosition() const
int labelsPrecision() const
bool remove(QBarSet *set)
void setAxisX(QAbstractAxis *axis)
void setAxisY(QAbstractAxis *axis)
void setBarComponent(QQmlComponent *newBarComponent)
void setBarWidth(qreal width)
void setBarsOrientation(QBarSeries::BarsOrientation orientation)
void setBarsType(QBarSeries::BarsType type)
void setLabelsAngle(qreal angle)
void setLabelsFormat(const QString &format)
void setLabelsPosition(QBarSeries::LabelsPosition position)
void setLabelsPrecision(int precision)
void setLabelsVisible(bool visible = true)
bool take(QBarSet *set)

Reimplemented Public Functions

virtual QAbstractSeries::SeriesType type() const override

Signals

void axisXChanged(QAbstractAxis *axis)
void axisYChanged(QAbstractAxis *axis)
void barComponentChanged()
void barWidthChanged()
void barsOrientationChanged(QBarSeries::BarsOrientation orientation)
void barsTypeChanged(QBarSeries::BarsType type)
void barsetsAdded(const QList<QBarSet *> &sets)
void barsetsRemoved(const QList<QBarSet *> &sets)
void clicked(int index, QBarSet *barset)
void countChanged()
void doubleClicked(int index, QBarSet *barset)
void hovered(bool status, int index, QBarSet *barset)
void labelsAngleChanged(qreal angle)
void labelsFormatChanged(const QString &format)
void labelsPositionChanged(QBarSeries::LabelsPosition position)
void labelsPrecisionChanged(int precision)
void labelsVisibleChanged(bool visible)
void pressed(int index, QBarSet *barset)
void released(int index, QBarSet *barset)
void restructuredBars()
void setValueAdded(int index, int count, QBarSet *barset)
void setValueChanged(int index, QBarSet *barset)
void setValueRemoved(int index, int count, QBarSet *barset)
void updatedBars()
void updatedLayout()

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.

See also QBarSet and QAbstractSeries.

Member Type Documentation

enum QBarSeries::BarsOrientation

This enum value describes the orientation of the bar series:

ConstantValueDescription
QBarSeries::BarsVertical0Bars appear vertically.
QBarSeries::BarsHorizontal1Bars appear horizontally.

enum QBarSeries::BarsType

This enum value describes the type of the bar series:

ConstantValueDescription
QBarSeries::BarsGroups0Bar sets are grouped by category.
QBarSeries::BarsStacked1Bar sets are stacked after each other by category.

enum QBarSeries::LabelsPosition

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

ConstantValueDescription
QBarSeries::LabelsCenter0Label is located in the center of the bar.
QBarSeries::LabelsInsideEnd1Label is located inside the bar at the top.
QBarSeries::LabelsInsideBase2Label is located inside the bar at the bottom.
QBarSeries::LabelsOutsideEnd3Label is located outside the bar at the top.

Property Documentation

axisX : QAbstractAxis*

X-axis of the series.

The x-axis used for the series. This should be QBarCategoryAxis.

Access functions:

QAbstractAxis *axisX()
void setAxisX(QAbstractAxis *axis)

Notifier signal:

void axisXChanged(QAbstractAxis *axis)

axisY : QAbstractAxis*

Y-axis of the series.

The y-axis used for the series. This should be QValueAxis.

Access functions:

QAbstractAxis *axisY()
void setAxisY(QAbstractAxis *axis)

Notifier signal:

void axisYChanged(QAbstractAxis *axis)

barComponent : 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. To get access into bars properties, use BarComponent. When this is not defined, a default rectangle visualization for bars is used.

Access functions:

QQmlComponent *barComponent() const
void setBarComponent(QQmlComponent *newBarComponent)

Notifier signal:

void barComponentChanged()

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:

See also QBarSeries.

barsOrientation : BarsOrientation

This property holds the orientation of the bar series. By default the bars appear vertically.

Access functions:

QBarSeries::BarsOrientation barsOrientation() const
void setBarsOrientation(QBarSeries::BarsOrientation orientation)

Notifier signal:

void barsOrientationChanged(QBarSeries::BarsOrientation orientation)

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)

[read-only] count : const int

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

Access functions:

int count() const

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:

@valueThe 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.

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.

Access functions:

bool isLabelsVisible() const
void setLabelsVisible(bool visible = true)

Notifier signal:

void labelsVisibleChanged(bool visible)

Member Function Documentation

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

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

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

Removes the bar series and the bar sets owned by it.

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.

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.

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

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

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::barWidthChanged()

This signal is emitted when the bar width changes.

Note: Notifier signal for property barWidth.

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

void QBarSeries::clear()

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

[signal] void QBarSeries::clicked(int index, QBarSet *barset)

This signal is emitted when the user clicks the bar specified by index in the bar set specified by barset.

int QBarSeries::count() const

Returns the number of bar sets in a bar series.

Note: Getter function for property count.

[signal] void QBarSeries::countChanged()

This signal is emitted when the number of bar sets is changed, for example by append() or remove().

Note: Notifier signal for property count.

[signal] void QBarSeries::doubleClicked(int index, QBarSet *barset)

This signal is emitted when the user double-clicks the bar specified by index in the bar set specified by barset.

[signal] void QBarSeries::hovered(bool status, int index, QBarSet *barset)

This signal is emitted when a mouse is hovered over the bar specified by index in the bar set specified by barset. When the mouse moves over the bar, status turns true, and when the mouse moves away again, it turns false.

bool QBarSeries::insert(int 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.

bool QBarSeries::isLabelsVisible() const

Returns the visibility of labels.

Note: Getter function for property labelsVisible.

[signal] void QBarSeries::labelsAngleChanged(qreal angle)

This signal is emitted when the angle of the value labels changes.

Note: Notifier signal for property labelsAngle.

[signal] void QBarSeries::labelsFormatChanged(const QString &format)

This signal is emitted when the format of data value labels changes.

Note: Notifier signal for property labelsFormat.

[signal] void QBarSeries::labelsPositionChanged(QBarSeries::LabelsPosition position)

This signal is emitted when the position of value labels changes.

Note: Notifier signal for property labelsPosition.

[signal] void QBarSeries::labelsPrecisionChanged(int precision)

This signal is emitted when the precision of the value labels changes.

Note: Notifier signal for property labelsPrecision.

[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 isLabelsVisible() and setLabelsVisible().

[signal] void QBarSeries::pressed(int index, QBarSet *barset)

This signal is emitted when the user clicks the bar specified by index in the bar set specified by barset and holds down the mouse button.

[signal] void QBarSeries::released(int index, QBarSet *barset)

This signal is emitted when the user releases the mouse press on the bar specified by index in the bar set specified by barset.

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.

[signal] void QBarSeries::restructuredBars()

This signal is emitted when the bars are restructured.

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 isLabelsVisible().

[signal] void QBarSeries::setValueAdded(int index, int 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(int 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(int index, int 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.

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.

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

[signal] void QBarSeries::updatedLayout()

This signal is emitted when the layout is updated.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.