Class: QgsSymbol

class qgis.core.QgsSymbol

Bases: sip.wrapper

Abstract base class for all rendered symbols.

Enums

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

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

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.

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.

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

Deprecated since version Will: be removed in QGIS 4.0

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.

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.

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.

startRender

Begins the rendering process for the symbol.

stopRender

Ends the rendering process.

symbolLayer

Returns a specific symbol layer contained in the symbol.

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.

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.

Signals

Attributes

DynamicRotation

Fill

Hybrid

Line

Marker

ScaleArea

ScaleDiameter

DynamicRotation = 2
Fill = 2
Hybrid = 3
Line = 1
Marker = 0
class RenderHint

Bases: int

class RenderHints

Bases: sip.wrapper

QgsSymbol.RenderHints(Union[QgsSymbol.RenderHints, QgsSymbol.RenderHint]) QgsSymbol.RenderHints(QgsSymbol.RenderHints)

ScaleArea = 0
ScaleDiameter = 1
class ScaleMethod

Bases: int

class SymbolType

Bases: int

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.

Returns

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

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

bigSymbolPreviewImage(self, expressionContext: QgsExpressionContext = None) → QImage

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

Parameters

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

See also

asImage()

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.

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.

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.

cloneLayers(self) → object

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

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

defaultSymbol(geomType: QgsWkbTypes.GeometryType) → QgsSymbol

Returns a new default symbol for the specified geometry type.

The caller takes ownership of the returned object.

deleteSymbolLayer(self, index: int) → bool

Removes and deletes the symbol layer at the specified index.

drawPreviewIcon(self, painter: QPainter, size: QSize, customContext: QgsRenderContext = 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.

See also

exportImage()

See also

asImage()

New in version 2.6.

dump(self) → str

Returns a string dump of the symbol’s properties.

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

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.4.3.

hasDataDefinedProperties(self) → bool

Returns whether the symbol utilizes any data defined properties.

New in version 2.12.

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

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

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

layer(self) → QgsVectorLayer

Deprecated since version Will: be removed in QGIS 4.0

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.

opacity(self) → float

Returns the opacity for the symbol.

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.

Returns

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

See also

setOutputUnit()

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

renderHints(self) → QgsSymbol.RenderHints

Returns the rendering hint flags for the symbol.

See also

setRenderHints()

renderUsingLayer(self, layer: QgsSymbolLayer, context: QgsSymbolRenderContext)

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.

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

Render editing vertex marker at specified point

New in version 2.16.

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

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.4.3.

setLayer(self, layer: QgsVectorLayer)

Note

the layer will be NULL after stopRender

Deprecated since version Will: be removed in QGIS 4.0

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

setOpacity(self, opacity: float)

Sets the opacity for the symbol.

Parameters

opacity – 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 – output units

See also

outputUnit()

setRenderHints(self, hints: Union[QgsSymbol.RenderHints, QgsSymbol.RenderHint])

Sets rendering hint flags for the symbol.

See also

renderHints()

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 – 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.

See also

stopRender()

stopRender(self, context: QgsRenderContext)

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

Parameters

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

See also

startRender()

symbolLayer(self, layer: int) → QgsSymbolLayer

Returns a specific symbol layer contained in the symbol.

Parameters

layer – layer number

Returns

corresponding symbol layer

See also

symbolLayers()

New in version 2.7.

symbolLayerCount(self) → int

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

Returns

count of symbol layers

See also

symbolLayers()

See also

symbolLayer()

New in version 2.7.

symbolLayers(self) → object

Returns the list of symbol layers contained in the symbol.

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.

Returns

The symbol render context

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 – The index of the layer to remove

Returns

A pointer to the removed layer

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

Converts the symbol to a SLD representation.

type(self) → QgsSymbol.SymbolType

Returns the symbol’s type.

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.