Class: QgsPlotTool

Abstract base class for all interactive plot tools.

Plot tools are user tools for manipulating and interacting with a QgsPlotCanvas.

Added in version 3.26.

Class Hierarchy

Base classes

QObject

Subclasses

QgsPlotToolPan	Plot tool for panning/zoom/navigating plots.
QgsPlotToolTemporaryKeyPan	Plot tool for temporarily panning a plot while a key is depressed.
QgsPlotToolZoom	Plot tool for zooming into and out of the plot.
QgsPlotToolTemporaryMousePan	Plot tool for temporarily panning a plot while a mouse button is depressed.

Methods

action	Returns the action associated with the tool or None if no action is associated.
canvas	Returns the tool's plot canvas.
isActive	Returns True if this tool is the current tool active on the plot canvas.
isClickAndDrag	Returns True if a mouse press/release operation which started at startViewPoint and ended at endViewPoint should be considered a "click and drag".
setAction	Associates an action with this tool.
setCursor	Sets a user defined cursor for use when the tool is active.
toCanvasCoordinates	Converts a point in map coordinates to the associated canvas point.
toMapCoordinates	Converts a point on the canvas to the associated map coordinate.
toolName	Returns a user-visible, translated name for the tool.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsPlotTool. See the FAQ for more details.

activate	Called when the tool is set as the currently active plot tool.
canvasToolTipEvent	Tooltip event for overriding.
deactivate	Called when the tool is being deactivated.
flags	Returns the flags for the plot tool.
gestureEvent	Gesture event for overriding.
keyPressEvent	Key press event for overriding.
keyReleaseEvent	Key release event for overriding.
plotDoubleClickEvent	Mouse double-click event for overriding.
plotMoveEvent	Mouse move event for overriding.
plotPressEvent	Mouse press event for overriding.
plotReleaseEvent	Mouse release event for overriding.
populateContextMenuWithEvent	Allows the tool to populate and customize the given menu, prior to showing it in response to a right-mouse button click.
wheelEvent	Mouse wheel event for overriding.

Static Methods

constrainPointToRect

Constrains a point to force it to fall within the specified rectangle.

Signals

activated	Emitted when the tool is activated.
deactivated	Emitted when the tool is deactivated

class qgis.gui.QgsPlotTool

Bases: QObject

__init__(canvas: QgsPlotCanvas | None, name: str | None)

Constructor takes a plot canvas as a parameter.

Parameters:

• canvas (Optional[QgsPlotCanvas])

• name (Optional[str])

action(self) → QAction | None

Returns the action associated with the tool or None if no action is associated.

See also

setAction()

Return type:

Optional[QAction]

virtual activate(self)

Called when the tool is set as the currently active plot tool.

signal activated

Emitted when the tool is activated.

canvas(self) → QgsPlotCanvas | None

Returns the tool’s plot canvas.

Return type:

Optional[QgsPlotCanvas]

virtual canvasToolTipEvent(self, event: QHelpEvent | None) → bool

Tooltip event for overriding.

Returns True if the event was handled by the tool and should not be propagated further.

Parameters:

event (Optional[QHelpEvent])

Return type:

bool

static constrainPointToRect(point: QPointF | QPoint, rect: QRectF) → QPointF

Constrains a point to force it to fall within the specified rectangle.

Parameters:

• point (Union[QPointF, QPoint])

• rect (QRectF)

Return type:

QPointF

virtual deactivate(self)

Called when the tool is being deactivated.

signal deactivated

Emitted when the tool is deactivated

virtual flags(self) → Qgis.PlotToolFlags

Returns the flags for the plot tool.

Return type:

Qgis.PlotToolFlags

virtual gestureEvent(self, event: QGestureEvent | None) → bool

Gesture event for overriding.

Returns True if the event was handled by the tool and should not be propagated further.

Parameters:

event (Optional[QGestureEvent])

Return type:

bool

isActive(self) → bool

Returns True if this tool is the current tool active on the plot canvas.

Return type:

bool

isClickAndDrag(self, startViewPoint: QPoint, endViewPoint: QPoint) → bool

Returns True if a mouse press/release operation which started at startViewPoint and ended at endViewPoint should be considered a “click and drag”. If False is returned, the operation should be instead treated as just a click on startViewPoint.

Parameters:

