Below is a brief overview of and guide to the classes and their relations. If you are new to QCustomPlot and just want to start using it, it's recommended to look at the examples/tutorials at
http://www.WorksLikeClockWork.com/index.php/components/qt-plotting-widget
This documentation is especially helpful when the basic concept of how to use QCustomPlot is clear and you wish to learn more about specific functionality.
Quick Guide
The central widget which displays the plottables and axes on its surface is QCustomPlot. Usually, you don't create the axes yourself, but you use the ones already inside every QCustomPlot instance (xAxis, yAxis, xAxis2, yAxis2).
Plottables
Plottables are classes that display any kind of data inside the QCustomPlot. They all derive from QCPAbstractPlottable. For example, the QCPGraph class is a plottable that displays a graph inside the plot 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:
You create a new graph with QCustomPlot::addGraph and access them with QCustomPlot::graph.
For all other plottables, you need to use the normal plottable interface:
First, you create an instance of the plottable you want, e.g.
add it to the customPlot with QCustomPlot::addPlottable:
and then modify the properties of the newly created plottable via newCurve.
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 dynamic_cast the returned pointer to the respective plottable subclass. (if the dynamic cast returns zero, 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.
Controlling the Axes
As mentioned, QCustomPlot has four axes by default: xAxis (bottom), yAxis (left), xAxis2 (top), yAxis2 (right).
Their range is handled by the simple QCPRange class. You can set the range with the QCPAxis::setRange function. By default, the axes represent a linear scale. To set a logarithmic scale, set QCPAxis::setScaleType to QCPAxis::STLogarithmic. The logarithm base can be set freely with QCPAxis::setScaleLogBase.
By default, an axis automatically creates and labels ticks in a sensible manner, i.e. with a tick interval that's pleasing to the viewer. See the following functions for tick manipulation:
QCPAxis::setTicks, QCPAxis::setAutoTicks, QCPAxis::setAutoTickCount, QCPAxis::setAutoTickStep, QCPAxis::setTickLabels, QCPAxis::setTickLabelType, QCPAxis::setTickLabelRotation, QCPAxis::setTickStep, QCPAxis::setTickLength,...
Each axis can be given an axis label (e.g. "Voltage [mV]") with QCPAxis::setLabel.
The distance of an axis backbone to the respective QCustomPlot widget border is called its margin. Normally, the margins are calculated automatically. To change this, set QCustomPlot::setAutoMargin to false and set the margins manually with QCustomPlot::setMargin.
Plot Legend
Every QCustomPlot owns a QCPLegend (as legend). That's a small window inside the plot which lists the plottables with an icon of the plottable line/symbol and a description. The Description is retrieved from the plottable 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 modified with the QCustomPlot::setAutoAddPlottableToLegend property.
The QCPLegend provides an interface to access, add and remove legend items directly, too. See QCPLegend::item, QCPLegend::itemWithPlottable, QCPLegend::addItem, QCPLegend::removeItem for example.
Performance Tweaks
Although QCustomPlot is quite fast, some features (transparent fills and antialiasing) cause a significant slow down. Here are some thoughts on how to increase performance:
Most performance gets lost in the drawing functions, specifically the drawing of graphs. For maximum performance, consider the following (in no particular order):
- avoid any kind of alpha (transparency), especially in fills
- avoid any kind of antialiasing, especially in graph lines (QCustomPlot::setAntialiasedElements)
- avoid repeatedly setting the complete data set with setData. Use addData instead, if most data points stay unchanged, e.g. in a running measurement.
- set the copy parameter of the setData functions to false, so only pointers get transferred.
- on X11 (linux), avoid the (slow) native drawing system, use raster by supplying "-graphicssystem raster" as command line argument or calling QApplication::setGraphicsSystem("raster") before creating the QApplication object.
- on all operating systems, use OpenGL hardware acceleration by supplying "-graphicssystem opengl" as command line argument or calling QApplication::setGraphicsSystem("opengl"). If OpenGL is available, this will slightly decrease the quality of antialiasing, but extremely increase performance especially with alpha (transparent) fills and a large QCustomPlot drawing surface. Note however, that the maximum frame rate might be constrained by the vertical sync frequency of your monitor (VSync can be disabled in the graphics card driver configuration). So for simple plots (potential framerate far above 60 frames per second), OpenGL acceleration might achieve lower frame rates than the other graphics systems, because they are not capped at the VSync frequency.
