QCustomPlot 2.1.1 Documentation
Author: Emanuel Eichhammer

· · · ·
QCustomPlot 2.1.1 Documentation

If you are new to QCustomPlot and just want to start using it, it's recommended to look at the tutorials and examples at

https://www.qcustomplot.com/

This documentation is especially helpful as a reference, when you're familiar with the basics of data visualization with QCustomPlot and you wish to learn more about specific functionality or more advanced concepts. See the class overview for diagrams explaining the relationships between the most important classes of the QCustomPlot library.

# Plottables

Plottables are classes that display any kind of data in QCustomPlot. They all derive from QCPAbstractPlottable. For example, QCPGraph is a plottable that displays a graph with different line styles, scatter styles, filling etc.

Since plotting graphs is such a dominant use case, QCustomPlot has a special interface for working with QCPGraph plottables, that makes it very easy to handle them:
A new graph can be created with QCustomPlot::addGraph and accessed with QCustomPlot::graph.

For all other plottables, the normal plottable interface is used: First, an instance of the respective plottable is created and added to the QCustomPlot, e.g.

QCPCurve *newCurve = new QCPCurve(customPlot->xAxis, customPlot->yAxis);

The properties of the newly created plottable can then be accessed via the newCurve pointer.

Plottables (including graphs) can be retrieved via QCustomPlot::plottable. Since the return type of that function is the abstract base class of all plottables, QCPAbstractPlottable, you will probably want to qobject_cast the returned pointer to the respective plottable subclass. As usual, the cast returns `nullptr` if the plottable wasn't of that specific subclass.

All further interfacing with plottables (e.g how to set data) is specific to the plottable type. See the documentations of the subclasses: QCPGraph, QCPCurve, QCPBars, QCPStatisticalBox, QCPColorMap, QCPFinancial.

# Controlling the Axes

QCustomPlot has four default axes: xAxis (bottom), yAxis (left), xAxis2 (top), yAxis2 (right).

Their range is handled by the simple QCPRange class which basically holds the lower and upper axis coordinate. You can set the range with the QCPAxis::setRange function. To change the axis scale type from a linear scale to a logarithmic scale, set QCPAxis::setScaleType to QCPAxis::stLogarithmic. In that case you will also want logarithmically spaced ticks and tick labels, so set the axis ticker with QCPAxis::setTicker to a QCPAxisTickerLog instance.

Each axis can be given an axis label (e.g. "Voltage (mV)") with QCPAxis::setLabel.

By default, an axis automatically creates and labels ticks in a sensible manner. See the various methods of the QCPAxis documentation for fine-tuning. Ticks can be disabled for an axis via QCPAxis::setTicks. If you only wish to hide tick labels (the numbers), use QCPAxis::setTickLabels. Note that the default right and top axes start out with hidden tick labels.

The distance of an axis backbone to the respective viewport/widget border is called its margin. Normally, the margins are calculated automatically to fit the axis and tick labels. To change this, set QCPAxisRect::setAutoMargins to exclude the respective margin sides, and set the margins manually with QCPAxisRect::setMargins. The main axis rect can be accessed with QCustomPlot::axisRect(). A detailed explanation of the different margins/paddings/offset options is given in the QCPAxisRect and QCPAxis documentation.

# Plot Legend

Every QCustomPlot has one QCPLegend (as QCustomPlot::legend) by default. A legend is a small layout element inside the plot which lists the plottables with an icon of the plottable line/symbol and a name (QCPAbstractPlottable::setName). Plottables can be added and removed from the legend via QCPAbstractPlottable::addToLegend and QCPAbstractPlottable::removeFromLegend. By default, adding a plottable to QCustomPlot automatically adds it to the legend, too. This behaviour can be changed with the QCustomPlot::setAutoAddPlottableToLegend property.

QCPLegend provides an interface to access, add and remove legend items directly, too. See QCPLegend::item, QCPLegend::itemWithPlottable, QCPLegend::addItem, QCPLegend::removeItem for example.

