Class: QgsSymbol

class qgis.core.QgsSymbol

Bases: sip.wrapper

Abstract base class for all rendered symbols.

Enums

PreviewFlag

alias of qgis._core.Qgis.SymbolPreviewFlag

RenderHint

alias of qgis._core.Qgis.SymbolRenderHint

ScaleMethod

Bases: enum.IntEnum

SymbolType

Bases: enum.IntEnum

Methods

appendSymbolLayer

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

asImage

Returns an image of the symbol at the specified size.

bigSymbolPreviewImage

bigSymbolPreviewImageV2

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

canCauseArtifactsBetweenAdjacentTiles

Returns True if the symbol rendering can cause visible artifacts across a single feature when the feature is rendered as a series of adjacent map tiles each containing a portion of the feature’s geometry.

changeSymbolLayer

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

clipFeaturesToExtent

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

clone

Returns a deep copy of this symbol.

cloneLayers

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

color

Returns the symbol’s color.

dataDefinedProperties

Returns a reference to the symbol’s property collection, used for data defined overrides.

defaultSymbol

Returns a new default symbol for the specified geometry type.

deleteSymbolLayer

Removes and deletes the symbol layer at the specified index.

drawPreviewIcon

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

dump

Returns a string dump of the symbol’s properties.

exportImage

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

flags

Returns flags for the symbol.

forceRHR

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.

hasDataDefinedProperties

Returns whether the symbol utilizes any data defined properties.

insertSymbolLayer

Inserts a symbol layer to specified index.

layer

mapUnitScale

Returns the map unit scale for the symbol.

opacity

Returns the opacity for the symbol.

outputUnit

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

propertyDefinitions

Returns the symbol property definitions.

renderFeature

Render a feature.

renderHints

Returns the rendering hint flags for the symbol.

renderUsingLayer

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

renderVertexMarker

Render editing vertex marker at specified point

setClipFeaturesToExtent

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

setColor

Sets the color for the symbol.

setDataDefinedProperties

Sets the symbol’s property collection, used for data defined overrides.

setDataDefinedProperty

Sets a data defined property for the symbol.

setFlags

Sets flags for the symbol.

setForceRHR

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.

setLayer

setMapUnitScale

Sets the map unit scale for the symbol.

setOpacity

Sets the opacity for the symbol.

setOutputUnit

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

setRenderHints

Sets rendering hint flags for the symbol.

startFeatureRender

Called before symbol layers will be rendered for a particular feature.

startRender

Begins the rendering process for the symbol.

stopFeatureRender

Called after symbol layers have been rendered for a particular feature.

stopRender

Ends the rendering process.

symbolLayer

Returns the symbol layer at the specified index.

symbolLayerCount

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

symbolLayers

Returns the list of symbol layers contained in the symbol.

symbolRenderContext

Returns the symbol render context.

symbolTypeForGeometryType

Returns the default symbol type required for the specified geometry type.

symbolTypeToString

Returns a translated string version of the specified symbol type.

takeSymbolLayer

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

toSld

Converts the symbol to a SLD representation.

type

Returns the symbol’s type.

usedAttributes

Returns a list of attributes required to render this feature.

usesMapUnits

Returns True if the symbol has any components which use map unit based sizes.

Attributes

PropertyOpacity

PreviewFlag

alias of qgis._core.Qgis.SymbolPreviewFlag

PreviewFlags

alias of qgis._core.Qgis.SymbolPreviewFlags

class Property

Bases: int

PropertyOpacity = 0
RenderHint

alias of qgis._core.Qgis.SymbolRenderHint

RenderHints

alias of qgis._core.Qgis.SymbolRenderHints

class ScaleMethod(value)

Bases: enum.IntEnum

Scale methods

New in version 3.20.

  • ScaleArea: Calculate scale by the area

  • ScaleDiameter: Calculate scale by the diameter

baseClass

alias of qgis._core.Qgis

class SymbolType(value)

Bases: enum.IntEnum

Symbol types

New in version 3.20.

  • Marker: Marker symbol

  • Line: Line symbol

  • Fill: Fill symbol

  • Hybrid: Hybrid symbol

baseClass

alias of qgis._core.Qgis

appendSymbolLayer(self, layer: QgsSymbolLayer) bool

Appends a symbol layer at the end of the current symbol layer list. Ownership of layer is transferred to the symbol.

Return type

bool

Returns

True if the layer was successfully added, False if the layer is not compatible with the symbol’s type().

Parameters

