QgsSymbol class

Abstract base class for all rendered symbols.

Contents

Public types

enum RenderHint { DynamicRotation = 2 }
Flags controlling behavior of symbols during rendering.
enum ScaleMethod { ScaleArea, ScaleDiameter }
Scale method.
enum SymbolType { Marker, Line, Fill, Hybrid }
Type of the symbol.

Public static functions

static auto defaultSymbol(QgsWkbTypes::GeometryType geomType) -> QgsSymbol*
Returns a new default symbol for the specified geometry type.

Public functions

auto appendSymbolLayer(QgsSymbolLayer* layer) -> bool
Appends a symbol layer at the end of the current symbol layer list.
auto asImage(QSize size, QgsRenderContext* customContext = nullptr) -> QImage
Returns an image of the symbol at the specified size.
auto bigSymbolPreviewImage(QgsExpressionContext* expressionContext = nullptr) -> QImage
Returns a large (roughly 100x100 pixel) preview image for the symbol.
auto changeSymbolLayer(int index, QgsSymbolLayer* layer) -> bool
Deletes the current layer at the specified index and replaces it with layer.
auto clipFeaturesToExtent() const -> bool
Returns whether features drawn by the symbol will be clipped to the render context's extent.
auto clone() const -> QgsSymbol* pure virtual
Returns a deep copy of this symbol.
auto color() const -> QColor
Returns the symbol's color.
auto deleteSymbolLayer(int index) -> bool
Removes and deletes the symbol layer at the specified index.
void drawPreviewIcon(QPainter* painter, QSize size, QgsRenderContext* customContext = nullptr)
Draws an icon of the symbol that occupies an area given by size using the specified painter.
auto dump() const -> QString
Returns a string dump of the symbol's properties.
void exportImage(const QString& path, const QString& format, QSize size)
Export the symbol as an image format, to the specified path and with the given size.
auto forceRHR() const -> bool
Returns true if polygon features drawn by the symbol will be reoriented to follow the standard right-hand-rule orientation, in which the area that is bounded by the polygon is to the right of the boundary.
auto hasDataDefinedProperties() const -> bool
Returns whether the symbol utilizes any data defined properties.
auto insertSymbolLayer(int index, QgsSymbolLayer* layer) -> bool
Inserts a symbol layer to specified index.
auto layer() const -> Q_DECL_DEPRECATED const QgsVectorLayer* deprecated
auto mapUnitScale() const -> QgsMapUnitScale
Returns the map unit scale for the symbol.
auto opacity() const -> qreal
Returns the opacity for the symbol.
auto outputUnit() const -> QgsUnitTypes::RenderUnit
Returns the units to use for sizes and widths within the symbol.
void renderFeature(const QgsFeature& feature, QgsRenderContext& context, int layer = -1, bool selected = false, bool drawVertexMarker = false, int currentVertexMarkerType = 0, int currentVertexMarkerSize = 0)
Render a feature.
auto renderHints() const -> RenderHints
Returns the rendering hint flags for the symbol.
void setClipFeaturesToExtent(bool clipFeaturesToExtent)
Sets whether features drawn by the symbol should be clipped to the render context's extent.
void setColor(const QColor& color)
Sets the color for the symbol.
void setForceRHR(bool force)
Sets whether polygon features drawn by the symbol should be reoriented to follow the standard right-hand-rule orientation, in which the area that is bounded by the polygon is to the right of the boundary.
auto setLayer(const QgsVectorLayer* layer) -> Q_DECL_DEPRECATED void deprecated
void setMapUnitScale(const QgsMapUnitScale& scale)
Sets the map unit scale for the symbol.
void setOpacity(qreal opacity)
Sets the opacity for the symbol.
void setOutputUnit(QgsUnitTypes::RenderUnit unit)
Sets the units to use for sizes and widths within the symbol.
void setRenderHints(RenderHints hints)
Sets rendering hint flags for the symbol.
void startRender(QgsRenderContext& context, const QgsFields& fields = QgsFields())
Begins the rendering process for the symbol.
void stopRender(QgsRenderContext& context)
Ends the rendering process.
auto symbolLayer(int layer) -> QgsSymbolLayer*
Returns a specific symbol layer contained in the symbol.
auto symbolLayerCount() const -> int
Returns the total number of symbol layers contained in the symbol.
auto symbolLayers() -> QgsSymbolLayerList
Returns the list of symbol layers contained in the symbol.
auto symbolRenderContext() -> QgsSymbolRenderContext*
Returns the symbol render context.
auto takeSymbolLayer(int index) -> QgsSymbolLayer*
Removes a symbol layer from the list and returns a pointer to it.
void toSld(QDomDocument& doc, QDomElement& element, QgsStringMap props) const
Converts the symbol to a SLD representation.
auto type() const -> SymbolType
Returns the symbol's type.
auto usedAttributes(const QgsRenderContext& context) const -> QSet<QString>
Returns a list of attributes required to render this feature.

