Subgroup: Symbol

Class: QgsSymbol

class qgis.core.QgsSymbol

Bases: sip.wrapper

Abstract base class for all rendered symbols.

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

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: int = 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: int)

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

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.