Class: QgsMapToolCapture

Base class for map tools capable of capturing point, lines and polygons.

The tool supports different techniques: straight segments, curves, streaming and shapes Once the the geometry is captured the virtual private handler geometryCaptured is called as well as a more specific handler (pointCaptured, lineCaptured or polygonCaptured)

Class Hierarchy

Base classes

QgsMapToolAdvancedDigitizing	A QgsMapTool which gives events directly in map coordinates and allows filtering of events.
QgsMapToolEdit	Base class for map tools that edit vector geometry.
QgsMapTool	Abstract base class for all map tools.
QObject

Subclasses

QgsMapToolCaptureLayerGeometry

Base class for map tools digitizing layer geometries.

class qgis.gui.QgsMapToolCapture

Bases: QgsMapToolAdvancedDigitizing

__init__(canvas: QgsMapCanvas | None, cadDockWidget: QgsAdvancedDigitizingDockWidget | None, mode: QgsMapToolCapture.CaptureMode)

constructor

Parameters:

• canvas (Optional[QgsMapCanvas])

• cadDockWidget (Optional[QgsAdvancedDigitizingDockWidget])

• mode (QgsMapToolCapture.CaptureMode)

class Capabilities

class Capabilities(f: QgsMapToolCapture.Capabilities | QgsMapToolCapture.Capability)

class Capabilities(a0: QgsMapToolCapture.Capabilities)

Bases: object

class Capability

Bases: int

CaptureLine = 2

class CaptureMode

Bases: int

CaptureNone = 0

CapturePoint = 1

CapturePolygon = 3

class CaptureTechnique(*values)

Bases: IntEnum

Capture technique.

Added in version 3.26.

• StraightSegments: Default capture mode - capture occurs with straight line segments

• CircularString: Capture in circular strings

• Streaming: Streaming points digitizing mode (points are automatically added as the mouse cursor moves).

• Shape: Digitize shapes.

NoCapabilities = 1

SupportsCurves = 2

ValidateGeometries = 4

addCurve(self, c: QgsCurve | None) → int

Adds a whole curve (e.g. circularstring) to the captured geometry. Curve must be in map CRS

Parameters:

c (Optional[QgsCurve])

Return type:

int

addVertex(self, point: QgsPointXY) → int

Adds a point to the rubber band (in map coordinates) and to the capture list (in layer coordinates)

Return type:

int

Returns:

0 in case of success, 2 if coordinate transformation failed

addVertex(self, mapPoint: QgsPointXY, match: QgsPointLocator.Match) -> int Variant to supply more information in the case of snapping

Parameters:

• mapPoint – The vertex to add in map coordinates

• match – Data about the snapping match. Can be an invalid match, if point not snapped.

• point (QgsPointXY)

virtual capabilities(self) → QgsMapToolCapture.Capabilities

Returns flags containing the supported capabilities

Return type:

QgsMapToolCapture.Capabilities

captureCurve(self) → QgsCompoundCurve | None

Gets the capture curve

Return type:

Optional[QgsCompoundCurve]

Returns:

Capture curve

clearCurve(self)

Clear capture curve.

closePolygon(self)

Close an open polygon

currentCaptureTechnique(self) → Qgis.CaptureTechnique

Returns the active capture technique

Added in version 3.32.

Return type:

Qgis.CaptureTechnique

deleteTempRubberBand(self)

Clean a temporary rubberband

fetchLayerPoint(self, match: QgsPointLocator.Match, layerPoint: QgsPoint) → int

Fetches the original point from the source layer if it has the same CRS as the current layer. If topological editing is activated, the points are projected to the current layer CRS.

Return type:

int

Returns:

0 in case of success 1 if not applicable (CRS mismatch / invalid layer) 2 in case of failure

Parameters:

• match (QgsPointLocator.Match)

• layerPoint (QgsPoint)

virtual geometryCaptured(self, geometry: QgsGeometry)

Called when the geometry is captured.

A more specific handler is also called afterwards (pointCaptured(), lineCaptured() or polygonCaptured()).

Added in version 3.26.

Parameters:

geometry (QgsGeometry)

isCapturing(self) → bool

Are we currently capturing?

Return type:

bool

Returns:

Is the tool in capture mode?

virtual keyPressEvent(self, e: QKeyEvent | None)

Intercept key events like Esc or Del to delete the last point

Parameters:

e (Optional[QKeyEvent]) – key event

virtual lineCaptured(self, line: QgsCurve | None)

Called when a line is captured

The generic geometryCaptured() method will be called immediately before this line-specific method.

Added in version 3.26.

Parameters:

