Class QAccelPlot::BandSeries¶

ClassList > QAccelPlot > BandSeries

A hardware-accelerated QML item that fills the area between a low and a high value at each X. More...

#include <BandSeries.hpp>

Inherits the following classes: QAccelPlot::PlotSeries

Inheritance diagram¶

flowchart TB
  classQAccelPlot_1_1BandSeries["QAccelPlot::BandSeries"]

  classQAccelPlot_1_1PlotSeries["QAccelPlot::PlotSeries"]
  classQAccelPlot_1_1PlotSeries --> classQAccelPlot_1_1BandSeries
  click classQAccelPlot_1_1PlotSeries "../classQAccelPlot_1_1PlotSeries/" "Open QAccelPlot::PlotSeries"

  external_base_classQAccelPlot_1_1PlotSeries_1["QQuickItem"]
  external_base_classQAccelPlot_1_1PlotSeries_1 --> classQAccelPlot_1_1PlotSeries

Public Types inherited from QAccelPlot::PlotSeries¶

See QAccelPlot::PlotSeries

Type	Name
enum	LegendSymbol Supported default legend symbols.

Public Properties¶

Type	Name
property QColor	color Fill color. Default: `Colors.dark.seriesPrimary` with alpha 64.
property BandEdges *	edges Grouped edge line settings, e.g. `edges.width` and`edges.lineStyle` . No edge lines by default.

Public Properties inherited from QAccelPlot::PlotSeries¶

See QAccelPlot::PlotSeries

Type	Name
property int	count Read-only: number of records stored, including invalid ones.
property quint64	dataRevision Revision incremented by every accepted change of the series' records.
property bool	hoverEnabled Whether the series reacts to the mouse cursor. Default: `true` .
property bool	hovered Read-only: `true` while the mouse cursor is over the series.
property SeriesInspection *	inspection Read-only constant: data queries for this series.
property LegendSymbol	legendSymbol Symbol style requested from the default legend.
property QString	name Identifying name used by the default legend.
property QRectF	plotRect Plot area in parent-item coordinates, assigned by `PlotView` .
property Axis *	xAxis Horizontal axis used for data-to-pixel coordinate mapping.
property Axis *	yAxis Vertical axis used for data-to-pixel coordinate mapping.

Public Signals¶

Type	Name
signal void	colorChanged Emitted when the color property changes.

Public Signals inherited from QAccelPlot::PlotSeries¶

See QAccelPlot::PlotSeries

Type	Name
signal void	countChanged Emitted when the number of records changes.
signal void	dataRevisionChanged Emitted when the dataRevision property changes.
signal void	hoverEnabledChanged Emitted when the hoverEnabled property changes.
signal void	hoveredChanged Emitted when the hovered property changes.
signal void	legendEntryChanged Emitted when the result of `legendEntry()` or`legendEntries()` changes.
signal void	legendSymbolChanged
signal void	nameChanged
signal void	plotRectChanged
signal void	xAxisChanged
signal void	yAxisChanged

Public Functions¶

Type	Name
	BandSeries (QQuickItem * parent=nullptr) Constructs a BandSeries with the given__parent .