Protected static functions

static auto _getLineString(QgsRenderContext& context, const QgsCurve& curve, bool clipToExtent = true) -> QPolygonF
Creates a line string in screen coordinates from a QgsCurve in map coordinates.
static auto _getPoint(QgsRenderContext& context, const QgsPoint& point) -> QPointF
Creates a point in screen coordinates from a QgsPoint in map coordinates.
static void _getPolygon(QPolygonF& pts, QList<QPolygonF>& holes, QgsRenderContext& context, const QgsPolygon& polygon, bool clipToExtent = true, bool correctRingOrientation = false)
Creates a polygon in screen coordinates from a QgsPolygonXYin map coordinates.
static auto _getPolygonRing(QgsRenderContext& context, const QgsCurve& curve, bool clipToExtent, bool isExteriorRing = false, bool correctRingOrientation = false) -> QPolygonF
Creates a polygon ring in screen coordinates from a QgsCurve in map coordinates.

Protected functions

auto cloneLayers() const -> QgsSymbolLayerList
Retrieve a cloned list of all layers that make up this symbol.
void renderUsingLayer(QgsSymbolLayer* layer, QgsSymbolRenderContext& context)
Renders a context using a particular symbol layer without passing in a geometry.
void renderVertexMarker(QPointF pt, QgsRenderContext& context, int currentVertexMarkerType, int currentVertexMarkerSize)
Render editing vertex marker at specified point.

Protected variables

qreal mOpacity
Symbol opacity (in the range 0 - 1)

Enum documentation

enum QgsSymbol::RenderHint

Flags controlling behavior of symbols during rendering.

Enumerators
DynamicRotation

Rotation of symbol may be changed during rendering and symbol should not be cached.

enum QgsSymbol::ScaleMethod

Scale method.

Enumerators
ScaleArea

Calculate scale by the area.
ScaleDiameter

Calculate scale by the diameter.

enum QgsSymbol::SymbolType

Type of the symbol.

Enumerators
Marker

Marker symbol.
Line

Line symbol.
Fill

Fill symbol.
Hybrid

Hybrid symbol.

Function documentation

static QgsSymbol* QgsSymbol::defaultSymbol(QgsWkbTypes::GeometryType geomType)

Returns a new default symbol for the specified geometry type.

The caller takes ownership of the returned object.

bool QgsSymbol::appendSymbolLayer(QgsSymbolLayer* layer)

Appends a symbol layer at the end of the current symbol layer list.

Returns true if the layer was successfully added, false if the layer is not compatible with the symbol's type().

Ownership of layer is transferred to the symbol.

QImage QgsSymbol::asImage(QSize size, QgsRenderContext* customContext = nullptr)

Returns an image of the symbol at the specified size.

Optionally a custom render context may be given in order to ensure that the preview icon exactly matches the settings from that context.

QImage QgsSymbol::bigSymbolPreviewImage(QgsExpressionContext* expressionContext = nullptr)

Returns a large (roughly 100x100 pixel) preview image for the symbol.

Parameters
expressionContext optional expression context, for evaluation of data defined symbol properties

bool QgsSymbol::changeSymbolLayer(int index, QgsSymbolLayer* layer)

Deletes the current layer at the specified index and replaces it with layer.

Ownership of layer is transferred to the symbol.

Returns false if layer is not compatible with the symbol's type(), or true if the layer was successfully replaced.

