User interactions

QCustomPlot offers multiple built-in user interactions. They can be roughly categorized as

  • Range manipulation by dragging with the mouse and scrolling the mouse wheel
  • Selection of plot entities by clicking
  • Signals emitted upon clicks of the user on plot entities

Range Manipulation

The default method for the user to manipulate the axis range is by performing a drag operation on the respective QCPAxisRect.

To enable range dragging in a QCustomPlot widget, the flag QCP::iRangeDrag needs to be added to the currently allowed interactions. This can be done with customPlot->setInteraction(QCP::iRangeDrag, true). To only allow dragging in one orientation, use QCPAxisRect::setRangeDrag and specify Qt::Vertical or Qt::Horizontal. The default ist to allow both directions with Qt::Vertical | Qt::Horizontal.

During the drag operation, the axes configured via QCPAxisRect::setRangeDragAxes update their ranges in realtime, automatically causing replots. This gives the user the impression of moving the plot coordinate plane by grabbing it with the mouse. Initially, the range drag axes are configured to be the rect's bottom and left axes. For the default axis rect of the QCustomPlot widget, those are QCustomPlot::xAxis and QCustomPlot::yAxis.

To change the size of the range, i.e. zoom in or out of the plot, the user may use the mouse wheel. This behaviour is controlled with the interaction flag QCP::iRangeZoom which also needs to be activated with QCustomPlot::setInteraction. Just like the range drag, the zoom may also be selective with respect to the affected axes and orientations, see the functions QCPAxisRect::setRangeZoomAxes and QCPAxisRect::setRangeZoom. Additionally the scaling strength can be controlled with QCPAxisRect::setRangeZoomFactor. On common mouse hardware, one mouse wheel step corresponds to this factor applied to the axis range. If the factor is greater than one, scrolling the mouse wheel forwards decreases the range (zooms in) and scrolling backwards increases it (zooms out). To invert this behaviour, set mouse wheel zoom factors smaller than one (but greater zero). The scaling is always centered around the current mouse cursor position in the plot. This means pointing the cursor on a feature of interest and scrolling the mouse wheel allows zooming into that feature.

The selection mechanism

QCustomPlot offers a selection mechanism that allows the user to select potentially every component in the plot, like axes and graphs. Whether a certain category of entities is generally selectable in the plot can be controlled with the interaction flags that start with QCP::iSelect(...). For example, setting customPlot->setInteraction(QCP::iSelectPlottables, true) will allow the user to select plottables (e.g. graphs) by clicking on them. Have a look at the QCP::Interaction documentation for all interaction flags.

To allow multiple objects to be selected simultaneously, set the QCP::iMultiSelect interaction flag. The user may then select multiple objects in succession by holding the multi-select-modifier (see QCustomPlot::setMultiSelectModifier), which is Ctrl by default.

Controlling individual selectability and selection state

The selectability can further be fine-tuned with setSelectable functions on individual objects. For example, if a specific graph in the plot shall not be selectable by the user, call thatGraph->setSelectable(false). The selected state can be modified programmatically via setSelected functions. Changing the selection state programmatically is possible even if the selectability for the user is disabled.

To deselect all objects in the plot, call QCustomPlot::deselectAll.

Appearance of selected objects

A selected object is usually displayed with a different pen, brush or font. This can be configured with methods like QCPGraph::setSelectedPen, QCPGraph::setSelectedBrush, QCPAxis::setSelectedLabelFont, QCPAxis::setSelectedBasePen, QCPItemText::setSelectedColor, just to name a few. As can be seen, they are named like the original (non-selected) property, but with the prefix "Selected".

Multi-Part objects

Some objects such as axes and legends have a more complex appearance such that a single boolean for selection isn't sufficient. In those cases, both selectability and selection state is an or-combination of SelectablePart flags (the respective QFlags type is called SelectableParts). Each multi-part object defines its own SelectablePart type.

For example, QCPAxis is conceptually made of three parts: the axis backbone with tick marks, the tick labels (numbers), and the axis label. And since those three parts shall be selectable individually, QCPAxis::SelectablePart defines QCPAxis::spNone, QCPAxis::spAxis, QCPAxis::spTickLabels, and QCPAxis::spAxisLabel. To make the axis backbone and the tick labels selectable, but not the axis label, call theAxis->setSelectableParts(QCPAxis::spAxis|QCP::spTickLabels). To control the current selection state of a multi-part object, use the QCPAxis::setSelectedParts method.

Reacting to a selection change

Upon a selection change, each object emits a signal called selectionChanged. It does not matter whether the change was caused by the user or programmatically by a call of setSelected/setSelectedParts.

If a selection in the plot is changed by user interaction, the QCustomPlot-wide signal QCustomPlot::selectionChangedByUser is emitted. In slots connected to this signal, you may check the selection state of certain objects and react accordingly. The methods QCustomPlot::selectedPlottables, selectedItems, selectedAxes, and selectedLegends may be useful here to retrieve the selected objects of a certain kind.

User interaction signals

Independent of the selection mechanism, QCustomPlot emits various signals upon user interaction. The most low-level ones are the QCustomPlot::mouseDoubleClick, mousePress, mouseMove, mouseRelease, and mouseWheel signals. They are emitted when the corresponding event of the QCustomPlot widget fires. Note that the cleanest way would be to subclass QCustomPlot and reimplement the event methods (inherited from QWidget) with the same names. However, these signals allow easier access to user interactions for simple tasks, if you don't want to subclass QCustomPlot.

There also are higher level signals that report clicks and doubleclicks of certain objects in the plot: QCustomPlot::plottableClick, plottableDoubleClick, itemClick, itemDoubleClick, axisClick, axisDoubleClick, legendClick, legendDoubleClick, titleClick, and titleDoubleClick. All those signals report which object was clicked (and which part, if it's a multi-part object), as well as the associated QMouseEvent.

The examples in the full package include one project which makes extensive use of various aspects of the interaction system. It also demonstrates how to fine-tune the behaviour to fit ones needs.