Class: QgsMapToolCapture

QgsMapToolCapture is a base class 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	The QgsMapToolAdvancedDigitizing class is a QgsMapTool which gives event directly in map coordinates and allows filtering its events. Events from QgsMapTool are caught and their QMouseEvent are transformed into QgsMapMouseEvent (with map coordinates). Events are then forwarded to corresponding virtual methods which can be reimplemented in subclasses. An event filter can be set on the map tool to filter and modify the events in map coordinates (:py:
QgsMapToolEdit	Base class for map tools that edit vector geometry
QgsMapTool	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.
QObject

Subclasses

QgsMapToolCaptureLayerGeometry

QgsMapToolCaptureLayerGeometry is a base class for map tools digitizing layer geometries This map tool subclass automatically handles intersection avoidance with other layers in the active project whenever a geometry is digitized by the user.

Enums

CaptureTechnique

Capture technique.

Methods

addCurve	Adds a whole curve (e.g. circularstring) to the captured geometry.
addVertex	Adds a point to the rubber band (in map coordinates) and to the capture list (in layer coordinates)
capabilities	Returns flags containing the supported capabilities
captureCurve	Gets the capture curve
clearCurve	Clear capture curve.
closePolygon	Close an open polygon
currentCaptureTechnique	Returns the active capture technique
deleteTempRubberBand	Clean a temporary rubberband
fetchLayerPoint	Fetches the original point from the source layer if it has the same CRS as the current layer.
geometryCaptured	Called when the geometry is captured.
isCapturing	Are we currently capturing?
keyPressEvent	Intercept key events like Esc or Del to delete the last point
lineCaptured	Called when a line is captured
mapPoint	Creates a QgsPoint with ZM support if necessary (according to the WkbType of the current layer).
mode	The capture mode
nextPoint	Converts a map point to layer coordinates
pointCaptured	Called when a point is captured.
points	List of digitized points
pointsZM	List of digitized points
polygonCaptured	Called when a polygon is captured.
setCircularDigitizingEnabled	Enable the digitizing with curve
setCurrentCaptureTechnique	Sets the current capture if it is supported by the map tool
setPoints	Set the points on which to work
setStreamDigitizingEnabled	Toggles the stream digitizing mode.
size	Number of points digitized
snappingMatches	Returns a list of matches for each point on the captureCurve.
startCapturing	Start capturing
stopCapturing	Stop capturing
supportsTechnique	Returns True if the tool supports the specified capture technique.
takeRubberBand	Returns the rubberBand currently owned by this map tool and transfers ownership to the caller.
undo	Removes the last vertex from mRubberBand and mCaptureList.

Attributes

CaptureLine
CaptureNone
CapturePoint
CapturePolygon
NoCapabilities
SupportsCurves
ValidateGeometries

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

Parameters:

point (QgsPointXY)

addVertex(self, mapPoint: QgsPointXY, match: QgsPointLocator.Match) → int

Variant to supply more information in the case of snapping

Parameters:

• mapPoint (QgsPointXY) – The vertex to add in map coordinates

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

Return type:

int

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)

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?

keyPressEvent(self, e: QKeyEvent | None)

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

Parameters:

e (Optional[QKeyEvent]) – key event

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

Return type:

QgsPoint

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

Return type:

int

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 (QPoint) – the input point

• layerPoint (QgsPoint) – the point in layer coordinates

• mapPoint (QgsPoint) – 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

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.

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 (Iterable[QgsPoint]) – 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

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)