A class for drawing transient features (e.g. More...

#include <qgsrubberband.h>

Inheritance diagram for QgsRubberBand:

[legend]

Public Types
enum	IconType { ICON_NONE , ICON_CROSS , ICON_X , ICON_BOX , ICON_CIRCLE , ICON_FULL_BOX , ICON_DIAMOND , ICON_FULL_DIAMOND , ICON_SVG }
	Icons. More...

Public Member Functions
	QgsRubberBand (QgsMapCanvas *mapCanvas, Qgis::GeometryType geometryType=Qgis::GeometryType::Line)
	Creates a new RubberBand.

	~QgsRubberBand () override

void	addGeometry (const QgsGeometry &geometry, const QgsCoordinateReferenceSystem &crs=QgsCoordinateReferenceSystem(), bool doUpdate=true)
	Adds a geometry to the rubberband.

void	addGeometry (const QgsGeometry &geometry, QgsMapLayer *layer, bool doUpdate=true)
	Adds the geometry of an existing feature to a rubberband This is useful for multi feature highlighting.

void	addPoint (const QgsPointXY &p, bool doUpdate=true, int geometryIndex=0, int ringIndex=0)
	Adds a vertex to the rubberband and update canvas.

QgsGeometry	asGeometry () const
	Returns the rubberband as a Geometry.

void	closePoints (bool doUpdate=true, int geometryIndex=0, int ringIndex=0)
	Ensures that a polygon geometry is closed and that the last vertex equals the first vertex.

void	copyPointsFrom (const QgsRubberBand *other)
	Copies the points from another rubber band.

QColor	fillColor () const
	Returns the current fill color.

const QgsPointXY *	getPoint (int i, int j=0, int ringIndex=0) const
	Returns a vertex.

IconType	icon () const
	Returns the current icon type to highlight point geometries.

double	iconSize () const
	Returns the current icon size of the point icons.

void	movePoint (const QgsPointXY &p, int geometryIndex=0, int ringIndex=0)
	Moves the rubber band point specified by index.

void	movePoint (int index, const QgsPointXY &p, int geometryIndex=0, int ringIndex=0)
	Moves the rubber band point specified by index.

int	numberOfVertices () const
	Returns count of vertices in all lists of mPoint.

int	partSize (int geometryIndex) const
	Returns number of vertices in feature part.

void	removeLastPoint (int geometryIndex=0, bool doUpdate=true, int ringIndex=0)
	Removes the last point.

void	removePoint (int index=0, bool doUpdate=true, int geometryIndex=0, int ringIndex=0)
	Removes a vertex from the rubberband and (optionally) updates canvas.

void	reset (Qgis::GeometryType geometryType=Qgis::GeometryType::Line)
	Clears all the geometries in this rubberband.

QColor	secondaryStrokeColor () const
	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 (double 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	setSvgIcon (const QString &path, QPoint drawOffset)
	Set the path to the svg file to use to draw points.

void	setSymbol (QgsSymbol *symbol)
	Sets the symbol used for rendering 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 (double width)
	Sets the width of the line.

int	size () const
	Returns number of geometries.

QColor	strokeColor () const
	Returns the current stroke color.

QgsSymbol *	symbol () const
	Returns the symbol used for rendering the rubberband, if set.

void	updatePosition () override
	called on changed extent or resize event to update position of the item

int	width () const
	Returns the current width of the line or stroke width for polygon.

Public Member Functions inherited from QgsMapCanvasItem
QRectF	boundingRect () const override

QgsRectangle	rect () const
	returns canvas item rectangle in map units

void	setRect (const QgsRectangle &r, bool resetRotation=true)
	sets canvas item rectangle in map units

QPointF	toCanvasCoordinates (const QgsPointXY &point) const
	transformation from map coordinates to screen coordinates

QgsPointXY	toMapCoordinates (QPoint point) const
	transformation from screen coordinates to map coordinates

Protected Member Functions
void	drawShape (QPainter *p, const QVector< QPointF > &pts)
	Draws shape of the rubber band.

void	drawShape (QPainter *p, const QVector< QPolygonF > &rings)
	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.

Protected Member Functions inherited from QgsMapCanvasItem
	QgsMapCanvasItem (QgsMapCanvas *mapCanvas)
	protected constructor: cannot be constructed directly

	~QgsMapCanvasItem () override

void	paint (QPainter painter, const QStyleOptionGraphicsItem option, QWidget *widget=nullptr) override

bool	setRenderContextVariables (QPainter *p, QgsRenderContext &context) const
	Sets render context parameters.

void	updateCanvas ()
	schedules map canvas for repaint

Properties
QColor	fillColor

int	iconSize

QColor	secondaryStrokeColor

QColor	strokeColor

int	width

Additional Inherited Members
Protected Attributes inherited from QgsMapCanvasItem
QSizeF	mItemSize
	cached size of the item (to return in boundingRect())

QgsMapCanvas *	mMapCanvas = nullptr
	pointer to map canvas

QgsRectangle	mRect
	cached canvas item rectangle in map coordinates encodes position (xmin,ymax) and size (width/height) used to re-position and re-size the item on zoom/pan while waiting for the renderer to complete.

double	mRectRotation

Detailed Description

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.

Definition at line 53 of file qgsrubberband.h.

Member Enumeration Documentation

◆ IconType

enum QgsRubberBand::IconType

Icons.

Enumerator
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 (◇)
ICON_FULL_DIAMOND	A diamond is used to highlight points (◆)
ICON_SVG	An svg image is used to highlight points. Since QGIS 3.10

Definition at line 84 of file qgsrubberband.h.

Constructor & Destructor Documentation

◆ QgsRubberBand()

QgsRubberBand::QgsRubberBand	(	QgsMapCanvas *	mapCanvas,
		Qgis::GeometryType	geometryType = `Qgis::GeometryType::Line`
	)

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. Qgis::GeometryType::Line, Qgis::GeometryType::Polygon or Qgis::GeometryType::Point

Definition at line 32 of file qgsrubberband.cpp.

◆ ~QgsRubberBand()

QgsRubberBand::~QgsRubberBand ( )

overridedefault

Member Function Documentation

◆ addGeometry() [1/2]

void QgsRubberBand::addGeometry	(	const QgsGeometry &	geometry,
		const QgsCoordinateReferenceSystem &	crs = `QgsCoordinateReferenceSystem()`,
		bool	doUpdate = `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.

Definition at line 308 of file qgsrubberband.cpp.

◆ addGeometry() [2/2]

void QgsRubberBand::addGeometry	(	const QgsGeometry &	geometry,
		QgsMapLayer *	layer,
		bool	doUpdate = `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	the geometry object. Will be treated as a collection of vertices.
layer	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 `nullptr` no coordinate transformation will occur.
doUpdate	set to `false` to defer updates of the rubber band.

Definition at line 289 of file qgsrubberband.cpp.

◆ addPoint()

void QgsRubberBand::addPoint	(	const QgsPointXY &	p,
		bool	doUpdate = `true`,
		int	geometryIndex = `0`,
		int	ringIndex = `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	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)
ringIndex	The index of the polygon ring (in case of polygons with holes)

Definition at line 119 of file qgsrubberband.cpp.

◆ asGeometry()

QgsGeometry QgsRubberBand::asGeometry ( ) const

Returns the rubberband as a Geometry.

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

Definition at line 747 of file qgsrubberband.cpp.

◆ closePoints()

void QgsRubberBand::closePoints	(	bool	doUpdate = `true`,
		int	geometryIndex = `0`,
		int	ringIndex = `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	The index of the feature part (in case of multipart geometries)
ringIndex	The index of the polygon ring (in case of polygons with holes)

Definition at line 177 of file qgsrubberband.cpp.

◆ copyPointsFrom()

void QgsRubberBand::copyPointsFrom ( const QgsRubberBand * other )

Copies the points from another rubber band.

Since: QGIS 3.22

Definition at line 440 of file qgsrubberband.cpp.

◆ drawShape() [1/2]

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

Definition at line 548 of file qgsrubberband.cpp.

◆ drawShape() [2/2]

void QgsRubberBand::drawShape	(	QPainter *	p,
		const QVector< QPolygonF > &	rings
	)

protected

Draws shape of the rubber band.

Parameters

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

Definition at line 531 of file qgsrubberband.cpp.

◆ fillColor()

QColor QgsRubberBand::fillColor ( ) const

inline

Returns the current fill color.

Definition at line 161 of file qgsrubberband.h.

◆ getPoint()

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

Returns a vertex.

Parameters

i	The geometry index
j	The vertex index within ring ringIndex
ringIndex	The ring index within geometry i

Definition at line 736 of file qgsrubberband.cpp.

◆ icon()

IconType QgsRubberBand::icon ( ) const

inline

Returns the current icon type to highlight point geometries.

Definition at line 216 of file qgsrubberband.h.

◆ iconSize()

double QgsRubberBand::iconSize ( ) const

inline

Returns the current icon size of the point icons.

Definition at line 226 of file qgsrubberband.h.

◆ movePoint() [1/2]

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

Definition at line 233 of file qgsrubberband.cpp.

◆ movePoint() [2/2]

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

Definition at line 249 of file qgsrubberband.cpp.

◆ numberOfVertices()

int QgsRubberBand::numberOfVertices ( ) const

Returns count of vertices in all lists of mPoint.

Returns: The total number of vertices

Definition at line 723 of file qgsrubberband.cpp.

◆ paint()

void QgsRubberBand::paint ( QPainter * p )

overrideprotectedvirtual

Paints the rubber band in response to an update event.

Parameters

p	The QPainter object

Implements QgsMapCanvasItem.

Definition at line 448 of file qgsrubberband.cpp.

◆ partSize()

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

Definition at line 714 of file qgsrubberband.cpp.

◆ removeLastPoint()

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

Removes the last point.

Most useful in connection with undo operations

Definition at line 228 of file qgsrubberband.cpp.

◆ removePoint()

void QgsRubberBand::removePoint	(	int	index = `0`,
		bool	doUpdate = `true`,
		int	geometryIndex = `0`,
		int	ringIndex = `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)
ringIndex	The index of the polygon ring (in case of polygons with holes)

Definition at line 201 of file qgsrubberband.cpp.

◆ reset()

void QgsRubberBand::reset ( Qgis::GeometryType geometryType = Qgis::GeometryType::Line )

Clears all the geometries in this rubberband.

Sets the representation type according to geometryType.

Parameters

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

Definition at line 111 of file qgsrubberband.cpp.

◆ secondaryStrokeColor()

QColor QgsRubberBand::secondaryStrokeColor ( ) const

inline

Returns the current secondary stroke color.

Definition at line 184 of file qgsrubberband.h.

◆ setBrushStyle()

void QgsRubberBand::setBrushStyle ( Qt::BrushStyle brushStyle )

Sets the style of the brush.

Definition at line 106 of file qgsrubberband.cpp.

◆ setColor()

void QgsRubberBand::setColor ( const QColor & color )

Sets the color for the rubberband.

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

Parameters

color The color used to render this rubberband

Definition at line 55 of file qgsrubberband.cpp.

◆ setFillColor()

void QgsRubberBand::setFillColor ( const QColor & color )

Sets the fill color for the rubberband.

Parameters

color The color used to render this rubberband

Definition at line 61 of file qgsrubberband.cpp.

◆ setIcon()

void QgsRubberBand::setIcon ( IconType icon )

Sets the icon type to highlight point geometries.

Parameters

icon	The icon to visualize point geometries

Definition at line 84 of file qgsrubberband.cpp.

◆ setIconSize()

void QgsRubberBand::setIconSize ( double iconSize )

Sets the size of the point icons.

Definition at line 96 of file qgsrubberband.cpp.

◆ setLineStyle()

void QgsRubberBand::setLineStyle ( Qt::PenStyle penStyle )

Sets the style of the line.

Definition at line 101 of file qgsrubberband.cpp.

◆ setSecondaryStrokeColor()

void QgsRubberBand::setSecondaryStrokeColor ( const QColor & color )

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

Definition at line 74 of file qgsrubberband.cpp.

◆ setStrokeColor()

void QgsRubberBand::setStrokeColor ( const QColor & color )

Sets the stroke color for the rubberband.

Parameters

color The color used to render this rubberband

Definition at line 69 of file qgsrubberband.cpp.

◆ setSvgIcon()

void QgsRubberBand::setSvgIcon	(	const QString &	path,
		QPoint	drawOffset
	)

Set the path to the svg file to use to draw points.

Calling this function automatically calls setIcon(ICON_SVG)

Parameters

path	The path to the svg
drawOffset	The offset where to draw the image origin

Since: QGIS 3.10

Definition at line 89 of file qgsrubberband.cpp.

◆ setSymbol()

void QgsRubberBand::setSymbol ( QgsSymbol * symbol )

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

Since: QGIS 3.20

Definition at line 687 of file qgsrubberband.cpp.

◆ setToCanvasRectangle()

void QgsRubberBand::setToCanvasRectangle ( QRect rect )

Sets this rubber band to a map canvas rectangle.

Parameters

rect	rectangle in canvas coordinates

Definition at line 420 of file qgsrubberband.cpp.

◆ setToGeometry() [1/2]

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

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	the geometry object
layer	the layer containing the feature, used for coord transformation to map crs. If layer is `nullptr`, the coordinates are not going to be transformed.

Definition at line 265 of file qgsrubberband.cpp.

◆ setToGeometry() [2/2]

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.

Since: QGIS 3.4

Definition at line 277 of file qgsrubberband.cpp.

◆ setTranslationOffset()

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

Adds translation to original coordinates (all in map coordinates)

Parameters

dx	x translation
dy	y translation

Definition at line 702 of file qgsrubberband.cpp.

◆ setWidth()

void QgsRubberBand::setWidth ( double width )

Sets the width of the line.

Stroke width for polygon.

Parameters

width The width for any lines painted for this rubberband

Definition at line 79 of file qgsrubberband.cpp.

◆ size()

int QgsRubberBand::size ( ) const

Returns number of geometries.

Returns: number of geometries

Definition at line 709 of file qgsrubberband.cpp.

◆ strokeColor()

QColor QgsRubberBand::strokeColor ( ) const

inline

Returns the current stroke color.

Definition at line 172 of file qgsrubberband.h.

◆ symbol()

QgsSymbol * QgsRubberBand::symbol ( ) const

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

See also: setSymbol()

Since: QGIS 3.20

Definition at line 682 of file qgsrubberband.cpp.

◆ updatePosition()

void QgsRubberBand::updatePosition ( )

overridevirtual

called on changed extent or resize event to update position of the item

Reimplemented from QgsMapCanvasItem.

Definition at line 692 of file qgsrubberband.cpp.

◆ updateRect()

void QgsRubberBand::updateRect ( )

protected

Recalculates needed rectangle.

Definition at line 638 of file qgsrubberband.cpp.

◆ width()

int QgsRubberBand::width ( ) const

inline

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

Definition at line 195 of file qgsrubberband.h.

Property Documentation

◆ fillColor

QColor QgsRubberBand::fillColor

readwrite

Definition at line 77 of file qgsrubberband.h.

◆ iconSize

int QgsRubberBand::iconSize

readwrite

Definition at line 79 of file qgsrubberband.h.

◆ secondaryStrokeColor

QColor QgsRubberBand::secondaryStrokeColor

readwrite

Definition at line 80 of file qgsrubberband.h.

◆ strokeColor

QColor QgsRubberBand::strokeColor

readwrite

Definition at line 78 of file qgsrubberband.h.

◆ width

int QgsRubberBand::width

readwrite

Definition at line 81 of file qgsrubberband.h.

The documentation for this class was generated from the following files:

/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/gui/qgsrubberband.h
/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/gui/qgsrubberband.cpp

Public Types

Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ IconType

Constructor & Destructor Documentation

◆ QgsRubberBand()

◆ ~QgsRubberBand()

Member Function Documentation

◆ addGeometry() [1/2]

◆ addGeometry() [2/2]

◆ addPoint()

◆ asGeometry()

◆ closePoints()

◆ copyPointsFrom()

◆ drawShape() [1/2]

◆ drawShape() [2/2]

◆ fillColor()

◆ getPoint()

◆ icon()

◆ iconSize()

◆ movePoint() [1/2]

◆ movePoint() [2/2]

◆ numberOfVertices()

◆ paint()

◆ partSize()

◆ removeLastPoint()

◆ removePoint()

◆ reset()

◆ secondaryStrokeColor()

◆ setBrushStyle()

◆ setColor()

◆ setFillColor()

◆ setIcon()

◆ setIconSize()

◆ setLineStyle()

◆ setSecondaryStrokeColor()

◆ setStrokeColor()

◆ setSvgIcon()

◆ setSymbol()

◆ setToCanvasRectangle()

◆ setToGeometry() [1/2]

◆ setToGeometry() [2/2]

◆ setTranslationOffset()

◆ setWidth()

◆ size()

◆ strokeColor()

◆ symbol()

◆ updatePosition()

◆ updateRect()

◆ width()

Property Documentation

◆ fillColor

◆ iconSize

◆ secondaryStrokeColor

◆ strokeColor

◆ width