QgsMapTool class

Abstract base class for all map tools.

Reference

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

Derived classes

class QgsMapToolEdit: Base class for map tools that edit vector geometry.
class QgsMapToolEmitPoint: A map tool that simply emits a point when clicking on the map.
class QgsMapToolExtent: A map tool that emits an extent from a rectangle drawn onto the map canvas.
class QgsMapToolIdentify: Map tool for identifying features in layers.
class QgsMapToolPan: A map tool for panning the map.
class QgsMapToolZoom: A map tool for zooming into the map.

Public types

enum Flag { Transient = 1 << 1, EditTool = 1 << 2, AllowZoomRect = 1 << 3 }: Enumeration of flags that adjust the way the map tool operates.

Public static functions

static auto searchRadiusMM() -> double: Gets search radius in mm.
static auto searchRadiusMU(const QgsRenderContext& context) -> double: Gets search radius in map units for given context.
static auto searchRadiusMU(QgsMapCanvas* canvas) -> double: Gets search radius in map units for given canvas.

Constructors, destructors, conversion operators

QgsMapTool(QgsMapCanvas* canvas) protected: constructor takes map canvas as a parameter

Public functions

auto action() -> QAction*: Returns associated action with map tool or NULL if no action is associated.
void activate() virtual: called when set as currently active map tool
auto button() -> QAbstractButton*: Returns associated button with map tool or NULL if no button is associated.
auto canvas() -> QgsMapCanvas*: returns pointer to the tool's map canvas
void canvasDoubleClickEvent(QgsMapMouseEvent* e) virtual: Mouse double-click event for overriding. Default implementation does nothing.
void canvasMoveEvent(QgsMapMouseEvent* e) virtual: Mouse move event for overriding. Default implementation does nothing.
void canvasPressEvent(QgsMapMouseEvent* e) virtual: Mouse press event for overriding. Default implementation does nothing.
void canvasReleaseEvent(QgsMapMouseEvent* e) virtual: Mouse release event for overriding. Default implementation does nothing.
void clean() virtual: convenient method to clean members
void deactivate() virtual: called when map tool is being deactivated
auto flags() const -> Flags virtual: Returns the flags for the map tool.
auto gestureEvent(QGestureEvent* e) -> bool virtual: gesture event for overriding. Default implementation does nothing.
auto isActive() const -> bool: Returns if the current map tool active on the map canvas.
void keyPressEvent(QKeyEvent* e) virtual: Key event for overriding. Default implementation does nothing.
void keyReleaseEvent(QKeyEvent* e) virtual: Key event for overriding. Default implementation does nothing.
void setAction(QAction* action): Use this to associate a QAction to this maptool.
void setButton(QAbstractButton* button): Use this to associate a button to this maptool.
void setCursor(const QCursor& cursor) virtual: Sets a user defined cursor.
auto toolName() -> QString: Emit map tool changed with the old tool.
void wheelEvent(QWheelEvent* e) virtual: Mouse wheel event for overriding. Default implementation does nothing.

Signals

void activated(): signal emitted once the map tool is activated
void deactivated(): signal emitted once the map tool is deactivated
void messageDiscarded(): emit signal to clear previous message
void messageEmitted(const QString& message, Qgis::MessageLevel = Qgis::Info): emit a message

Protected functions

auto toCanvasCoordinates(const QgsPointXY& point) -> QPoint: transformation from map coordinates to screen coordinates
auto toLayerCoordinates(const QgsMapLayer* layer, QPoint point) -> QgsPointXY: transformation from screen coordinates to layer's coordinates
auto toLayerCoordinates(const QgsMapLayer* layer, const QgsPointXY& point) -> QgsPointXY: transformation from map coordinates to layer's coordinates
auto toLayerCoordinates(const QgsMapLayer* layer, const QgsRectangle& rect) -> QgsRectangle: trnasformation of the rect from map coordinates to layer's coordinates
auto toMapCoordinates(QPoint point) -> QgsPointXY: transformation from screen coordinates to map coordinates
auto toMapCoordinates(const QgsMapLayer* layer, const QgsPointXY& point) -> QgsPointXY: transformation from layer's coordinates to map coordinates (which is different in case reprojection is used)
auto toMapCoordinates(const QgsMapLayer* layer, const QgsPoint& point) -> QgsPoint: transformation from layer's coordinates to map coordinates (which is different in case reprojection is used)

Protected variables

QAction* mAction: optionally map tool can have pointer to action which will be used to set that action as active
QAbstractButton* mButton: optionally map tool can have pointer to a button which will be used to set that action as active
QgsMapCanvas* mCanvas: pointer to map canvas
QCursor mCursor: cursor used in map tool
QString mToolName: translated name of the map tool

Enum documentation

enum QgsMapTool::Flag

Enumeration of flags that adjust the way the map tool operates.

Enumerators
Transient	Indicates that this map tool performs a transient (one-off) operation. If it does, the tool can be operated once and then a previous map tool automatically restored.
EditTool	Map tool is an edit tool, which can only be used when layer is editable.
AllowZoomRect	Allow zooming by rectangle (by holding shift and dragging) while the tool is active.

Function documentation

static double QgsMapTool::searchRadiusMM()

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.

static double QgsMapTool::searchRadiusMU(const QgsRenderContext& context)

Gets search radius in map units for given context.

Used by identify, tip etc. The values is calculated from searchRadiusMM().

static double QgsMapTool::searchRadiusMU(QgsMapCanvas* canvas)

Gets search radius in map units for given canvas.

Used by identify, tip etc. The values is calculated from searchRadiusMM().

Flags QgsMapTool::flags() const virtual

Returns the flags for the map tool.

bool QgsMapTool::isActive() const

Returns if the current map tool active on the map canvas.

void QgsMapTool::setAction(QAction* action)

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.

void QgsMapTool::setButton(QAbstractButton* button)

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.

QString QgsMapTool::toolName()

Emit map tool changed with the old tool.

QgsPoint QgsMapTool::toMapCoordinates(const QgsMapLayer* layer, const QgsPoint& point) protected

transformation from layer's coordinates to map coordinates (which is different in case reprojection is used)