QgsRubberBand class

A class for drawing transient features (e.g.

Reference

digitizing lines) on the map.

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

Base classes

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

Public types

enum IconType { ICON_NONE, ICON_CROSS, ICON_X, ICON_BOX, ICON_CIRCLE, ICON_FULL_BOX, ICON_DIAMOND, ICON_FULL_DIAMOND }: Icons.

Constructors, destructors, conversion operators

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

Public functions

void addGeometry(const QgsGeometry& geometry, QgsVectorLayer* layer): Adds the geometry of an existing feature to a rubberband This is useful for multi feature highlighting.
void addGeometry(const QgsGeometry& geometry, const QgsCoordinateReferenceSystem& crs = QgsCoordinateReferenceSystem()): Adds a geometry to the rubberband.
void addPoint(const QgsPointXY& p, bool doUpdate = true, int geometryIndex = 0): Adds a vertex to the rubberband and update canvas.
auto asGeometry() const -> QgsGeometry: Returns the rubberband as a Geometry.
void closePoints(bool doUpdate = true, int geometryIndex = 0): Ensures that a polygon geometry is closed and that the last vertex equals the first vertex.
auto fillColor() const -> QColor: Returns the current fill color.
auto getPoint(int i, int j = 0) const -> const QgsPointXY*: Returns a vertex.
auto icon() const -> IconType: Returns the current icon type to highlight point geometries.
auto iconSize() const -> int: Returns the current icon size of the point icons.
void movePoint(const QgsPointXY& p, int geometryIndex = 0): Moves the rubber band point specified by index.
void movePoint(int index, const QgsPointXY& p, int geometryIndex = 0): Moves the rubber band point specified by index.
auto numberOfVertices() const -> int: Returns count of vertices in all lists of mPoint.
auto partSize(int geometryIndex) const -> int: Returns number of vertices in feature part.
void removeLastPoint(int geometryIndex = 0, bool doUpdate = true): Removes the last point.
void removePoint(int index = 0, bool doUpdate = true, int geometryIndex = 0): Removes a vertex from the rubberband and (optionally) updates canvas.
void reset(QgsWkbTypes::GeometryType geometryType = QgsWkbTypes::LineGeometry): Clears all the geometries in this rubberband.
auto secondaryStrokeColor() const -> QColor: Returns the current secondary stroke color.
void setBrushStyle(Qt::BrushStyle brushStyle): Sets the style of the brush.
void setColor(const QColor& color): Sets the color for the rubberband.
void setFillColor(const QColor& color): Sets the fill color for the rubberband.
void setIcon(IconType icon): Sets the icon type to highlight point geometries.
void setIconSize(int iconSize): Sets the size of the point icons.
void setLineStyle(Qt::PenStyle penStyle): Sets the style of the line.
void setSecondaryStrokeColor(const QColor& color): Sets a secondary stroke color for the rubberband which will be drawn under the main stroke color.
void setStrokeColor(const QColor& color): Sets the stroke color for the rubberband.
void setToCanvasRectangle(QRect rect): Sets this rubber band to a map canvas rectangle.
void setToGeometry(const QgsGeometry& geom, QgsVectorLayer* layer): Sets this rubber band to geom.
void setToGeometry(const QgsGeometry& geometry, const QgsCoordinateReferenceSystem& crs = QgsCoordinateReferenceSystem()): Sets this rubber band to geometry.
void setTranslationOffset(double dx, double dy): Adds translation to original coordinates (all in map coordinates)
void setWidth(int width): Sets the width of the line.
auto size() const -> int: Returns number of geometries.
auto strokeColor() const -> QColor: Returns the current stroke color.
void updatePosition() override: called on changed extent or resize event to update position of the item
auto width() const -> int: Returns the current width of the line or stroke width for polygon.

Protected functions

void drawShape(QPainter* p, const QVector<QPointF>& pts): Draws shape of the rubber band.
void paint(QPainter* p) override: Paints the rubber band in response to an update event.
void updateRect(): Recalculates needed rectangle.

Enum documentation

enum QgsRubberBand::IconType

Icons.

Enumerators
ICON_NONE	No icon is used.
ICON_CROSS	A cross is used to highlight points (+)
ICON_X	A cross is used to highlight points (x)
ICON_BOX	A box is used to highlight points (□)
ICON_CIRCLE	A circle is used to highlight points (○)
ICON_FULL_BOX	A full box is used to highlight points (■)
ICON_DIAMOND	A diamond is used to highlight points (◇) Since QGIS 3.0
ICON_FULL_DIAMOND	A diamond is used to highlight points (◆) Since QGIS 3.0

Function documentation

QgsRubberBand::QgsRubberBand(QgsMapCanvas* mapCanvas, QgsWkbTypes::GeometryType geometryType = QgsWkbTypes::LineGeometry)

Creates a new RubberBand.

Parameters
mapCanvas	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	Defines how the data should be drawn onto the screen. QgsWkbTypes::LineGeometry, QgsWkbTypes::PolygonGeometry or QgsWkbTypes::PointGeometry

