Class: QgsRubberBand¶

Responsible for drawing transient features (e.g. digitizing lines) on the map.

The QgsRubberBand class provides a transparent overlay widget for tracking the mouse while drawing polylines or polygons.

Class Hierarchy¶

Base classes¶

`QgsMapCanvasItem`	An abstract class for items that can be placed on the map canvas.
QGraphicsItem

Abstract Methods

paint

Paints the rubber band in response to an update event.

Methods

`addGeometry`	Adds the geometry of an existing feature to a rubberband This is useful for multi feature highlighting.
`addPoint`	Adds a vertex to the rubberband and update canvas.
`asGeometry`	Returns the rubberband as a Geometry
`closePoints`	Ensures that a polygon geometry is closed and that the last vertex equals the first vertex.
`copyPointsFrom`	Copies the points from another rubber band.
`drawShape`	Draws shape of the rubber band.
`fillColor`	Returns the current fill color.
`getPoint`	Returns a vertex
`icon`	Returns the current icon type to highlight point geometries.
`iconSize`	Returns the current icon size of the point icons.
`movePoint`	Moves the rubber band point specified by index.
`numberOfVertices`	Returns count of vertices in all lists of mPoint
`partSize`	Returns number of vertices in feature part
`removeLastPoint`	Removes the last point.
`removePoint`	Removes a vertex from the rubberband and (optionally) updates canvas.
`reset`	Clears all the geometries in this rubberband.
`secondaryStrokeColor`	Returns the current secondary stroke color.
`setBrushStyle`	Sets the style of the brush
`setColor`	Sets the color for the rubberband.
`setFillColor`	Sets the fill color for the rubberband
`setIcon`	Sets the icon type to highlight point geometries.
`setIconSize`	Sets the size of the point icons
`setLineStyle`	Sets the style of the line
`setSecondaryStrokeColor`	Sets a secondary stroke color for the rubberband which will be drawn under the main stroke color.
`setStrokeColor`	Sets the stroke color for the rubberband
`setSvgIcon`	Set the path to the svg file to use to draw points.
`setSymbol`	Sets the symbol used for rendering the rubberband.
`setToCanvasRectangle`	Sets this rubber band to a map canvas rectangle
`setToGeometry`	Sets this rubber band to geom.
`setTranslationOffset`	Adds translation to original coordinates (all in map coordinates)
`setWidth`	Sets the width of the line.
`size`	Returns number of geometries
`strokeColor`	Returns the current stroke color.
`symbol`	Returns the symbol used for rendering the rubberband, if set.
`updateRect`	Recalculates needed rectangle
`width`	Returns the current width of the line or stroke width for polygon.

Attributes

`ICON_BOX`
`ICON_CIRCLE`
`ICON_CROSS`
`ICON_DIAMOND`
`ICON_FULL_BOX`
`ICON_FULL_DIAMOND`
`ICON_NONE`
`ICON_SVG`
`ICON_X`

class qgis.gui.QgsRubberBand[source]¶

Bases: QgsMapCanvasItem

__init__(mapCanvas: QgsMapCanvas | None, geometryType: Qgis.GeometryType = Qgis.GeometryType.Line)

Creates a new RubberBand.

Parameters:

mapCanvas (Optional[QgsMapCanvas]) – The map canvas to draw onto. Its CRS will be used to map points onto screen coordinates. The ownership is transferred to this canvas.
geometryType (Qgis.GeometryType = Qgis.GeometryType.Line) – Defines how the data should be drawn onto the screen. Qgis.GeometryType.Line, Qgis.GeometryType.Polygon or Qgis.GeometryType.Point

ICON_BOX = 3¶

ICON_CIRCLE = 4¶

ICON_CROSS = 1¶

ICON_DIAMOND = 6¶

ICON_FULL_BOX = 5¶

ICON_FULL_DIAMOND = 7¶

ICON_NONE = 0¶

ICON_SVG = 8¶

ICON_X = 2¶

class IconType¶: Bases: int

addGeometry(self, geometry: QgsGeometry, layer: QgsMapLayer | None, doUpdate: bool = True)[source]¶

Adds the geometry of an existing feature to a rubberband This is useful for multi feature highlighting. As of 2.0, this method does not change the GeometryType any more. You need to set the GeometryType of the rubberband explicitly by calling reset() or setToGeometry() with appropriate arguments. setToGeometry() is also to be preferred for backwards-compatibility.

