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.

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)
`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.
`isCapturing`	Are we currently capturing?
`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
`points`	List of digitized points
`pointsZM`	List of digitized points
`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
`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.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsMapToolCapture. See the FAQ for more details.

`capabilities`	Returns flags containing the supported capabilities
`geometryCaptured`	Called when the geometry is captured.
`keyPressEvent`	Intercept key events like Esc or Del to delete the last point
`lineCaptured`	Called when a line is captured
`pointCaptured`	Called when a point is captured.
`polygonCaptured`	Called when a polygon is captured.
`supportsTechnique`	Returns `True` if the tool supports the specified capture technique.

Attributes

`CaptureLine`
`CaptureNone`
`CapturePoint`
`CapturePolygon`
`NoCapabilities`
`SupportsCurves`
`ValidateGeometries`

class qgis.gui.QgsMapToolCapture[source]¶

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[source]¶

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[source]¶

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[source]

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

virtual capabilities(self) → QgsMapToolCapture.Capabilities[source]¶

Returns flags containing the supported capabilities

Return type:: QgsMapToolCapture.Capabilities

captureCurve(self) → QgsCompoundCurve | None[source]¶

Gets the capture curve

Return type:: Optional[QgsCompoundCurve]
Returns:: Capture curve

clearCurve(self)[source]¶: Clear capture curve.

closePolygon(self)[source]¶: Close an open polygon

currentCaptureTechnique(self) → Qgis.CaptureTechnique[source]¶

Returns the active capture technique

Added in version 3.32.

Return type:: Qgis.CaptureTechnique

deleteTempRubberBand(self)[source]¶: Clean a temporary rubberband

fetchLayerPoint(self, match: QgsPointLocator.Match, layerPoint: QgsPoint) → int[source]¶

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)[source]¶

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[source]¶

Are we currently capturing?

Return type:: bool
Returns:: Is the tool in capture mode?

virtual keyPressEvent(self, e: QKeyEvent | None)[source]¶

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

Parameters:: e (Optional[QKeyEvent]) – key event

virtual lineCaptured(self, line: QgsCurve | None)[source]¶

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[source]¶

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[source]

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[source]¶

The capture mode

Return type:: QgsMapToolCapture.CaptureMode
Returns:: Capture mode

nextPoint(self, mapPoint: QgsPoint, layerPoint: QgsPoint) → int[source]¶

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[source]

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

virtual pointCaptured(self, point: QgsPoint)[source]¶

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][source]¶

List of digitized points

Return type:: List[QgsPoint]
Returns:: List of points

Added in version 3.12.

virtual polygonCaptured(self, polygon: QgsCurvePolygon | None)[source]¶

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)[source]¶

Enable the digitizing with curve

Deprecated since version 3.26: Use setCurrentCaptureTechnique() instead.

Parameters:: enable (bool)

setCurrentCaptureTechnique(self, technique: Qgis.CaptureTechnique)[source]¶

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])[source]¶

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])[source]

Set the points on which to work

Parameters:: pointList (Iterable[QgsPoint]) – A list of points

Added in version 3.12.

setStreamDigitizingEnabled(self, enable: bool)[source]¶

Toggles the stream digitizing mode.

Added in version 3.20.

Deprecated since version 3.26: Use setCurrentCaptureTechnique() instead.

Parameters:: enable (bool)

size(self) → int[source]¶

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)[source]¶: Start capturing

stopCapturing(self)[source]¶: Stop capturing

virtual supportsTechnique(self, technique: Qgis.CaptureTechnique) → bool[source]¶

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[source]¶

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)[source]¶

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)