bool QgsSymbol::clipFeaturesToExtent() const

Returns whether features drawn by the symbol will be clipped to the render context's extent.

Returns true if features will be clipped

If this option is enabled then features which are partially outside the extent will be clipped. This speeds up rendering of the feature, but may have undesirable side effects for certain symbol types.

QgsSymbol* QgsSymbol::clone() const pure virtual

Returns a deep copy of this symbol.

Ownership is transferred to the caller.

QColor QgsSymbol::color() const

Returns the symbol's color.

For multi-layer symbols, this method returns the color of the first unlocked symbol layer.

void QgsSymbol::drawPreviewIcon(QPainter* painter, QSize size, QgsRenderContext* customContext = nullptr)

Draws an icon of the symbol that occupies an area given by size using the specified painter.

Optionally a custom render context may be given in order to ensure that the preview icon exactly matches the settings from that context.

void QgsSymbol::exportImage(const QString& path, const QString& format, QSize size)

Export the symbol as an image format, to the specified path and with the given size.

If format is "SVG" then an SVG file will be created, otherwise a raster image of the specified format will be created.

bool QgsSymbol::forceRHR() const

Returns true if polygon features drawn by the symbol will be reoriented to follow the standard right-hand-rule orientation, in which the area that is bounded by the polygon is to the right of the boundary.

In particular, the exterior ring is oriented in a clockwise direction and the interior rings in a counter-clockwise direction.

bool QgsSymbol::hasDataDefinedProperties() const

Returns whether the symbol utilizes any data defined properties.

bool QgsSymbol::insertSymbolLayer(int index, QgsSymbolLayer* layer)

Inserts a symbol layer to specified index.

Parameters
index The index at which the layer should be added
layer The symbol layer to add
Returns True if the layer is added, False if the index or the layer is bad

Ownership of layer is transferred to the symbol.

Q_DECL_DEPRECATED const QgsVectorLayer* QgsSymbol::layer() const

QgsMapUnitScale QgsSymbol::mapUnitScale() const

Returns the map unit scale for the symbol.

If the symbol consists of multiple layers, the map unit scale is only returned if all layers have the same scale settings. If the settings differ, a default constructed map unit scale is returned.

qreal QgsSymbol::opacity() const

Returns the opacity for the symbol.

Returns opacity value between 0 (fully transparent) and 1 (fully opaque)

QgsUnitTypes::RenderUnit QgsSymbol::outputUnit() const

Returns the units to use for sizes and widths within the symbol.

Returns output unit, or QgsUnitTypes::RenderUnknownUnit if the symbol contains mixed units

Individual symbol layer definitions will interpret this in different ways, e.g., a marker symbol may use it to specify the units for the marker size, while a line symbol may use it to specify the units for the line width.

void QgsSymbol::renderFeature(const QgsFeature& feature, QgsRenderContext& context, int layer = -1, bool selected = false, bool drawVertexMarker = false, int currentVertexMarkerType = 0, int currentVertexMarkerSize = 0)

Render a feature.

Before calling this the startRender() method should be called to initialize the rendering process. After rendering all features stopRender() must be called.

RenderHints QgsSymbol::renderHints() const

Returns the rendering hint flags for the symbol.

void QgsSymbol::setClipFeaturesToExtent(bool clipFeaturesToExtent)

Sets whether features drawn by the symbol should be clipped to the render context's extent.

Parameters
clipFeaturesToExtent set to true to enable clipping (defaults to true)

If this option is enabled then features which are partially outside the extent will be clipped. This speeds up rendering of the feature, but may have undesirable side effects for certain symbol types.

void QgsSymbol::setColor(const QColor& color)

Sets the color for the symbol.

Calling this method sets the color for each individual symbol layer contained within the symbol to color.

Locked symbol layers are skipped and are left unchanged.

void QgsSymbol::setForceRHR(bool force)

Sets whether polygon features drawn by the symbol should be reoriented to follow the standard right-hand-rule orientation, in which the area that is bounded by the polygon is to the right of the boundary.

In particular, the exterior ring is oriented in a clockwise direction and the interior rings in a counter-clockwise direction.

Q_DECL_DEPRECATED void QgsSymbol::setLayer(const QgsVectorLayer* layer)