If additional geometries are to be added then set doUpdate to False to defer costly repaint and bounding rectangle calculations for better performance. After adding the final geometry updatePosition() should be called.

Parameters:

geometry (QgsGeometry) – the geometry object. Will be treated as a collection of vertices.
layer (Optional[QgsMapLayer]) – the layer associated with the geometry. This is used for transforming the geometry from the layer’s CRS to the map crs. If layer is None no coordinate transformation will occur.
doUpdate (bool = True) – set to False to defer updates of the rubber band.

addGeometry(self, geometry: QgsGeometry, crs: QgsCoordinateReferenceSystem = QgsCoordinateReferenceSystem(), doUpdate: bool = True)[source]

Adds a geometry to the rubberband.

If crs is specified, the geometry will be automatically reprojected from crs to the canvas CRS.

If additional geometries are to be added then set doUpdate to False to defer costly repaint and bounding rectangle calculations for better performance. After adding the final geometry updatePosition() should be called.

Parameters:

geometry (QgsGeometry)
crs (QgsCoordinateReferenceSystem = QgsCoordinateReferenceSystem())
doUpdate (bool = True)

addPoint(self, p: QgsPointXY, doUpdate: bool = True, geometryIndex: int = 0, ringIndex: int = 0)[source]¶

Adds a vertex to the rubberband and update canvas. The rendering of the vertex depends on the current GeometryType and icon. If adding more points consider using update=``False`` for better performance

Parameters:

p (QgsPointXY) – The vertex/point to add
doUpdate (bool = True) – Should the map canvas be updated immediately?
geometryIndex (int = 0) – The index of the feature part (in case of multipart geometries)
ringIndex (int = 0) – The index of the polygon ring (in case of polygons with holes)

asGeometry(self) → QgsGeometry[source]¶

Returns the rubberband as a Geometry

Return type:: QgsGeometry
Returns:: A geometry object which reflects the current state of the rubberband.

closePoints(self, doUpdate: bool = True, geometryIndex: int = 0, ringIndex: int = 0)[source]¶

Ensures that a polygon geometry is closed and that the last vertex equals the first vertex.

Parameters:

doUpdate (bool = True) – set to True to update the map canvas immediately
geometryIndex (int = 0) – The index of the feature part (in case of multipart geometries)
ringIndex (int = 0) – The index of the polygon ring (in case of polygons with holes)

copyPointsFrom(self, other: QgsRubberBand | None)[source]¶

Copies the points from another rubber band.

Added in version 3.22.

Parameters:: other (Optional[QgsRubberBand])

drawShape(self, p: QPainter | None, pts: Iterable[QPointF | QPoint])[source]¶

Draws shape of the rubber band.

Parameters:

p (Optional[QPainter]) – The QPainter object
pts (Iterable[Union[QPointF, QPoint]]) – A list of points used to draw the shape

drawShape(self, p: QPainter | None, rings: Iterable[QPolygonF])[source]

Draws shape of the rubber band.

Parameters:

p (Optional[QPainter]) – The QPainter object
rings (Iterable[QPolygonF]) – A list of points used to draw the shape

fillColor(self) → QColor[source]¶

Returns the current fill color.

Return type:: QColor

getPoint(self, i: int, j: int = 0, ringIndex: int = 0) → QgsPointXY | None[source]¶

Returns a vertex

Parameters:

i (int) – The geometry index
j (int = 0) – The vertex index within ring ringIndex
ringIndex (int = 0) – The ring index within geometry i

Return type:

Optional[QgsPointXY]

icon(self) → QgsRubberBand.IconType[source]¶

Returns the current icon type to highlight point geometries.

Return type:: QgsRubberBand.IconType

iconSize(self) → float[source]¶

Returns the current icon size of the point icons.

Return type:: float

movePoint(self, p: QgsPointXY, geometryIndex: int = 0, ringIndex: int = 0)[source]¶

Moves the rubber band point specified by index. Note that if the rubber band is not used to track the last mouse position, the first point of the rubber band has two vertices

Parameters:

p (QgsPointXY)
geometryIndex (int = 0)
ringIndex (int = 0)

movePoint(self, index: int, p: QgsPointXY, geometryIndex: int = 0, ringIndex: int = 0)[source]