Multiple legends are supported via the layout system (since a QCPLegend is a normal layout element).

# User Interaction

QCustomPlot supports dragging axis ranges with the mouse (QCPAxisRect::setRangeDrag), zooming axis ranges with the mouse wheel (QCPAxisRect::setRangeZoom) and a complete selection mechanism with configurable granularity down to data points and data ranges.

The availability of these interactions is controlled with QCustomPlot::setInteractions. For details about the interaction system, see the documentation there. The data selection is discussed in detail on the dedicated Data Selection Mechanism page.

Further, QCustomPlot always emits corresponding signals, when objects are clicked or doubleClicked. See QCustomPlot::plottableClick, QCustomPlot::plottableDoubleClick and QCustomPlot::axisClick for example.

Finally on the lowest level you can work with the QCPLayerable mouse event virtual methods in own subclasses, that the QCustomPlot instance calls on the affected layerable.

# Decorations and Auxiliary Items

Apart from plottables there is another category of plot objects that are important: Items. The base class of all items is QCPAbstractItem. An item sets itself apart from plottables in that it's not necessarily bound to any axes. This means it may also be positioned in absolute pixel coordinates or placed at a relative position on an axis rect. Further, it usually doesn't represent data directly, but acts as decoration, emphasis, description etc.

Multiple items can be arranged in a parent-child-hierarchy allowing for dynamical behaviour. For example, you could place the head of an arrow at a fixed plot coordinate, so it always points to some important area in the plot. The tail of the arrow can be anchored to a text item which always resides in the top center of the axis rect, independent of where the user drags the axis ranges. This way the arrow stretches and turns so it always points from the label to the specified plot coordinate, without any further code necessary.

For a more detailed introduction, see the QCPAbstractItem documentation, and from there the documentations of the individual standard items, to find out how to use them.

# Layout Elements and Layouts

QCustomPlot uses an internal layout system to provide dynamic sizing and positioning of objects like the axis rect(s), legends, color scales, and other layout elements. They are all based on QCPLayoutElement and are arranged by placing them inside a QCPLayout subclass, like QCPLayoutGrid.

See the page about the layout system for details.

# OpenGL Accelerated Plotting and Performance Improvement

QCustomPlot has multiple OpenGL backends to provide OpenGL hardware accelerated plotting across all supported Qt versions. If the computer supports OpenGL, you can enable it by compiling with `QCUSTOMPLOT_USE_OPENGL` and simply calling setOpenGl(true) on the respective QCustomPlot instance. More details are given in the documentation of that method.

Information on maximizing plot performance for demanding visualization tasks can be found on the dedicated page about Plot Performance Improvement.

# Preprocessor Define Flags

QCustomPlot understands some preprocessor defines that are useful for debugging and compilation. The flags must be defined before including the QCustomPlot header. Usually it's best to add them to your qmake project file, using e.g. DEFINES += QCUSTOMPLOT_USE_OPENGL

`QCUSTOMPLOT_USE_OPENGL`
  If this flag is defined, QCustomPlot can use OpenGL to improve plot performance for graphically demanding plots, see QCustomPlot::setOpenGl.
`QCUSTOMPLOT_COMPILE_LIBRARY`
  Define this flag when compiling QCustomPlot as a shared library (.so/.dll)
`QCUSTOMPLOT_USE_LIBRARY`
  Define this flag before including the header, when using QCustomPlot as a shared library
`QCUSTOMPLOT_CHECK_DATA`
  If this flag is defined, the QCustomPlot plottables will perform data validity checks on every redraw. They will give qDebug output when encountering inf or nan values (also if silent NaNs are used intentionally to create gaps in graphs).

# Using QCustomPlot with special Qt flags

See the page Special Qt Flags if your project uses QT_NO_CAST_FROM_ASCII, QT_NO_CAST_TO_ASCII or QT_NO_KEYWORDS.