Main Page · Class Overview · Hierarchy · All Classes
QCustomPlot Documentation

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 tutorials and examples at

This documentation is especially helpful as a reference, when you're familiar with the basic concept of how to use QCustomPlot and you wish to learn more about specific functionality.

Simplified Class Overview

Simplified diagram of most important classes, view the Class Overview to see a full overview.

The central widget which displays the plottables and axes on its surface is QCustomPlot. Every QCustomPlot contains four axes by default. They can be accessed via the members xAxis, yAxis, xAxis2 and yAxis2, and are of type QCPAxis. QCustomPlot supports an arbitrary number of axes and axis rects, see the documentation of QCPAxisRect for details.


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.

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

add it to the customPlot:


and then modify the properties of the newly created plottable 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, if the 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. 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 viewport border is called its margin. Normally, the margins are calculated automatically. To change this, set QCPAxisRect::setAutoMargins to exclude the respective margin sides, set the margins manually with QCPAxisRect::setMargins. The main axis rect can be reached with QCustomPlot::axisRect().

Plot Legend

Every QCustomPlot owns one QCPLegend (as 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 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.

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

User Interactions

QCustomPlot supports dragging axis ranges with the mouse (QCPAxisRect::setRangeDrag), zooming axis ranges with the mouse wheel (QCPAxisRect::setRangeZoom) and a complete selection mechanism.

The availability of these interactions is controlled with QCustomPlot::setInteractions. For details about the interaction system, see the documentation there.

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


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 built-in 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 and the plot title. They are all based on QCPLayoutElement and are arranged by placing them inside a QCPLayout.

Details on this topic are given on the dedicated page about the layout system.

Performance Tweaks

Although QCustomPlot is quite fast, some features like translucent fills, antialiasing and thick lines can cause a significant slow down. If you notice this in your application, here are some thoughts on how to increase performance. By far the most time is spent in the drawing functions, specifically the drawing of graphs. For maximum performance, consider the following (most recommended/effective measures first):

Preprocessor Define Flags

QCustomPlot understands some preprocessor defines that are useful for debugging and compilation:

Define this flag when you compile QCustomPlot as a shared library (.so/.dll)
Define this flag before including the header, when using QCustomPlot as a shared library
If this flag is defined, the QCustomPlot plottables will perform data validity checks on every redraw. This means they will give qDebug output when you plot inf or nan values, they will not fix your data.