Class: QgsMapTool

class qgis.gui.QgsMapTool

Bases: PyQt5.QtCore.QObject

Abstract base class for all map tools. Map tools are user interactive tools for manipulating the map canvas. For example map pan and zoom features are implemented as map tools.

QgsMapTool(canvas: QgsMapCanvas) Constructor takes a map canvas as a parameter.

Methods

action

Returns associated action with map tool or None if no action is associated

activate

called when set as currently active map tool

button

Returns associated button with map tool or None if no button is associated

canvas

returns pointer to the tool's map canvas

canvasDoubleClickEvent

Mouse double-click event for overriding.

canvasMoveEvent

Mouse move event for overriding.

canvasPressEvent

Mouse press event for overriding.

canvasReleaseEvent

Mouse release event for overriding.

canvasToolTipEvent

Tooltip event for overriding.

childEvent

clean

convenient method to clean members

connectNotify

customEvent

deactivate

called when map tool is being deactivated

disconnectNotify

flags

Returns the flags for the map tool.

gestureEvent

gesture event for overriding.

isActive

Returns if the current map tool active on the map canvas

isSignalConnected

keyPressEvent

Key event for overriding.

keyReleaseEvent

Key event for overriding.

layer

Returns the map layer with the matching ID, or None if no layers could be found.

populateContextMenu

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

populateContextMenuWithEvent

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

receivers

searchRadiusMM

Gets search radius in mm.

searchRadiusMU

Gets search radius in map units for given context.

sender

senderSignalIndex

setAction

Use this to associate a QAction to this maptool.

setButton

Use this to associate a button to this maptool.

setCursor

Sets a user defined cursor

setToolName

Sets the tool's name.

timerEvent

toCanvasCoordinates

Transforms a point from map coordinates to screen coordinates.

toLayerCoordinates

Transforms a point from screen coordinates to layer coordinates.

toLayerCoordinatesV2

Transforms a point from map coordinates to layer coordinates.

toMapCoordinates

Transforms a point from screen coordinates to map coordinates.

toMapCoordinatesV2

Transforms a point from layer coordinates to map coordinates (which is different in case reprojection is used).

toolName

Emit map tool changed with the old 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

messageDiscarded

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

messageEmitted

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

Attributes

AllowZoomRect

EditTool

ShowContextMenu

Transient

AllowZoomRect = 8
EditTool = 4
class Flag

Bases: int

class Flags
class Flags(Union[QgsMapTool.Flags, QgsMapTool.Flag])
class Flags(QgsMapTool.Flags)

Bases: sip.wrapper

ShowContextMenu = 16
Transient = 2
action(self) QAction

Returns associated action with map tool or None if no action is associated

Return type:

QAction

activate(self)

called when set as currently active map 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

button(self) QAbstractButton

Returns associated button with map tool or None if no button is associated

Return type:

QAbstractButton

canvas(self) QgsMapCanvas

returns pointer to the tool’s map canvas

Return type:

QgsMapCanvas

canvasDoubleClickEvent(self, e: QgsMapMouseEvent)

Mouse double-click event for overriding. Default implementation does nothing.

Parameters:

e (QgsMapMouseEvent) –

canvasMoveEvent(self, e: QgsMapMouseEvent)

Mouse move event for overriding. Default implementation does nothing.

Parameters:

e (QgsMapMouseEvent) –

canvasPressEvent(self, e: QgsMapMouseEvent)

Mouse press event for overriding. Default implementation does nothing.

Parameters:

e (QgsMapMouseEvent) –

canvasReleaseEvent(self, e: QgsMapMouseEvent)

Mouse release event for overriding. Default implementation does nothing.

Parameters:

e (QgsMapMouseEvent) –

canvasToolTipEvent(self, e: QHelpEvent) bool

Tooltip event for overriding. Default implementation does nothing. Returns whether the event was handled by the tool and should not be propagated further.

New in version 3.22.

Parameters:

e (QHelpEvent) –

Return type:

bool

childEvent(self, QChildEvent)
clean(self)

convenient method to clean members

connectNotify(self, QMetaMethod)
customEvent(self, QEvent)
deactivate(self)

called when map 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) QgsMapTool.Flags

Returns the flags for the map tool.

New in version 2.16.

Return type:

QgsMapTool.Flags

gestureEvent(self, e: QGestureEvent) bool

gesture event for overriding. Default implementation does nothing.

Parameters:

e (QGestureEvent) –

Return type:

bool

isActive(self) bool

Returns if the current map tool active on the map canvas

New in version 3.4.