Moves the rubber band point specified by index. Note that if the rubber band is not used to track the last mouse position, the first point of the rubber band has two vertices

Parameters:

index (int)
p (QgsPointXY)
geometryIndex (int = 0)
ringIndex (int = 0)

numberOfVertices(self) → int[source]¶

Returns count of vertices in all lists of mPoint

Return type:: int
Returns:: The total number of vertices

abstract paint(self, p: QPainter | None)[source]¶

Paints the rubber band in response to an update event.

Parameters:: p (Optional[QPainter]) – The QPainter object

partSize(self, geometryIndex: int) → int[source]¶

Returns number of vertices in feature part

Parameters:: geometryIndex (int) – The index of the feature part (in case of multipart geometries)
Return type:: int
Returns:: number of vertices

removeLastPoint(self, geometryIndex: int = 0, doUpdate: bool = True, ringIndex: int = 0)[source]¶

Removes the last point. Most useful in connection with undo operations

Parameters:

geometryIndex (int = 0)
doUpdate (bool = True)
ringIndex (int = 0)

removePoint(self, index: int = 0, doUpdate: bool = True, geometryIndex: int = 0, ringIndex: int = 0)[source]¶

Removes a vertex from the rubberband and (optionally) updates canvas.

Parameters:

index (int = 0) – The index of the vertex/point to remove, negative indexes start at end
doUpdate (bool = True) – Should the map canvas be updated immediately?
geometryIndex (int = 0) – The index of the feature part (in case of multipart geometries)
ringIndex (int = 0) – The index of the polygon ring (in case of polygons with holes)

reset(self, geometryType: Qgis.GeometryType = Qgis.GeometryType.Line)[source]¶

Clears all the geometries in this rubberband. Sets the representation type according to geometryType.

Parameters:: geometryType (Qgis.GeometryType = Qgis.GeometryType.Line) – Defines how the data should be drawn onto the screen. (Use Qgis.Line, Qgis.Polygon or Qgis.Point)

secondaryStrokeColor(self) → QColor[source]¶

Returns the current secondary stroke color.

Return type:: QColor

setBrushStyle(self, brushStyle: Qt.BrushStyle)[source]¶

Sets the style of the brush

Parameters:: brushStyle (Qt.BrushStyle)

setColor(self, color: QColor | Qt.GlobalColor)[source]¶

Sets the color for the rubberband. Shorthand method to set fill and stroke color with a single call.

Parameters:: color (Union[QColor, Qt.GlobalColor]) – The color used to render this rubberband

setFillColor(self, color: QColor | Qt.GlobalColor)[source]¶

Sets the fill color for the rubberband

Parameters:: color (Union[QColor, Qt.GlobalColor]) – The color used to render this rubberband

setIcon(self, icon: QgsRubberBand.IconType)[source]¶

Sets the icon type to highlight point geometries.

Parameters:: icon (QgsRubberBand.IconType) – The icon to visualize point geometries

setIconSize(self, iconSize: float)[source]¶

Sets the size of the point icons

Parameters:: iconSize (float)

setLineStyle(self, penStyle: Qt.PenStyle)[source]¶

Sets the style of the line

Parameters:: penStyle (Qt.PenStyle)

setSecondaryStrokeColor(self, color: QColor | Qt.GlobalColor)[source]¶

Sets a secondary stroke color for the rubberband which will be drawn under the main stroke color. Set to an invalid color to avoid drawing the secondary stroke.

Parameters:: color (Union[QColor, Qt.GlobalColor]) – The color used to render a secondary stroke color to this rubberband

setStrokeColor(self, color: QColor | Qt.GlobalColor)[source]¶

Sets the stroke color for the rubberband

Parameters:: color (Union[QColor, Qt.GlobalColor]) – The color used to render this rubberband

setSvgIcon(self, path: str | None, drawOffset: QPoint)[source]¶

Set the path to the svg file to use to draw points. Calling this function automatically calls setIcon(ICON_SVG)

Parameters:

path (Optional[str]) – The path to the svg
drawOffset (QPoint) – The offset where to draw the image origin

Added in version 3.10.

setSymbol(self, symbol: QgsSymbol | None)[source]¶

Sets the symbol used for rendering the rubberband.

Ownership of symbol is transferred to the rubberband.

Warning

Only line and fill symbols are currently supported.

Note

Setting a symbol for the rubberband overrides any other appearance setting, such as the strokeColor() or width().