Q_INVOKABLE void	appendData (qreal x, qreal low, qreal high) Appends the data point ( x _,_low _,_high ). Triggers a redraw.
virtual Q_INVOKABLE void	clearData () override Removes all data points.
QColor	color () const Returns the fill color.
bool	contains (const QPointF & point) override const Returns `true` when item position__point lies inside the band or on an edge line.
BandEdges *	edges () const Returns the grouped edge line settings. The object is owned by the series.
virtual std::optional< LegendEntry >	legendEntry () override const Returns the legend entry: the symbol and color of the band.
void	setColor (const QColor & color) Sets the fill color to color .
Q_INVOKABLE void	setData (const QList< qreal > & xs, const QList< qreal > & lows, const QList< qreal > & highs) Replaces the data points with xs _,_lows , and__highs . If the sizes differ, the shortest length is used.
void	setData (const std::vector< double > & xs, const std::vector< double > & lows, const std::vector< double > & highs) Replaces the data points with xs _,_lows , and__highs . If the sizes differ, the shortest length is used.
void	setData (const double * data, int count) Replaces the series data with count data points copied from an interleaved double array.
void	setData (std::vector< double > && data, int count) Replaces the series data by moving an interleaved double buffer.
void	setData (const double * data, int count, const DataBounds & bounds) Like `setData` _(_data _,_count ), with the data extents given as__bounds instead of scanned for.
void	setData (std::vector< double > && data, int count, const DataBounds & bounds) Like `setData` _(_data _,_count ), with the data extents given as__bounds instead of scanned for.
void	setDataF (const float * data, int count) Replaces the series data with count data points copied from an interleaved float array.
void	setDataF (std::vector< float > && data, int count) Replaces the series data by moving an interleaved float buffer.
void	setDataF (const float * data, int count, const DataBounds & bounds) Like `setDataF` _(_data _,_count ), with the data extents given as__bounds instead of scanned for.
void	setDataF (std::vector< float > && data, int count, const DataBounds & bounds) Like `setDataF` _(_data _,_count ), with the data extents given as__bounds instead of scanned for.
Q_INVOKABLE QVariantMap	valueAt (qreal x) const Returns the band at data coordinate x as an object with`x` ,`low` , and`high` properties.

Public Functions inherited from QAccelPlot::PlotSeries¶

See QAccelPlot::PlotSeries

Type	Name
	PlotSeries (QQuickItem * parent=nullptr)
virtual void	clearData () Removes all data points from the series.
virtual int	count () const Returns the number of records stored. The default is the number of stored data points.
quint64	dataRevision () const Returns the current data revision.
bool	hoverEnabled () const Returns whether the series reacts to the mouse cursor.
bool	hovered () const Returns whether the mouse cursor is over the series.
SeriesInspection *	inspection () const Returns the data queries for this series; created on first use and owned by the series.
virtual QList< LegendEntry >	legendEntries () const Returns the legend rows of the series. Default: the `legendEntry()` , if any.
virtual std::optional< LegendEntry >	legendEntry () const Returns how a legend draws the series, or `std::nullopt` for no legend entry. Default: no entry.
LegendSymbol	legendSymbol () const
QString	name () const
QRectF	plotRect () const
void	postData (std::vector< double > && data, int count) Queues a moved double buffer for assignment on the series' thread.
void	postData (std::vector< float > && data, int count) Queues a moved float buffer for assignment on the series' thread.
void	setData (const double * data, int count) Replaces the series data with count data points copied from an interleaved double array.
void	setData (std::vector< double > && data, int count) Replaces the series data by moving an interleaved double buffer.
void	setData (const double * data, int count, const DataBounds & bounds) Like `setData` _(_data _,_count ), with the data extents given as__bounds instead of scanned for.
void	setData (std::vector< double > && data, int count, const DataBounds & bounds) Like `setData` _(_data _,_count ), with the data extents given as__bounds instead of scanned for.
void	setDataF (const float * data, int count) Replaces the series data with count data points copied from an interleaved float array.
void	setDataF (std::vector< float > && data, int count) Replaces the series data by moving an interleaved float buffer.
void	setDataF (const float * data, int count, const DataBounds & bounds) Like `setDataF` _(_data _,_count ), with the data extents given as__bounds instead of scanned for.
void	setDataF (std::vector< float > && data, int count, const DataBounds & bounds) Like `setDataF` _(_data _,_count ), with the data extents given as__bounds instead of scanned for.
void	setHoverEnabled (bool enabled) Sets whether the series reacts to the mouse cursor to enabled .
void	setLegendSymbol (LegendSymbol symbol)
void	setName (const QString & name)
void	setPlotRect (const QRectF & rect) Updates the series geometry to exactly cover rect .
void	setXAxis (Axis * axis)
void	setYAxis (Axis * axis)
Axis *	xAxis () const
std::optional< DataExtent >	xDataRange () const Returns the extent this series reports to its horizontal axis, or `std::nullopt` when it has none.
Axis *	yAxis () const
std::optional< DataExtent >	yDataRange () const Returns the extent this series reports to its vertical axis, or `std::nullopt` when it has none.
	~PlotSeries () override