layer (QgsSymbolLayer) –

asImage(self, size: QSize, customContext: QgsRenderContext = None) QImage

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.

See also

exportImage()

Parameters
Return type

QImage

bigSymbolPreviewImage(self, expressionContext: QgsExpressionContext = None, flags: int = static_cast<int>(Qgis.SymbolPreviewFlag.FlagIncludeCrosshairsForMarkerSymbols)) QImage

Deprecated since version use: bigSymbolPreviewImageV2 instead.

Parameters
  • expressionContext (QgsExpressionContext = None) –

  • flags (int = static_cast<int>(Qgis.SymbolPreviewFlag.FlagIncludeCrosshairsForMarkerSymbols)) –

Return type

QImage

bigSymbolPreviewImageV2(self, expressionContext: QgsExpressionContext = None, flags: Union[Qgis.SymbolPreviewFlags, Qgis.SymbolPreviewFlag] = Qgis.SymbolPreviewFlag.FlagIncludeCrosshairsForMarkerSymbols) QImage

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

Parameters
  • expressionContext (QgsExpressionContext = None) – optional expression context, for evaluation of data defined symbol properties

  • flags (Union[Qgis.SymbolPreviewFlags) – optional flags to control how preview image is generated

See also

asImage()

Return type

QImage

canCauseArtifactsBetweenAdjacentTiles(self) bool

Returns True if the symbol rendering can cause visible artifacts across a single feature when the feature is rendered as a series of adjacent map tiles each containing a portion of the feature’s geometry.

Internally this calls QgsSymbolLayer.canCauseArtifactsBetweenAdjacentTiles() for all symbol layers in the symbol and returns True if any of the layers returned True.

New in version 3.18.

Return type

bool

changeSymbolLayer(self, index: int, layer: QgsSymbolLayer) bool

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.

Parameters
Return type

bool

clipFeaturesToExtent(self) bool

Returns whether features drawn by the symbol will be clipped to the render context’s extent. 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.

Return type

bool

Returns

True if features will be clipped

New in version 2.9.

clone(self) QgsSymbol

Returns a deep copy of this symbol.

Ownership is transferred to the caller.

Return type

QgsSymbol

cloneLayers(self) List[QgsSymbolLayer]

Retrieve a cloned list of all layers that make up this symbol. Ownership is transferred to the caller.

Return type

List[QgsSymbolLayer]

color(self) QColor

Returns the symbol’s color.

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

See also

setColor()

Return type

QColor

dataDefinedProperties(self) QgsPropertyCollection

Returns a reference to the symbol’s property collection, used for data defined overrides.

See also

Property

New in version 3.18.

Return type

QgsPropertyCollection

defaultSymbol(geomType: QgsWkbTypes.GeometryType) QgsSymbol

Returns a new default symbol for the specified geometry type.

The caller takes ownership of the returned object.

Parameters

geomType (QgsWkbTypes.GeometryType) –

Return type

QgsSymbol

deleteSymbolLayer(self, index: int) bool

Removes and deletes the symbol layer at the specified index.

Parameters

index (int) –

Return type

bool

drawPreviewIcon(self, painter: QPainter, size: QSize, customContext: QgsRenderContext = None, selected: bool = False, expressionContext: QgsExpressionContext = None, patchShape: QgsLegendPatchShape = None)

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.

Parameters
  • painter (QPainter) – destination painter

  • size (QSize) – size of the icon

  • customContext (QgsRenderContext = None) – the context in which the rendering happens

  • selected (bool = False) – set to True to render the symbol in a selected state

  • expressionContext (QgsExpressionContext = None) – optional custom expression context

  • patchShape (QgsLegendPatchShape = None) – optional patch shape to use for symbol preview. If not specified a default shape will be used instead.

See also

exportImage()

See also

asImage()

Note

Parameter selected added in QGIS 3.10

New in version 2.6.

dump(self) str

Returns a string dump of the symbol’s properties.

Return type

str

exportImage(self, path: str, format: str, size: QSize)

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.

See also

asImage()

Parameters
  • path (str) –

  • format (str) –

  • size (QSize) –

flags(self) Qgis.SymbolFlags

Returns flags for the symbol.

See also

setFlags()

New in version 3.20.

Return type

Qgis.SymbolFlags

forceRHR(self) 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. In particular, the exterior ring is oriented in a clockwise direction and the interior rings in a counter-clockwise direction.

See also

setForceRHR()

New in version 3.6.

Return type

bool

hasDataDefinedProperties(self) bool

Returns whether the symbol utilizes any data defined properties.

New in version 2.12.

Return type

bool

insertSymbolLayer(self, index: int, layer: QgsSymbolLayer) bool

Inserts a symbol layer to specified index. Ownership of layer is transferred to the symbol.

Parameters
  • index (int) – The index at which the layer should be added

  • layer (QgsSymbolLayer) – The symbol layer to add

Return type

bool

Returns

True if the layer is added, False if the index or the layer is bad

layer(self) QgsVectorLayer

Deprecated since version Will: be removed in QGIS 4.0

Return type

QgsVectorLayer

mapUnitScale(self) QgsMapUnitScale

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.

Return type

QgsMapUnitScale

opacity(self) float

Returns the opacity for the symbol.

Return type

float

Returns

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

See also

setOpacity()

outputUnit(self) QgsUnitTypes.RenderUnit

Returns the units to use for sizes and widths within the symbol. 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.

Return type

QgsUnitTypes.RenderUnit

Returns

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

See also

setOutputUnit()

propertyDefinitions() Dict[int, QgsPropertyDefinition]

Returns the symbol property definitions.

New in version 3.18.

Return type

Dict[int, QgsPropertyDefinition]

renderFeature(self, feature: QgsFeature, context: QgsRenderContext, layer: int = - 1, selected: bool = False, drawVertexMarker: bool = False, currentVertexMarkerType: Qgis.VertexMarkerType = Qgis.VertexMarkerType.SemiTransparentCircle, currentVertexMarkerSize: float = 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.

Parameters
  • feature (QgsFeature) –

  • context (QgsRenderContext) –

  • layer (int = -1) –

  • selected (bool = False) –

  • drawVertexMarker (bool = False) –

  • currentVertexMarkerType (Qgis.VertexMarkerType = Qgis.VertexMarkerType.SemiTransparentCircle) –

  • currentVertexMarkerSize (float = 0) –

renderHints(self) Qgis.SymbolRenderHints

Returns the rendering hint flags for the symbol.

See also

setRenderHints()

Return type

Qgis.SymbolRenderHints

renderUsingLayer(self, layer: QgsSymbolLayer, context: QgsSymbolRenderContext, geometryType: QgsWkbTypes.GeometryType = QgsWkbTypes.GeometryType.UnknownGeometry, points: QPolygonF = None, rings: Iterable[QPolygonF] = [])

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.

Since QGIS 3.22, the optional geometryType, points and rings arguments can specify the original geometry type, points and rings in which are being rendered by the parent symbol.

Parameters
  • layer (QgsSymbolLayer) –

  • context (QgsSymbolRenderContext) –

  • geometryType (QgsWkbTypes.GeometryType = QgsWkbTypes.GeometryType.UnknownGeometry) –

  • points (QPolygonF = None) –

  • rings (Iterable[QPolygonF] = []) –

renderVertexMarker(self, pt: Union[QPointF, QPoint], context: QgsRenderContext, currentVertexMarkerType: Qgis.VertexMarkerType, currentVertexMarkerSize: float)

Render editing vertex marker at specified point

New in version 2.16.

Parameters
setClipFeaturesToExtent(self, clipFeaturesToExtent: bool)

Sets whether features drawn by the symbol should be clipped to the render context’s extent. 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.

Parameters

clipFeaturesToExtent (bool) – set to True to enable clipping (defaults to True)

New in version 2.9.

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

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.

See also

color()

Parameters

color (Union[QColor) –

setDataDefinedProperties(self, collection: QgsPropertyCollection)

Sets the symbol’s property collection, used for data defined overrides.

Parameters

collection (QgsPropertyCollection) – property collection. Existing properties will be replaced.

New in version 3.18.

setDataDefinedProperty(self, key: QgsSymbol.Property, property: QgsProperty)

Sets a data defined property for the symbol. Any existing property with the same key will be overwritten.

See also

Property

New in version 3.18.

Parameters
setFlags(self, flags: Union[Qgis.SymbolFlags, Qgis.SymbolFlag])

Sets flags for the symbol.

See also

flags()

New in version 3.320.

Parameters

flags (Union[Qgis.SymbolFlags) –

setForceRHR(self, force: bool)

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.

See also

forceRHR()

New in version 3.6.

Parameters

force (bool) –

setLayer(self, layer: QgsVectorLayer)

Note

the layer will be None after stopRender

Deprecated since version Will: be removed in QGIS 4.0

Parameters

layer (QgsVectorLayer) –

setMapUnitScale(self, scale: QgsMapUnitScale)

Sets the map unit scale for the symbol.

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

See also

mapUnitScale()

Parameters

scale (QgsMapUnitScale) –

setOpacity(self, opacity: float)

Sets the opacity for the symbol.

Parameters

opacity (float) – opacity value between 0 (fully transparent) and 1 (fully opaque)

See also

opacity()

setOutputUnit(self, unit: QgsUnitTypes.RenderUnit)

Sets the units to use for sizes and widths within the symbol. 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.

Parameters

unit (QgsUnitTypes.RenderUnit) – output units

See also

outputUnit()

setRenderHints(self, hints: Union[Qgis.SymbolRenderHints, Qgis.SymbolRenderHint])

Sets rendering hint flags for the symbol.

See also

renderHints()

Parameters

hints (Union[Qgis.SymbolRenderHints) –

startFeatureRender(self, feature: QgsFeature, context: QgsRenderContext, layer: int = - 1)

Called before symbol layers will be rendered for a particular feature.

This is always followed by a call to stopFeatureRender() after the feature has been completely rendered (i.e. all parts have been rendered).

Internally, this notifies all symbol layers which will be used via a call to QgsSymbolLayer.startFeatureRender().

New in version 3.20.

Parameters
startRender(self, context: QgsRenderContext, fields: QgsFields = QgsFields())

Begins the rendering process for the symbol. This must be called before renderFeature(), and should be followed by a call to stopRender().

Parameters
  • context (QgsRenderContext) – render context which symbol will be drawn using

  • fields (QgsFields = QgsFields()) – fields for features to be rendered (usually the associated vector layer’s fields). Required for correct calculation of data defined overrides.

See also

stopRender()

stopFeatureRender(self, feature: QgsFeature, context: QgsRenderContext, layer: int = - 1)

Called after symbol layers have been rendered for a particular feature.

This is always preceded by a call to startFeatureRender() just before the feature will be rendered.

Internally, this notifies all symbol layers which were used via a call to QgsSymbolLayer.stopFeatureRender().

New in version 3.20.

Parameters
stopRender(self, context: QgsRenderContext)

Ends the rendering process. This should be called after rendering all desired features.

Parameters

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

See also

startRender()

symbolLayer(self, layer: int) QgsSymbolLayer

Returns the symbol layer at the specified index.

Raises

IndexError – if no layer with the specified index exists.

See also

symbolLayers()

New in version 2.7.

Parameters

layer (int) –

Return type

QgsSymbolLayer

symbolLayerCount(self) int

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

Return type

int

Returns

count of symbol layers

See also

symbolLayers()

See also

symbolLayer()

New in version 2.7.

symbolLayers(self) List[QgsSymbolLayer]

Returns the list of symbol layers contained in the symbol.

Return type

List[QgsSymbolLayer]

Returns

symbol layers list

See also

symbolLayer()

New in version 2.7.

symbolRenderContext(self) QgsSymbolRenderContext

Returns the symbol render context. Only valid between startRender and stopRender calls.

Return type

QgsSymbolRenderContext

Returns

The symbol render context

symbolTypeForGeometryType(type: QgsWkbTypes.GeometryType) Qgis.SymbolType

Returns the default symbol type required for the specified geometry type.

New in version 3.20.

Parameters

type (QgsWkbTypes.GeometryType) –

Return type

Qgis.SymbolType

symbolTypeToString(type: Qgis.SymbolType) str

Returns a translated string version of the specified symbol type.

New in version 3.20.

Parameters

type (Qgis.SymbolType) –

Return type

str

takeSymbolLayer(self, index: int) QgsSymbolLayer

Removes a symbol layer from the list and returns a pointer to it. Ownership of the layer is handed to the caller.

Parameters

index (int) – The index of the layer to remove

Return type

QgsSymbolLayer

Returns

A pointer to the removed layer

toSld(self, doc: QDomDocument, element: QDomElement, props: Dict[str, Any])

Converts the symbol to a SLD representation.

Parameters
  • doc (QDomDocument) –

  • element (QDomElement) –

  • props (Dict[str) –

type(self) Qgis.SymbolType

Returns the symbol’s type.

Return type

Qgis.SymbolType

usedAttributes(self, context: QgsRenderContext) Set[str]

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.

Parameters

context (QgsRenderContext) –

Return type

Set[str]

usesMapUnits(self) bool

Returns True if the symbol has any components which use map unit based sizes.

New in version 3.18.

Return type

bool