Items: Supplementary graphical elements

QCustomPlot allows placing and anchoring of graphical elements such as text, arrows, lines, rectangles, arbitrary pixmaps etc. on the plot. They are based on the abstract base class QCPAbstractItem. A detailed description of the item mechanism and what built-in items are currently available can be found in the documentation of QCPAbstractItem.

Basic example using arrow and text

This example shows how to create a text label that is always positioned at the top of the axis rect and an arrow that connects a point in plot coordinates with that label.

  // add the text label at the top:
  QCPItemText *textLabel = new QCPItemText(customPlot);
  textLabel->setPositionAlignment(Qt::AlignTop|Qt::AlignHCenter);
  textLabel->position->setType(QCPItemPosition::ptAxisRectRatio);
  textLabel->position->setCoords(0.5, 0); // place position at center/top of axis rect
  textLabel->setText("Text Item Demo");
  textLabel->setFont(QFont(font().family(), 16)); // make font a bit larger
  textLabel->setPen(QPen(Qt::black)); // show black border around text
  
  // add the arrow:
  QCPItemLine *arrow = new QCPItemLine(customPlot);
  arrow->start->setParentAnchor(textLabel->bottom);
  arrow->end->setCoords(4, 1.6); // point to (4, 1.6) in x-y-plot coordinates
  arrow->setHead(QCPLineEnding::esSpikeArrow);

Notice that even when the plot range is dragged, the arrow head stays attached to the plot coordinate (4, 1.6) and rotates/stretches accordingly. This is achieved by the flexibility of QCustomPlot's item positioning. Items may be positioned in plot coordinates, in absolute pixel coordinates and in fractional units of the axis rect size. The documentation of QCPAbstractItem and QCPItemPosition goes into more detail about how to use these different possibilities.

As with plottables, it is easy to create own items, too. This can be done by making your own subclass of QCPAbstractItem. See the subclassing section in the documentation of QCPAbstractItem.

Item clipping

Items are by default clipped to the main axis rect, this means they are only visible inside the axis rect. To make an item visible outside that axis rect, disable clipping by calling setClipToAxisRect(false).

On the other hand if you want the item to be clipped to a different axis rect, you can specify it via setClipAxisRect. This clipAxisRect property of an item is only used for clipping behaviour, and in principle is independent of the coordinate axes the item might be tied to via its position members (see QCPItemPosition::setAxes). However, it is common that the axis rect for clipping also contains the axes used for the item positions.

More advanced item usage

For a more advanced and real-world demonstration of what can be achieved with QCustomPlot's item system, have a look at the Special Use Cases tutorial Dynamic axis tags with items.