Protected Types inherited from QAccelPlot::PlotSeries¶

See QAccelPlot::PlotSeries

Type	Name
enum	CapacityOverflow What a series draws when its records outgrow its GPU capacity.
enum	DataChange How the records changed in a data update.

Protected Attributes inherited from QAccelPlot::PlotSeries¶

See QAccelPlot::PlotSeries

Type	Name
bool	overRenderCapacity_ = `{false}` Whether the record count of the last `updateRenderCapacity()` exceeded`renderCapacity_` .
int	renderCapacity_ = `{std::numeric\_limits<int>::max()}` Records the GPU buffers hold, as of the last `updateRenderCapacity()` ; the largest`int` before the first.

Protected Functions¶

Type	Name
virtual void	onAxisRangeChanged () override Re-tests the hover position when the viewport moves under the cursor.
virtual void	onAxisScaleChanged () override Re-tests the hover position when a bound axis changes between linear and log scale.
virtual void	onDataPointsChanged (DataChange change, int previousCount) override Refreshes the X order, the hover state, and the count after the data points changed.

Protected Functions inherited from QAccelPlot::PlotSeries¶

See QAccelPlot::PlotSeries

Type	Name
	PlotSeries (DataPointStore::Layout layout, DataPointWording wording, QQuickItem * parent) Creates a series whose data points have layout _;_wording names them in warnings.
void	appendDataPoint (const double * coordinates) Appends one double data point and widens the data ranges by its valid coordinates.
virtual void	applyDataPoints (DataPointInput && input) Applies data points passed to `setData()` or`setDataF()` .
virtual DataRanges	computeDataRanges () const Scans the records for their extents. The default implementation scans the data points.
virtual int	dataPointValueCount () const Returns the number of values per data point that `setData()` and`setDataF()` take.
DataPointStore &	dataPoints () Returns the data points of the series.
const DataPointStore &	dataPoints () const Returns the data points of the series.
bool	event (QEvent * event) override Withholds hover events from a series beneath another series under the cursor.
void	extendXDataRange (qreal x) Widens the X extent to include x and notifies the bound axes.
void	extendYDataRange (qreal y) Widens the Y extent to include y . A non-finite__y leaves the extent unchanged.
virtual bool	inspectionAvailable () const Returns false while the records are ambiguous, such as during a data transition. Default: true.
void	inspectionDataChanged (DataChange change=DataChange::Replaced) Advances the data revision and refreshes the data queries. Call after every accepted record change.
virtual InspectionDataPoint	inspectionDataPointAt (const QPointF & position) const Returns the record drawn at the series-local position as a data point. Default: unsupported.
virtual InspectionRecord	inspectionRecord (int index) const Returns the native record at index for series that are not plain XY series. Default: unsupported.
virtual InspectionRecord	inspectionRecordAt (const QPointF & position) const Returns the native record drawn at the series-local position . Default: unsupported.
virtual Internal::InspectionSource	inspectionSource () const Returns a view of the XY records that data point queries search. The default has none.
void	invalidateDataRanges () Discards the cached extents and notifies the bound axes.
void	invalidateInspection () Refreshes the data queries after record validity changed without a data change, such as an axis scale switch.
bool	logScaleX () const Returns whether the horizontal axis is logarithmic; false without an axis.
bool	logScaleY () const Returns whether the vertical axis is logarithmic; false without an axis.
void	notifyDataPointsChanged (DataChange change, int previousCount) Finishes a change of the data points: data ranges, `onDataPointsChanged()` ,`countChanged()` , data queries, and a repaint.
virtual void	onAxisRangeChanged () Called when the viewport of a bound axis changes. The default implementation schedules a repaint.
virtual void	onAxisScaleChanged () Called when a bound axis switches between linear and logarithmic scale, or a different axis is bound.
virtual void	onDataPointsChanged (DataChange change, int previousCount) Called after the data points changed, before the data queries are refreshed. The default does nothing.
virtual bool	positionInspectionSupported () const Returns whether `inspectionDataPointAt()` matches records drawn as areas, such as heatmap cells. Default: false.
virtual bool	recordInspectionSupported () const Returns whether `inspectionRecord()` and`inspectionRecordAt()` answer for this series. Default: false.
QRectF	resolvePlotRect () const Returns the plot area to render into: `plotRect` when set, otherwise the item's current size.
void	setHovered (bool hovered) Sets the hovered property to hovered . Called by the hover handling of a series.
void	storeDataPoints (DataPointInput && input) Stores input as the data points and finishes the change.
void	supportHover () Makes the series accept hover events while `hoverEnabled` is`true` .
void	updateRenderCapacity (int capacity, int recordCount, CapacityOverflow overflow=CapacityOverflow::DropsExcess) Stores capacity , the number of records the GPU buffers hold, and warns when__recordCount newly exceeds it.
bool	validateDataSize (std::size_t valueCount, int count, bool floatData, int valuesPerDataPoint=0) const Returns whether valueCount values hold__count data points; warns otherwise.
bool	validateRawDataArguments (const void * data, int count) const Returns whether data and__count are valid arguments for copying data points; warns otherwise.

