Class: QgsPlotTool

class qgis.gui.QgsPlotTool

Bases: PyQt5.QtCore.QObject

Abstract base class for all interactive plot tools.

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

New in version 3.26.

QgsPlotTool(canvas: QgsPlotCanvas, name: str) Constructor takes a plot canvas as a parameter.

Methods

action

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

activate

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

canvas

Returns the tool's plot canvas.

canvasToolTipEvent

Tooltip event for overriding.

childEvent

connectNotify

constrainPointToRect

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

customEvent

deactivate

Called when the tool is being deactivated.

disconnectNotify

flags

Returns the flags for the plot tool.

gestureEvent

Gesture event for overriding.

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".

isSignalConnected

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.

receivers

sender

senderSignalIndex

setAction

Associates an action with this tool.

setCursor

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

timerEvent

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.

wheelEvent

Mouse wheel event for overriding.

Signals

activated

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

deactivated

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

action(self) QAction

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

See also

setAction()

Return type:

QAction

activate(self)

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

activated

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

canvas(self) QgsPlotCanvas

Returns the tool’s plot canvas.

Return type:

QgsPlotCanvas

canvasToolTipEvent(self, event: QHelpEvent) bool

Tooltip event for overriding.

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

Parameters:

event (QHelpEvent) –

Return type:

bool

childEvent(self, QChildEvent)
connectNotify(self, QMetaMethod)
constrainPointToRect(point: QPointF | QPoint, rect: QRectF) QPointF

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

Parameters:
  • point (Union[QPointF) –

  • rect (QRectF) –

Return type:

QPointF

customEvent(self, QEvent)
deactivate(self)

Called when the tool is being deactivated.

deactivated

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

disconnectNotify(self, QMetaMethod)
flags(self) Qgis.PlotToolFlags

Returns the flags for the plot tool.

Return type:

Qgis.PlotToolFlags

gestureEvent(self, event: QGestureEvent) bool

Gesture event for overriding.

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

Parameters:

event (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

isSignalConnected(self, QMetaMethod) bool
keyPressEvent(self, event: QKeyEvent)

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 (QKeyEvent) –

keyReleaseEvent(self, event: QKeyEvent)

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 (QKeyEvent) –

plotDoubleClickEvent(self, event: QgsPlotMouseEvent)

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 (QgsPlotMouseEvent) –

plotMoveEvent(self, event: QgsPlotMouseEvent)

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 (QgsPlotMouseEvent) –

plotPressEvent(self, event: QgsPlotMouseEvent)

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 (QgsPlotMouseEvent) –

plotReleaseEvent(self, event: QgsPlotMouseEvent)

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 (QgsPlotMouseEvent) –

populateContextMenuWithEvent(self, menu: QMenu, event: QgsPlotMouseEvent) 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:
Return type:

bool

receivers(self, PYQT_SIGNAL) int
sender(self) QObject
senderSignalIndex(self) int
setAction(self, action: QAction)

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 (QAction) –

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

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

Parameters:

cursor (Union[QCursor) –

timerEvent(self, QTimerEvent)
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

wheelEvent(self, event: QWheelEvent)

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 (QWheelEvent) –