QGIS API Documentation 3.28.0-Firenze (ed3ad0430f)
Public Types | Public Member Functions | Protected Member Functions | Properties | List of all members
QgsRubberBand Class Reference

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

#include <qgsrubberband.h>

Inheritance diagram for QgsRubberBand:
Inheritance graph
[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, QgsWkbTypes::GeometryType geometryType=QgsWkbTypes::LineGeometry)
 Creates a new RubberBand. More...
 
 ~QgsRubberBand () override
 
void addGeometry (const QgsGeometry &geometry, const QgsCoordinateReferenceSystem &crs=QgsCoordinateReferenceSystem(), bool doUpdate=true)
 Adds a geometry to the rubberband. More...
 
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. More...
 
void addPoint (const QgsPointXY &p, bool doUpdate=true, int geometryIndex=0, int ringIndex=0)
 Adds a vertex to the rubberband and update canvas. More...
 
QgsGeometry asGeometry () const
 Returns the rubberband as a Geometry. More...
 
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. More...
 
void copyPointsFrom (const QgsRubberBand *other)
 Copies the points from another rubber band. More...
 
QColor fillColor () const
 Returns the current fill color. More...
 
const QgsPointXYgetPoint (int i, int j=0, int ringIndex=0) const
 Returns a vertex. More...
 
IconType icon () const
 Returns the current icon type to highlight point geometries. More...
 
int iconSize () const
 Returns the current icon size of the point icons. More...
 
void movePoint (const QgsPointXY &p, int geometryIndex=0, int ringIndex=0)
 Moves the rubber band point specified by index. More...
 
void movePoint (int index, const QgsPointXY &p, int geometryIndex=0, int ringIndex=0)
 Moves the rubber band point specified by index. More...
 
int numberOfVertices () const
 Returns count of vertices in all lists of mPoint. More...
 
int partSize (int geometryIndex) const
 Returns number of vertices in feature part. More...
 
void removeLastPoint (int geometryIndex=0, bool doUpdate=true, int ringIndex=0)
 Removes the last point. More...
 
void removePoint (int index=0, bool doUpdate=true, int geometryIndex=0, int ringIndex=0)
 Removes a vertex from the rubberband and (optionally) updates canvas. More...
 
void reset (QgsWkbTypes::GeometryType geometryType=QgsWkbTypes::LineGeometry)
 Clears all the geometries in this rubberband. More...
 
QColor secondaryStrokeColor () const
 Returns the current secondary stroke color. More...
 
void setBrushStyle (Qt::BrushStyle brushStyle)
 Sets the style of the brush. More...
 
void setColor (const QColor &color)
 Sets the color for the rubberband. More...
 
void setFillColor (const QColor &color)
 Sets the fill color for the rubberband. More...
 
void setIcon (IconType icon)
 Sets the icon type to highlight point geometries. More...
 
void setIconSize (int iconSize)
 Sets the size of the point icons. More...
 
void setLineStyle (Qt::PenStyle penStyle)
 Sets the style of the line. More...
 
void setSecondaryStrokeColor (const QColor &color)
 Sets a secondary stroke color for the rubberband which will be drawn under the main stroke color. More...
 
void setStrokeColor (const QColor &color)
 Sets the stroke color for the rubberband. More...
 
void setSvgIcon (const QString &path, QPoint drawOffset)
 Set the path to the svg file to use to draw points. More...
 
void setSymbol (QgsSymbol *symbol)
 Sets the symbol used for rendering the rubberband. More...
 
void setToCanvasRectangle (QRect rect)
 Sets this rubber band to a map canvas rectangle. More...
 
void setToGeometry (const QgsGeometry &geom, QgsVectorLayer *layer)
 Sets this rubber band to geom. More...
 
void setToGeometry (const QgsGeometry &geometry, const QgsCoordinateReferenceSystem &crs=QgsCoordinateReferenceSystem())
 Sets this rubber band to geometry. More...
 
void setTranslationOffset (double dx, double dy)
 Adds translation to original coordinates (all in map coordinates) More...
 
void setWidth (int width)
 Sets the width of the line. More...
 
int size () const
 Returns number of geometries. More...
 
QColor strokeColor () const
 Returns the current stroke color. More...
 
QgsSymbolsymbol () const
 Returns the symbol used for rendering the rubberband, if set. More...
 
void updatePosition () override
 called on changed extent or resize event to update position of the item More...
 
int width () const
 Returns the current width of the line or stroke width for polygon. More...
 