Detailed Description¶

Data points are stored as interleaved (x, low, high) triples and uploaded to the GPU as a float data texture once per data change; panning and zooming only change shader uniforms. Dashed edge lines are the exception: zooming recomputes their dash positions on the CPU. The setData() overloads keep doubles and upload them relative to an origin near the viewport, so large coordinates such as epoch timestamps stay precise. The setDataF() overloads store floats and upload them without conversion.

Draw a center line with a separate LineCurve. edges draws lines along the lower and upper edges of the filled band.

** **

At each data point the band spans from the smaller to the larger of low and high. X values are expected in ascending order: hovered and valueAt() work only when they are.

** **

A data point is invalid when x, low, or high is NaN or ±Inf, or is not strictly positive on a log-scale axis. The fill and the edge lines leave a gap at invalid data points. Auto-ranging skips invalid values one by one.

** **

At most 16,777,216 (2^24) data points are drawn, fewer on GPUs whose maximum texture size is below 6144. Data points beyond the limit are not drawn, and a warning is logged once.

See also: LineCurve, BandEdges

Public Properties Documentation¶

property color¶

Fill color. Default: Colors.dark.seriesPrimary with alpha 64.

QColor QAccelPlot::BandSeries::color;

property edges¶

Grouped edge line settings, e.g. edges.width andedges.lineStyle . No edge lines by default.

BandEdges* QAccelPlot::BandSeries::edges;

Public Signals Documentation¶

signal colorChanged¶

Emitted when the color property changes.

void QAccelPlot::BandSeries::colorChanged;

Public Functions Documentation¶

function BandSeries¶

Constructs a BandSeries with the given__parent .

explicit QAccelPlot::BandSeries::BandSeries (
    QQuickItem * parent=nullptr
)

function appendData¶

Appends the data point ( x _,_low _,_high ). Triggers a redraw.

Q_INVOKABLE void QAccelPlot::BandSeries::appendData (
    qreal x,
    qreal low,
    qreal high
)

function clearData¶

Removes all data points.

virtual Q_INVOKABLE void QAccelPlot::BandSeries::clearData () override

Implements QAccelPlot::PlotSeries::clearData

function color¶

Returns the fill color.

QColor QAccelPlot::BandSeries::color () const

function contains¶

Returns true when item position__point lies inside the band or on an edge line.

bool QAccelPlot::BandSeries::contains (
    const QPointF & point
) override const

Hover delivery uses this test, so stacked series underneath still receive hover events outside the band.

function edges¶