Return type:

bool

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

Key event for overriding. Default implementation does nothing.

Parameters:

e (QKeyEvent) –

keyReleaseEvent(self, e: QKeyEvent)

Key event for overriding. Default implementation does nothing.

Parameters:

e (QKeyEvent) –

layer(self, id: str) QgsMapLayer

Returns the map layer with the matching ID, or None if no layers could be found.

This method searches both layers associated with the map canvas (see QgsMapCanvas.layers()) and layers from the QgsProject associated with the canvas. It can be used to resolve layer IDs to layers which may be visible in the canvas, but not associated with a QgsProject.

New in version 3.22.

Parameters:

id (str) –

Return type:

QgsMapLayer

messageDiscarded

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

messageEmitted

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

populateContextMenu(self, menu: QMenu)

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.

The default implementation does nothing.

Note

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

New in version 3.14.

Parameters:

menu (QMenu) –

populateContextMenuWithEvent(self, menu: QMenu, event: QgsMapMouseEvent) 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 map mouse event can be provided to allow particular behavior depending on the map 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().

New in version 3.18.

Parameters:
Return type:

bool

receivers(self, PYQT_SIGNAL) int
searchRadiusMM() float

Gets search radius in mm. Used by identify, tip etc. The values is currently set in identify tool options (move somewhere else?) and defaults to Qgis.DEFAULT_SEARCH_RADIUS_MM.

New in version 2.3.

Return type:

float

searchRadiusMU(context: QgsRenderContext) float

Gets search radius in map units for given context. Used by identify, tip etc. The values is calculated from searchRadiusMM().

New in version 2.3.

searchRadiusMU(canvas: QgsMapCanvas) -> float Gets search radius in map units for given canvas. Used by identify, tip etc. The values is calculated from searchRadiusMM().

New in version 2.3.

Parameters:

context (QgsRenderContext) –

Return type:

float

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

Use this to associate a QAction to this maptool. Then when the setMapTool method of mapcanvas is called the action state will be set to on. Usually this will cause e.g. a toolbutton to appear pressed in and the previously used toolbutton to pop out.

Parameters:

action (QAction) –

setButton(self, button: QAbstractButton)

Use this to associate a button to this maptool. It has the same meaning as setAction() function except it works with a button instead of an QAction.

Parameters:

button (QAbstractButton) –

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

Sets a user defined cursor

Parameters:

cursor (Union[QCursor) –

setToolName(self, name: str)

Sets the tool’s name.

See also

toolName()

New in version 3.20.

Parameters:

name (str) –

timerEvent(self, QTimerEvent)
toCanvasCoordinates(self, point: QgsPointXY) QPoint

Transforms a point from map coordinates to screen coordinates.

Parameters:

point (QgsPointXY) –

Return type:

QPoint

toLayerCoordinates(self, layer: QgsMapLayer, point: QPoint) QgsPointXY

Transforms a point from screen coordinates to layer coordinates.

toLayerCoordinates(self, layer: QgsMapLayer, point: QgsPointXY) -> QgsPointXY Transforms a point from map coordinates to layer coordinates.

toLayerCoordinates(self, layer: QgsMapLayer, rect: QgsRectangle) -> QgsRectangle Transforms a rect from map coordinates to layer coordinates.

Parameters:
Return type:

QgsPointXY

toLayerCoordinatesV2(self, layer: QgsMapLayer, point: QgsPoint) QgsPoint

Transforms a point from map coordinates to layer coordinates.

Note

This method is available in the Python bindings as toLayerCoordinatesV2.

Parameters:
Return type:

QgsPoint

toMapCoordinates(self, point: QPoint) QgsPointXY

Transforms a point from screen coordinates to map coordinates.

toMapCoordinates(self, layer: QgsMapLayer, point: QgsPointXY) -> QgsPointXY Transforms a point from layer coordinates to map coordinates (which is different in case reprojection is used).

Parameters:

point (QPoint) –

Return type:

QgsPointXY

toMapCoordinatesV2(self, layer: QgsMapLayer, point: QgsPoint) QgsPoint

Transforms a point from layer coordinates to map coordinates (which is different in case reprojection is used).

Note

This method is available in the Python bindings as toMapCoordinatesV2.

Parameters:
Return type:

QgsPoint

toolName(self) str

Emit map tool changed with the old tool

See also

setToolName()

New in version 2.3.

Return type:

str

wheelEvent(self, e: QWheelEvent)

Mouse wheel event for overriding. Default implementation does nothing.

Parameters:

e (QWheelEvent) –