- Public Member Functions inherited from QgsMapCanvasItem
QRectF boundingRect () const override
 
QgsRectangle rect () const
 returns canvas item rectangle in map units More...
 
void setRect (const QgsRectangle &r, bool resetRotation=true)
 sets canvas item rectangle in map units More...
 
QPointF toCanvasCoordinates (const QgsPointXY &point) const
 transformation from map coordinates to screen coordinates More...
 
QgsPointXY toMapCoordinates (QPoint point) const
 transformation from screen coordinates to map coordinates More...
 
virtual void updatePosition ()
 called on changed extent or resize event to update position of the item More...
 

Protected Member Functions

void drawShape (QPainter *p, const QVector< QPointF > &pts)
 Draws shape of the rubber band. More...
 
void drawShape (QPainter *p, const QVector< QPolygonF > &rings)
 Draws shape of the rubber band. More...
 
void paint (QPainter *p) override
 Paints the rubber band in response to an update event. More...
 
void updateRect ()
 Recalculates needed rectangle. More...
 
- Protected Member Functions inherited from QgsMapCanvasItem
 QgsMapCanvasItem (QgsMapCanvas *mapCanvas)
 protected constructor: cannot be constructed directly More...
 
 ~QgsMapCanvasItem () override
 
virtual void paint (QPainter *painter)=0
 function to be implemented by derived classes More...
 
void paint (QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget=nullptr) override
 
bool setRenderContextVariables (QPainter *p, QgsRenderContext &context) const
 Sets render context parameters. More...
 
void updateCanvas ()
 schedules map canvas for repaint More...
 

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()) More...
 
QgsMapCanvasmMapCanvas = nullptr
 pointer to map canvas More...
 
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. More...
 
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 51 of file qgsrubberband.h.

Member Enumeration Documentation

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

Since
QGIS 3.0
ICON_FULL_DIAMOND 

A diamond is used to highlight points (◆)

Since
QGIS 3.0
ICON_SVG 

An svg image is used to highlight points.

Since
QGIS 3.10

Definition at line 82 of file qgsrubberband.h.

Constructor & Destructor Documentation

◆ QgsRubberBand()

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

Creates a new RubberBand.

Parameters
mapCanvasThe map canvas to draw onto. Its CRS will be used to map points onto screen coordinates. The ownership is transferred to this canvas.
geometryTypeDefines how the data should be drawn onto the screen. QgsWkbTypes::LineGeometry, QgsWkbTypes::PolygonGeometry or QgsWkbTypes::PointGeometry

Definition at line 31 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.

Since
QGIS 3.0

Definition at line 307 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
geometrythe geometry object. Will be treated as a collection of vertices.
layerthe 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.
doUpdateset to false to defer updates of the rubber band.

Definition at line 288 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
pThe vertex/point to add
doUpdateShould the map canvas be updated immediately?
geometryIndexThe index of the feature part (in case of multipart geometries)
ringIndexThe index of the polygon ring (in case of polygons with holes)

Definition at line 118 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 746 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
doUpdateset to true to update the map canvas immediately
geometryIndexThe index of the feature part (in case of multipart geometries)
ringIndexThe index of the polygon ring (in case of polygons with holes)
Since
QGIS 2.16

Definition at line 176 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 439 of file qgsrubberband.cpp.

◆ drawShape() [1/2]

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

Draws shape of the rubber band.

Parameters
pThe QPainter object
ptsA list of points used to draw the shape

Definition at line 547 of file qgsrubberband.cpp.

◆ drawShape() [2/2]

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

Draws shape of the rubber band.

Parameters
pThe QPainter object
ringsA list of points used to draw the shape

Definition at line 530 of file qgsrubberband.cpp.

◆ fillColor()

QColor QgsRubberBand::fillColor ( ) const
inline

Returns the current fill color.

Definition at line 162 of file qgsrubberband.h.

◆ getPoint()

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

Returns a vertex.

Parameters
iThe geometry index
jThe vertex index within ring ringIndex
ringIndexThe ring index within geometry i

Definition at line 735 of file qgsrubberband.cpp.

◆ icon()

IconType QgsRubberBand::icon ( ) const
inline

Returns the current icon type to highlight point geometries.

Definition at line 219 of file qgsrubberband.h.

◆ iconSize()

int QgsRubberBand::iconSize ( ) const
inline

Returns the current icon size of the point icons.

Definition at line 229 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 232 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 248 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 722 of file qgsrubberband.cpp.

◆ paint()

void QgsRubberBand::paint ( QPainter *  p)
overrideprotectedvirtual

