Class: QgsRubberBand

class qgis.gui.QgsRubberBand

Bases: QgsMapCanvasItem

A class 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.

QgsRubberBand(mapCanvas: QgsMapCanvas, geometryType: QgsWkbTypes.GeometryType = QgsWkbTypes.LineGeometry) Creates a new RubberBand.

Parameters
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, doUpdate: bool = True)

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 (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) 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.

New in version 3.0.

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

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

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)

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)

New in version 2.16.

contextMenuEvent(self, QGraphicsSceneContextMenuEvent)
copyPointsFrom(self, other: QgsRubberBand)

Copies the points from another rubber band.

New in version 3.22.

Parameters

other (QgsRubberBand) –

dragEnterEvent(self, QGraphicsSceneDragDropEvent)
dragLeaveEvent(self, QGraphicsSceneDragDropEvent)
dragMoveEvent(self, QGraphicsSceneDragDropEvent)
drawShape(self, p: QPainter, pts: Iterable[Union[QPointF, QPoint]])

Draws shape of the rubber band.

Parameters
  • p (QPainter) – The QPainter object

  • pts (Iterable[Union[QPointF) – A list of points used to draw the shape

drawShape(self, p: QPainter, rings: Iterable[QPolygonF]) Draws shape of the rubber band.

Parameters
  • p – The QPainter object

  • rings – A list of points used to draw the shape

dropEvent(self, QGraphicsSceneDragDropEvent)
fillColor(self) QColor

Returns the current fill color.

Return type

QColor

focusInEvent(self, QFocusEvent)
focusOutEvent(self, QFocusEvent)
getPoint(self, i: int, j: int = 0, ringIndex: int = 0) QgsPointXY

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

QgsPointXY

hoverEnterEvent(self, QGraphicsSceneHoverEvent)
hoverLeaveEvent(self, QGraphicsSceneHoverEvent)
hoverMoveEvent(self, QGraphicsSceneHoverEvent)
icon(self) QgsRubberBand.IconType

Returns the current icon type to highlight point geometries.

Return type

QgsRubberBand.IconType

iconSize(self) int

Returns the current icon size of the point icons.

Return type

int

inputMethodEvent(self, QInputMethodEvent)
inputMethodQuery(self, Qt.InputMethodQuery) Any
itemChange(self, QGraphicsItem.GraphicsItemChange, Any) Any
keyPressEvent(self, QKeyEvent)
keyReleaseEvent(self, QKeyEvent)
mouseDoubleClickEvent(self, QGraphicsSceneMouseEvent)
mouseMoveEvent(self, QGraphicsSceneMouseEvent)
mousePressEvent(self, QGraphicsSceneMouseEvent)
mouseReleaseEvent(self, QGraphicsSceneMouseEvent)
movePoint(self, p: QgsPointXY, geometryIndex: int = 0, ringIndex: int = 0)

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

movePoint(self, index: int, p: QgsPointXY, geometryIndex: int = 0, ringIndex: int = 0) 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) –

numberOfVertices(self) int

Returns count of vertices in all lists of mPoint

Return type

int

Returns

The total number of vertices

paint(self, p: QPainter)

Paints the rubber band in response to an update event.

Parameters

p (QPainter) – The QPainter object

partSize(self, geometryIndex: int) int

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

prepareGeometryChange(self)
removeLastPoint(self, geometryIndex: int = 0, doUpdate: bool = True, ringIndex: int = 0)

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)

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: QgsWkbTypes.GeometryType = QgsWkbTypes.LineGeometry)

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

Parameters

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

sceneEvent(self, QEvent) bool
sceneEventFilter(self, QGraphicsItem, QEvent) bool
secondaryStrokeColor(self) QColor

Returns the current secondary stroke color.

Return type

QColor

setBrushStyle(self, brushStyle: Qt.BrushStyle)

Sets the style of the brush

Parameters

brushStyle (Qt.BrushStyle) –

setColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

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

Parameters

color (Union[QColor) – The color used to render this rubberband

setFillColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

Sets the fill color for the rubberband

Parameters

color (Union[QColor) – The color used to render this rubberband

New in version 2.6.

setIcon(self, icon: QgsRubberBand.IconType)

Sets the icon type to highlight point geometries.

Parameters

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

setIconSize(self, iconSize: int)

Sets the size of the point icons

Parameters

iconSize (int) –

setLineStyle(self, penStyle: Qt.PenStyle)

Sets the style of the line

Parameters

penStyle (Qt.PenStyle) –

setRenderContextVariables(self, p: QPainter, context: QgsRenderContext) bool

Sets render context parameters

Parameters
  • p – painter for rendering

  • context – out: configured context

Returns

True in case of success

setSecondaryStrokeColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

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) – The color used to render a secondary stroke color to this rubberband

New in version 3.0.

setStrokeColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

Sets the stroke color for the rubberband

Parameters

color (Union[QColor) – The color used to render this rubberband

New in version 2.6.

setSvgIcon(self, path: str, drawOffset: QPoint)

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

Parameters
  • path (str) – The path to the svg

  • drawOffset (QPoint) – The offset where to draw the image origin

New in version 3.10.

setSymbol(self, symbol: QgsSymbol)

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().

See also

setSymbol()

New in version 3.20.

Parameters

symbol (QgsSymbol) –

setToCanvasRectangle(self, rect: QRect)

Sets this rubber band to a map canvas rectangle

Parameters

rect (QRect) – rectangle in canvas coordinates

setToGeometry(self, geom: QgsGeometry, layer: QgsVectorLayer)

Sets this rubber band to geom. This is useful for feature highlighting. In contrast to addGeometry(), this method does also change the geometry type of the rubberband.

Parameters
  • geom (QgsGeometry) – the geometry object

  • layer (QgsVectorLayer) – the layer containing the feature, used for coord transformation to map crs. If layer is None, the coordinates are not going to be transformed.

setToGeometry(self, geometry: QgsGeometry, crs: QgsCoordinateReferenceSystem = QgsCoordinateReferenceSystem()) Sets this rubber band to geometry. In contrast to addGeometry(), this method does also change the geometry type of the rubberband. The coordinate reference system of the geometry can be specified with crs. If an invalid crs is passed, the geometry will not be reprojected and needs to be in canvas crs already. By default, no reprojection is done.

New in version 3.4.

setTranslationOffset(self, dx: float, dy: float)

Adds translation to original coordinates (all in map coordinates)

Parameters
  • dx (float) – x translation

  • dy (float) – y translation

setWidth(self, width: int)

Sets the width of the line. Stroke width for polygon.

Parameters

width (int) – The width for any lines painted for this rubberband

size(self) int

Returns number of geometries

Return type

int

Returns

number of geometries

strokeColor(self) QColor

Returns the current stroke color.

Return type

QColor

symbol(self) QgsSymbol

Returns the symbol used for rendering the rubberband, if set.

See also

setSymbol()

New in version 3.20.

Return type

QgsSymbol

updateCanvas(self)

schedules map canvas for repaint

updateMicroFocus(self)
updatePosition(self)
updateRect(self)

Recalculates needed rectangle

wheelEvent(self, QGraphicsSceneWheelEvent)
width(self) int

Returns the current width of the line or stroke width for polygon.

Return type

int