void QgsRubberBand::addGeometry(const QgsGeometry& geometry, QgsVectorLayer* layer)

Adds the geometry of an existing feature to a rubberband This is useful for multi feature highlighting.

Parameters
geometry	the geometry object. Will be treated as a collection of vertices.
layer	the layer containing the feature, used for coord transformation to map crs. In case of 0 pointer, the coordinates are not going to be transformed.

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.

void QgsRubberBand::addGeometry(const QgsGeometry& geometry, const QgsCoordinateReferenceSystem& crs = QgsCoordinateReferenceSystem())

Adds a geometry to the rubberband.

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

void QgsRubberBand::addPoint(const QgsPointXY& p, bool doUpdate = true, int geometryIndex = 0)

Adds a vertex to the rubberband and update canvas.

Parameters
p	The vertex/point to add
doUpdate	Should the map canvas be updated immediately?
geometryIndex	The index of the feature part (in case of multipart geometries)

The rendering of the vertex depends on the current GeometryType and icon. If adding more points consider using update=false for better performance

QgsGeometry QgsRubberBand::asGeometry() const

Returns the rubberband as a Geometry.

Returns	A geometry object which reflects the current state of the rubberband.

void QgsRubberBand::closePoints(bool doUpdate = true, int geometryIndex = 0)

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

Parameters
doUpdate	set to true to update the map canvas immediately
geometryIndex	index of the feature part (in case of multipart geometries)

const QgsPointXY* QgsRubberBand::getPoint(int i, int j = 0) const

Returns a vertex.

Parameters
i	The geometry index
j	The vertex index within geometry i

void QgsRubberBand::movePoint(const QgsPointXY& p, int geometryIndex = 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

void QgsRubberBand::movePoint(int index, const QgsPointXY& p, int geometryIndex = 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

int QgsRubberBand::numberOfVertices() const

Returns count of vertices in all lists of mPoint.

Returns	The total number of vertices

int QgsRubberBand::partSize(int geometryIndex) const

Returns number of vertices in feature part.

Parameters
geometryIndex	The index of the feature part (in case of multipart geometries)
Returns	number of vertices

void QgsRubberBand::removeLastPoint(int geometryIndex = 0, bool doUpdate = true)

Removes the last point.

Most useful in connection with undo operations

void QgsRubberBand::removePoint(int index = 0, bool doUpdate = true, int geometryIndex = 0)

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

Parameters
index	The index of the vertex/point to remove, negative indexes start at end
doUpdate	Should the map canvas be updated immediately?
geometryIndex	The index of the feature part (in case of multipart geometries)

void QgsRubberBand::reset(QgsWkbTypes::GeometryType geometryType = QgsWkbTypes::LineGeometry)

Clears all the geometries in this rubberband.

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

Sets the representation type according to geometryType.

void QgsRubberBand::setColor(const QColor& color)

Sets the color for the rubberband.

Parameters
color	The color used to render this rubberband

Shorthand method to set fill and stroke color with a single call.

void QgsRubberBand::setFillColor(const QColor& color)

Sets the fill color for the rubberband.

Parameters
color	The color used to render this rubberband

void QgsRubberBand::setIcon(IconType icon)

Sets the icon type to highlight point geometries.

Parameters
icon	The icon to visualize point geometries

void QgsRubberBand::setSecondaryStrokeColor(const QColor& color)

Sets a secondary stroke color for the rubberband which will be drawn under the main stroke color.

Parameters
color	The color used to render a secondary stroke color to this rubberband

Set to an invalid color to avoid drawing the secondary stroke.

void QgsRubberBand::setStrokeColor(const QColor& color)

Sets the stroke color for the rubberband.

Parameters
color	The color used to render this rubberband

void QgsRubberBand::setToCanvasRectangle(QRect rect)

Sets this rubber band to a map canvas rectangle.

Parameters
rect	rectangle in canvas coordinates

void QgsRubberBand::setToGeometry(const QgsGeometry& geom, QgsVectorLayer* layer)

Sets this rubber band to geom.

Parameters
geom	the geometry object
layer	the layer containing the feature, used for coord transformation to map crs. In case of 0 pointer, the coordinates are not going to be transformed.

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

void QgsRubberBand::setToGeometry(const QgsGeometry& geometry, const QgsCoordinateReferenceSystem& crs = 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.

void QgsRubberBand::setTranslationOffset(double dx, double dy)

Adds translation to original coordinates (all in map coordinates)

Parameters
dx	x translation
dy	y translation

void QgsRubberBand::setWidth(int width)

Sets the width of the line.

Parameters
width	The width for any lines painted for this rubberband

Stroke width for polygon.

int QgsRubberBand::size() const

Returns number of geometries.

Returns	number of geometries

void QgsRubberBand::drawShape(QPainter* p, const QVector<QPointF>& pts) protected

Draws shape of the rubber band.

Parameters
p	The QPainter object
pts	A list of points used to draw the shape

void QgsRubberBand::paint(QPainter* p) override protected

Paints the rubber band in response to an update event.

Parameters
p	The QPainter object