line (Optional[QgsCurve])

mapPoint(self, e: QgsMapMouseEvent) → QgsPoint

Creates a QgsPoint with ZM support if necessary (according to the WkbType of the current layer). If the point is snapped, then the Z value is derived from the snapped point.

Parameters:

e (QgsMapMouseEvent) – A mouse event

Returns:

a point with ZM support if necessary

mapPoint(self, point: QgsPointXY) -> QgsPoint Creates a QgsPoint with ZM support if necessary (according to the WkbType of the current layer).

Parameters:

point – A point in 2D

Return type:

QgsPoint

Returns:

a point with ZM support if necessary

mode(self) → QgsMapToolCapture.CaptureMode

The capture mode

Return type:

QgsMapToolCapture.CaptureMode

Returns:

Capture mode

nextPoint(self, mapPoint: QgsPoint, layerPoint: QgsPoint) → int

Converts a map point to layer coordinates

Parameters:

• mapPoint (QgsPoint) – the point in map coordinates

• layerPoint (QgsPoint) – the point in layer coordinates

Returns:

0 in case of success 1 if the current layer is None 2 if the transformation failed

nextPoint(self, p: QPoint, layerPoint: QgsPoint, mapPoint: QgsPoint) -> int Converts a point to map coordinates and layer coordinates

Parameters:

• p – the input point

• layerPoint – the point in layer coordinates

• mapPoint – the point in map coordinates

Return type:

int

Returns:

0 in case of success 1 if the current layer is None or not a vector layer 2 if the transformation failed

virtual pointCaptured(self, point: QgsPoint)

Called when a point is captured.

The generic geometryCaptured() method will be called immediately before this point-specific method.

Added in version 3.26.

Parameters:

point (QgsPoint)

points(self) → List[QgsPointXY]

List of digitized points

Return type:

List[QgsPointXY]

Returns:

List of points

Deprecated since version 3.12: Will be removed in QGIS 4.0. Use the variant returns QgsPoint objects instead of QgsPointXY.

pointsZM(self) → List[QgsPoint]

List of digitized points

Return type:

List[QgsPoint]

Returns:

List of points

Added in version 3.12.

virtual polygonCaptured(self, polygon: QgsCurvePolygon | None)

Called when a polygon is captured.

The generic geometryCaptured() method will be called immediately before this polygon-specific method.

Added in version 3.26.

Parameters:

polygon (Optional[QgsCurvePolygon])

setCircularDigitizingEnabled(self, enable: bool)

Enable the digitizing with curve

Deprecated since version 3.26: Use setCurrentCaptureTechnique() instead.

Parameters:

enable (bool)

setCurrentCaptureTechnique(self, technique: Qgis.CaptureTechnique)

Sets the current capture if it is supported by the map tool

Added in version 3.26.

Parameters:

technique (Qgis.CaptureTechnique)

setPoints(self, pointList: Iterable[QgsPointXY])

Set the points on which to work

Parameters:

pointList (Iterable[QgsPointXY]) – A list of points

Deprecated since version 3.12: Will be removed in QGIS 4.0. Use the variant which accepts QgsPoint objects instead of QgsPointXY.

setPoints(self, pointList: Iterable[QgsPoint]) Set the points on which to work

Parameters:

pointList – A list of points

Added in version 3.12.

setStreamDigitizingEnabled(self, enable: bool)

Toggles the stream digitizing mode.

Added in version 3.20.

Deprecated since version 3.26: Use setCurrentCaptureTechnique() instead.

Parameters:

enable (bool)

size(self) → int

Number of points digitized

Return type:

int

Returns:

Number of points

snappingMatches(self) → List[QgsPointLocator.Match]

Returns a list of matches for each point on the captureCurve.

Return type:

List[QgsPointLocator.Match]

startCapturing(self)

Start capturing

stopCapturing(self)

Stop capturing

virtual supportsTechnique(self, technique: Qgis.CaptureTechnique) → bool

Returns True if the tool supports the specified capture technique.

Added in version 3.20.

Parameters:

technique (Qgis.CaptureTechnique)

Return type:

bool

takeRubberBand(self) → QgsRubberBand | None

Returns the rubberBand currently owned by this map tool and transfers ownership to the caller.

May be None.

Added in version 3.8.

Return type:

Optional[QgsRubberBand]

undo(self, isAutoRepeat: bool = False)

Removes the last vertex from mRubberBand and mCaptureList.

Since QGIS 3.20, if isAutoRepeat is set to True then the undo operation will be treated as a auto repeated undo as if the user has held down the undo key for an extended period of time.

Parameters:

isAutoRepeat (bool = False)