• startViewPoint (QPoint)

• endViewPoint (QPoint)

Return type:

bool

virtual keyPressEvent(self, event: QKeyEvent | None)

Key press event for overriding.

The default implementation does nothing. When subclasses implement this method and have acted on the event, they must explicitly call event->:py:func:~QgsPlotTool.accept to prevent the event from being passed on to other widgets.

Parameters:

event (Optional[QKeyEvent])

virtual keyReleaseEvent(self, event: QKeyEvent | None)

Key release event for overriding.

The default implementation does nothing. When subclasses implement this method and have acted on the event, they must explicitly call event->:py:func:~QgsPlotTool.accept to prevent the event from being passed on to other widgets.

Parameters:

event (Optional[QKeyEvent])

virtual plotDoubleClickEvent(self, event: QgsPlotMouseEvent | None)

Mouse double-click event for overriding.

The default implementation does nothing. When subclasses implement this method and have acted on the event, they must explicitly call event->:py:func:~QgsPlotTool.accept to prevent the event from being passed on to other widgets.

Parameters:

event (Optional[QgsPlotMouseEvent])

virtual plotMoveEvent(self, event: QgsPlotMouseEvent | None)

Mouse move event for overriding.

The default implementation does nothing. When subclasses implement this method and have acted on the event, they must explicitly call event->:py:func:~QgsPlotTool.accept to prevent the event from being passed on to other widgets.

Parameters:

event (Optional[QgsPlotMouseEvent])

virtual plotPressEvent(self, event: QgsPlotMouseEvent | None)

Mouse press event for overriding.

The default implementation does nothing. When subclasses implement this method and have acted on the event, they must explicitly call event->:py:func:~QgsPlotTool.accept to prevent the event from being passed on to other widgets.

Parameters:

event (Optional[QgsPlotMouseEvent])

virtual plotReleaseEvent(self, event: QgsPlotMouseEvent | None)

Mouse release event for overriding.

The default implementation does nothing. When subclasses implement this method and have acted on the event, they must explicitly call event->:py:func:~QgsPlotTool.accept to prevent the event from being passed on to other widgets.

Parameters:

event (Optional[QgsPlotMouseEvent])

virtual populateContextMenuWithEvent(self, menu: QMenu | None, event: QgsPlotMouseEvent | None) → bool

Allows the tool to populate and customize the given menu, prior to showing it in response to a right-mouse button click.

menu will be initially populated with a set of default, generic actions. Any new actions added to the menu should be correctly parented to menu.

A pointer to the plot mouse event can be provided to allow particular behavior depending on the plot tool.

This method can return True to inform the caller that the menu was effectively populated.

The default implementation does nothing and returns False.

Note

The context menu is only shown when the ShowContextMenu flag is present in flags().

Parameters:

• menu (Optional[QMenu])

• event (Optional[QgsPlotMouseEvent])

Return type:

bool

setAction(self, action: QAction | None)

Associates an action with this tool. When the setTool method of QgsPlotCanvas is called the action’s state will be set to on. Usually this will cause a toolbutton to appear pressed in and the previously used toolbutton to pop out.

See also

action()

Parameters:

action (Optional[QAction])

setCursor(self, cursor: QCursor | Qt.CursorShape)

Sets a user defined cursor for use when the tool is active.

Parameters:

cursor (Union[QCursor, Qt.CursorShape])

toCanvasCoordinates(self, point: QgsPoint) → QgsPointXY

Converts a point in map coordinates to the associated canvas point.

May return an empty point if the map point cannot be converted to a canvas point.

Parameters:

point (QgsPoint)

Return type:

QgsPointXY

toMapCoordinates(self, point: QgsPointXY) → QgsPoint

Converts a point on the canvas to the associated map coordinate.

May return an empty point if the canvas point cannot be converted to a map point.

Parameters:

point (QgsPointXY)

Return type:

QgsPoint

toolName(self) → str

Returns a user-visible, translated name for the tool.

Return type:

str

virtual wheelEvent(self, event: QWheelEvent | None)

Mouse wheel event for overriding.

The default implementation does nothing. When subclasses implement this method and have acted on the event, they must explicitly call event->:py:func:~QgsPlotTool.accept to prevent the event from being passed on to other widgets.

Parameters:

event (Optional[QWheelEvent])