Returns the grouped edge line settings. The object is owned by the series.

BandEdges * QAccelPlot::BandSeries::edges () const

function legendEntry¶

Returns the legend entry: the symbol and color of the band.

virtual std::optional< LegendEntry > QAccelPlot::BandSeries::legendEntry () override const

Implements QAccelPlot::PlotSeries::legendEntry

function setColor¶

Sets the fill color to color .

void QAccelPlot::BandSeries::setColor (
    const QColor & color
)

function setData¶

Replaces the data points with xs _,_lows , and__highs . If the sizes differ, the shortest length is used.

Q_INVOKABLE void QAccelPlot::BandSeries::setData (
    const QList< qreal > & xs,
    const QList< qreal > & lows,
    const QList< qreal > & highs
)

function setData¶

Replaces the data points with xs _,_lows , and__highs . If the sizes differ, the shortest length is used.

void QAccelPlot::BandSeries::setData (
    const std::vector< double > & xs,
    const std::vector< double > & lows,
    const std::vector< double > & highs
)

function setData¶

Replaces the series data with count data points copied from an interleaved double array.

void QAccelPlot::BandSeries::setData (
    const double * data,
    int count
)

See the class description for the data point layout of each series.

function setData¶

Replaces the series data by moving an interleaved double buffer.

void QAccelPlot::BandSeries::setData (
    std::vector< double > && data,
    int count
)

function setData¶

Like setData _(_data _,_count ), with the data extents given as__bounds instead of scanned for.

void QAccelPlot::BandSeries::setData (
    const double * data,
    int count,
    const DataBounds & bounds
)

function setData¶

Like setData _(_data _,_count ), with the data extents given as__bounds instead of scanned for.

void QAccelPlot::BandSeries::setData (
    std::vector< double > && data,
    int count,
    const DataBounds & bounds
)

function setDataF¶

Replaces the series data with count data points copied from an interleaved float array.

void QAccelPlot::BandSeries::setDataF (
    const float * data,
    int count
)

function setDataF¶

Replaces the series data by moving an interleaved float buffer.

void QAccelPlot::BandSeries::setDataF (
    std::vector< float > && data,
    int count
)

function setDataF¶

Like setDataF _(_data _,_count ), with the data extents given as__bounds instead of scanned for.

void QAccelPlot::BandSeries::setDataF (
    const float * data,
    int count,
    const DataBounds & bounds
)

function setDataF¶

Like setDataF _(_data _,_count ), with the data extents given as__bounds instead of scanned for.

void QAccelPlot::BandSeries::setDataF (
    std::vector< float > && data,
    int count,
    const DataBounds & bounds
)

function valueAt¶

Returns the band at data coordinate x as an object withx ,low , andhigh properties.

Q_INVOKABLE QVariantMap QAccelPlot::BandSeries::valueAt (
    qreal x
) const

low and high are interpolated between the neighboring data points as drawn, with low ≤ high. At an X shared by several data points they cover all of them. Returns an empty object when x lies outside the data points, next to an invalid data point, or when the X values are not in ascending order.

Protected Functions Documentation¶

function onAxisRangeChanged¶

Re-tests the hover position when the viewport moves under the cursor.

virtual void QAccelPlot::BandSeries::onAxisRangeChanged () override

Implements QAccelPlot::PlotSeries::onAxisRangeChanged

function onAxisScaleChanged¶

Re-tests the hover position when a bound axis changes between linear and log scale.

virtual void QAccelPlot::BandSeries::onAxisScaleChanged () override

Implements QAccelPlot::PlotSeries::onAxisScaleChanged

function onDataPointsChanged¶

Refreshes the X order, the hover state, and the count after the data points changed.

virtual void QAccelPlot::BandSeries::onDataPointsChanged (
    DataChange change,
    int previousCount
) override

Implements QAccelPlot::PlotSeries::onDataPointsChanged

The documentation for this class was generated from the following file QAccelPlot/src/QAccelPlot/series/BandSeries.hpp