void QgsSymbol::setMapUnitScale(const QgsMapUnitScale& scale)

Sets the map unit scale for the symbol.

Calling this method sets the scale for all symbol layers contained within the symbol.

void QgsSymbol::setOpacity(qreal opacity)

Sets the opacity for the symbol.

Parameters
opacity opacity value between 0 (fully transparent) and 1 (fully opaque)

void QgsSymbol::setOutputUnit(QgsUnitTypes::RenderUnit unit)

Sets the units to use for sizes and widths within the symbol.

Parameters
unit output units

Individual symbol definitions will interpret this in different ways, e.g., a marker symbol may use it to specify the units for the marker size, while a line symbol may use it to specify the units for the line width.

void QgsSymbol::setRenderHints(RenderHints hints)

Sets rendering hint flags for the symbol.

void QgsSymbol::startRender(QgsRenderContext& context, const QgsFields& fields = QgsFields())

Begins the rendering process for the symbol.

Parameters
context render context which symbol will be drawn using
fields fields for features to be rendered (usually the associated vector layer's fields). Required for correct calculation of data defined overrides.

This must be called before renderFeature(), and should be followed by a call to stopRender().

void QgsSymbol::stopRender(QgsRenderContext& context)

Ends the rendering process.

Parameters
context render context, must match the context specified when startRender() was called.

This should be called after rendering all desired features.

QgsSymbolLayer* QgsSymbol::symbolLayer(int layer)

Returns a specific symbol layer contained in the symbol.

Parameters
layer layer number
Returns corresponding symbol layer

int QgsSymbol::symbolLayerCount() const

Returns the total number of symbol layers contained in the symbol.

Returns count of symbol layers

QgsSymbolLayerList QgsSymbol::symbolLayers()

Returns the list of symbol layers contained in the symbol.

Returns symbol layers list

QgsSymbolRenderContext* QgsSymbol::symbolRenderContext()

Returns the symbol render context.

Returns The symbol render context

Only valid between startRender and stopRender calls.

QgsSymbolLayer* QgsSymbol::takeSymbolLayer(int index)

Removes a symbol layer from the list and returns a pointer to it.

Parameters
index The index of the layer to remove
Returns A pointer to the removed layer

Ownership of the layer is handed to the caller.

QSet<QString> QgsSymbol::usedAttributes(const QgsRenderContext& context) const

Returns a list of attributes required to render this feature.

This should include any attributes required by the symbology including the ones required by expressions.

static void QgsSymbol::_getPolygon(QPolygonF& pts, QList<QPolygonF>& holes, QgsRenderContext& context, const QgsPolygon& polygon, bool clipToExtent = true, bool correctRingOrientation = false) protected

Creates a polygon in screen coordinates from a QgsPolygonXYin map coordinates.

If correctRingOrientation is true then the ring will be oriented to match standard ring orientation, e.g. clockwise for exterior rings and counter-clockwise for interior rings.

static QPolygonF QgsSymbol::_getPolygonRing(QgsRenderContext& context, const QgsCurve& curve, bool clipToExtent, bool isExteriorRing = false, bool correctRingOrientation = false) protected

Creates a polygon ring in screen coordinates from a QgsCurve in map coordinates.

If correctRingOrientation is true then the ring will be oriented to match standard ring orientation, e.g. clockwise for exterior rings and counter-clockwise for interior rings.

QgsSymbolLayerList QgsSymbol::cloneLayers() const protected

Retrieve a cloned list of all layers that make up this symbol.

Ownership is transferred to the caller.

void QgsSymbol::renderUsingLayer(QgsSymbolLayer* layer, QgsSymbolRenderContext& context) protected

Renders a context using a particular symbol layer without passing in a geometry.

This is used as fallback, if the symbol being rendered is not compatible with the specified layer. In such a case, this method can be called and will call the layer's rendering method anyway but the geometry passed to the layer will be empty. This is required for layers that generate their own geometry from other information in the rendering context.

void QgsSymbol::renderVertexMarker(QPointF pt, QgsRenderContext& context, int currentVertexMarkerType, int currentVertexMarkerSize) protected

Render editing vertex marker at specified point.