Paints the rubber band in response to an update event.

Parameters
pThe QPainter object

Implements QgsMapCanvasItem.

Definition at line 447 of file qgsrubberband.cpp.

◆ partSize()

int QgsRubberBand::partSize ( int  geometryIndex) const

Returns number of vertices in feature part.

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

Definition at line 713 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 227 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
indexThe index of the vertex/point to remove, negative indexes start at end
doUpdateShould the map canvas be updated immediately?
geometryIndexThe index of the feature part (in case of multipart geometries)
ringIndexThe index of the polygon ring (in case of polygons with holes)

Definition at line 200 of file qgsrubberband.cpp.

◆ reset()

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

Clears all the geometries in this rubberband.

Sets the representation type according to geometryType.

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

Definition at line 110 of file qgsrubberband.cpp.

◆ secondaryStrokeColor()

QColor QgsRubberBand::secondaryStrokeColor ( ) const
inline

Returns the current secondary stroke color.

Definition at line 187 of file qgsrubberband.h.

◆ setBrushStyle()

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

Sets the style of the brush.

Definition at line 105 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
colorThe color used to render this rubberband

Definition at line 54 of file qgsrubberband.cpp.

◆ setFillColor()

void QgsRubberBand::setFillColor ( const QColor &  color)

Sets the fill color for the rubberband.

Parameters
colorThe color used to render this rubberband
Since
QGIS 2.6

Definition at line 60 of file qgsrubberband.cpp.

◆ setIcon()

void QgsRubberBand::setIcon ( IconType  icon)

Sets the icon type to highlight point geometries.

Parameters
iconThe icon to visualize point geometries

Definition at line 83 of file qgsrubberband.cpp.

◆ setIconSize()

void QgsRubberBand::setIconSize ( int  iconSize)

Sets the size of the point icons.

Definition at line 95 of file qgsrubberband.cpp.

◆ setLineStyle()

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

Sets the style of the line.

Definition at line 100 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
colorThe color used to render a secondary stroke color to this rubberband
Since
QGIS 3.0

Definition at line 73 of file qgsrubberband.cpp.

◆ setStrokeColor()

void QgsRubberBand::setStrokeColor ( const QColor &  color)

Sets the stroke color for the rubberband.

Parameters
colorThe color used to render this rubberband
Since
QGIS 2.6

Definition at line 68 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
pathThe path to the svg
drawOffsetThe offset where to draw the image origin
Since
QGIS 3.10

Definition at line 88 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 686 of file qgsrubberband.cpp.

◆ setToCanvasRectangle()

void QgsRubberBand::setToCanvasRectangle ( QRect  rect)

Sets this rubber band to a map canvas rectangle.

Parameters
rectrectangle in canvas coordinates

Definition at line 419 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
geomthe geometry object
layerthe 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 264 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 276 of file qgsrubberband.cpp.

◆ setTranslationOffset()

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

Adds translation to original coordinates (all in map coordinates)

Parameters
dxx translation
dyy translation

Definition at line 701 of file qgsrubberband.cpp.

◆ setWidth()

void QgsRubberBand::setWidth ( int  width)

Sets the width of the line.

Stroke width for polygon.

Parameters
widthThe width for any lines painted for this rubberband

Definition at line 78 of file qgsrubberband.cpp.

◆ size()

int QgsRubberBand::size ( ) const

Returns number of geometries.

Returns
number of geometries

Definition at line 708 of file qgsrubberband.cpp.

◆ strokeColor()

QColor QgsRubberBand::strokeColor ( ) const
inline

Returns the current stroke color.

Definition at line 174 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 681 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 691 of file qgsrubberband.cpp.

◆ updateRect()

void QgsRubberBand::updateRect ( )
protected

Recalculates needed rectangle.

Definition at line 637 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 198 of file qgsrubberband.h.

Property Documentation

◆ fillColor

QColor QgsRubberBand::fillColor
readwrite

Definition at line 51 of file qgsrubberband.h.

◆ iconSize

int QgsRubberBand::iconSize
readwrite

Definition at line 51 of file qgsrubberband.h.

◆ secondaryStrokeColor

QColor QgsRubberBand::secondaryStrokeColor
readwrite

Definition at line 51 of file qgsrubberband.h.

◆ strokeColor

QColor QgsRubberBand::strokeColor
readwrite

Definition at line 51 of file qgsrubberband.h.

◆ width

int QgsRubberBand::width
readwrite

Definition at line 51 of file qgsrubberband.h.


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