QCustomPlot offers multiple built-in user interactions. They can be roughly categorized as
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::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
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::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.
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.
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
A selected object is usually displayed with a different pen, brush or font. This can be configured with methods like
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".
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
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::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
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
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
selectedLegends may be useful here to retrieve the selected objects of a certain kind.
Independent of the selection mechanism, QCustomPlot emits various signals upon user interaction. The most low-level ones are the
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:
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.