Class: QgsSymbol¶
- class qgis.core.QgsSymbol¶
Bases:
sip.wrapper
Abstract base class for all rendered symbols.
Enums
alias of
SymbolPreviewFlag
alias of
SymbolRenderHint
Bases:
enum.IntEnum
Bases:
enum.IntEnum
Methods
Returns a reference to the symbol animation settings.
Appends a symbol
layer
at the end of the current symbol layer list.Returns an image of the symbol at the specified
size
.Returns a large (roughly 100x100 pixel) preview image for the symbol.
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.Deletes the current layer at the specified
index
and replaces it withlayer
.Returns whether features drawn by the symbol will be clipped to the render context's extent.
Returns a deep copy of this symbol.
Retrieve a cloned list of all layers that make up this symbol.
Returns the symbol's color.
Returns a reference to the symbol's property collection, used for data defined overrides.
Returns a new default symbol for the specified geometry type.
Removes and deletes the symbol layer at the specified
index
.Draws an icon of the symbol that occupies an area given by
size
using the specifiedpainter
.Returns a string dump of the symbol's properties.
Export the symbol as an image format, to the specified
path
and with the givensize
.Returns flags for the symbol.
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.Returns whether the symbol utilizes any data defined properties.
Inserts a symbol
layer
to specifiedindex
.Returns the map unit scale for the symbol.
Returns the opacity for the symbol.
Returns the units to use for sizes and widths within the symbol.
Returns the symbol property definitions.
Render a feature.
Returns the rendering hint flags for the symbol.
Renders a context using a particular symbol layer without passing in a geometry.
Render editing vertex marker at specified point
Sets a the symbol animation
settings
.Sets whether features drawn by the symbol should be clipped to the render context's extent.
Sets the
color
for the symbol.Sets the symbol's property collection, used for data defined overrides.
Sets a data defined property for the symbol.
Sets
flags
for the symbol.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.
Sets the map unit
scale
for the symbol.Sets the
opacity
for the symbol.Sets the units to use for sizes and widths within the symbol.
Sets rendering hint flags for the symbol.
Called before symbol layers will be rendered for a particular
feature
.Begins the rendering process for the symbol.
Called after symbol layers have been rendered for a particular
feature
.Ends the rendering process.
Returns the symbol layer at the specified index.
Returns the total number of symbol layers contained in the symbol.
Returns the list of symbol layers contained in the symbol.
Returns the symbol render context.
Returns the default symbol type required for the specified geometry
type
.Returns a translated string version of the specified symbol
type
.Removes a symbol layer from the list and returns a pointer to it.
Converts the symbol to a SLD representation.
Returns the symbol's type.
Returns a list of attributes required to render this feature.
Returns
True
if the symbol has any components which use map unit based sizes.Attributes
- PreviewFlag¶
alias of
SymbolPreviewFlag
- PreviewFlags¶
alias of
SymbolPreviewFlags
- class Property¶
Bases:
int
- PropertyOpacity = 0¶
- RenderHint¶
alias of
SymbolRenderHint
- RenderHints¶
alias of
SymbolRenderHints
- class ScaleMethod(value)¶
Bases:
enum.IntEnum
Scale methods
New in version 3.20.
ScaleArea
: Calculate scale by the areaScaleDiameter
: Calculate scale by the diameter
- class SymbolPreviewFlags¶
- class SymbolPreviewFlags(Union[Qgis.SymbolPreviewFlags, Qgis.SymbolPreviewFlag])
- class SymbolPreviewFlags(Qgis.SymbolPreviewFlags)
Bases:
sip.wrapper
- class SymbolType(value)¶
Bases:
enum.IntEnum
Symbol types
New in version 3.20.
Marker
: Marker symbolLine
: Line symbolFill
: Fill symbolHybrid
: Hybrid symbol
- animationSettings(self) QgsSymbolAnimationSettings ¶
Returns a reference to the symbol animation settings.
See also
New in version 3.26.
- Return type:
- appendSymbolLayer(self, layer: QgsSymbolLayer) bool ¶
Appends a symbol
layer
at the end of the current symbol layer list. Ownership oflayer
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’stype()
.- 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
See also
- Parameters:
size (QSize) –
customContext (
QgsRenderContext
= None) –
- 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: 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 propertiesflags (Union[Qgis.SymbolPreviewFlags) – optional flags to control how preview image is generated
See also
See also
- 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 returnsTrue
if any of the layers returnedTrue
.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 withlayer
. Ownership oflayer
is transferred to the symbol.Returns
False
iflayer
is not compatible with the symbol’stype()
, orTrue
if the layer was successfully replaced.- Parameters:
index (int) –
layer (QgsSymbolLayer) –
- 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
See also
New in version 2.9.
- clone(self) QgsSymbol ¶
Returns a deep copy of this symbol.
Ownership is transferred to the caller.
- Return type:
- 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
- Return type:
QColor
- dataDefinedProperties(self) QgsPropertyCollection ¶
Returns a reference to the symbol’s property collection, used for data defined overrides.
See also
See also
Property
New in version 3.18.
- Return type:
- 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:
- 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 specifiedpainter
.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 happensselected (bool = False) – set to
True
to render the symbol in a selected stateexpressionContext (
QgsExpressionContext
= None) – optional custom expression contextpatchShape (
QgsLegendPatchShape
= None) – optional patch shape to use for symbol preview. If not specified a default shape will be used instead.
See also
See also
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 givensize
.If
format
is “SVG” then an SVG file will be created, otherwise a raster image of the specified format will be created.See also
See also
- Parameters:
path (str) –
format (str) –
size (QSize) –
- flags(self) Qgis.SymbolFlags ¶
Returns flags for the symbol.
See also
New in version 3.20.
- Return type:
- 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
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 specifiedindex
. Ownership oflayer
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:
- 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.
See also
- Return type:
- 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
- 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:
- Returns:
output unit, or
QgsUnitTypes
.RenderUnknownUnit if the symbol contains mixed units
See also
- 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 featuresstopRender()
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
- Return type:
- 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
andrings
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: QPointF | QPoint, context: QgsRenderContext, currentVertexMarkerType: Qgis.VertexMarkerType, currentVertexMarkerSize: float)¶
Render editing vertex marker at specified point
New in version 2.16.
- Parameters:
pt (Union[QPointF) –
context (QgsRenderContext) –
currentVertexMarkerType (Qgis.VertexMarkerType) –
currentVertexMarkerSize (float) –
- setAnimationSettings(self, settings: QgsSymbolAnimationSettings)¶
Sets a the symbol animation
settings
.See also
New in version 3.26.
- Parameters:
settings (QgsSymbolAnimationSettings) –
- 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 toTrue
)
See also
New in version 2.9.
- setColor(self, color: QColor | Qt.GlobalColor | QGradient)¶
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
- 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.
See also
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
See also
Property
New in version 3.18.
- Parameters:
key (QgsSymbol.Property) –
property (QgsProperty) –
- setFlags(self, flags: Qgis.SymbolFlags | Qgis.SymbolFlag)¶
Sets
flags
for the symbol.See also
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
New in version 3.6.
- Parameters:
force (bool) –
- setLayer(self, layer: QgsVectorLayer)¶
Note
the layer will be
None
after stopRenderDeprecated 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
- 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
- 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
- setRenderHints(self, hints: Qgis.SymbolRenderHints | Qgis.SymbolRenderHint)¶
Sets rendering hint flags for the symbol.
See also
- 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:
feature (QgsFeature) –
context (QgsRenderContext) –
layer (int = -1) –
- 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 tostopRender()
.- 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
- 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:
feature (QgsFeature) –
context (QgsRenderContext) –
layer (int = -1) –
- 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
- 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
See also
New in version 2.7.
- Parameters:
layer (int) –
- Return type:
- symbolLayerCount(self) int ¶
Returns the total number of symbol layers contained in the symbol.
- Return type:
int
- Returns:
count of symbol layers
See also
See also
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
See also
New in version 2.7.
- symbolRenderContext(self) QgsSymbolRenderContext ¶
Returns the symbol render context. Only valid between startRender and stopRender calls.
- Return type:
- 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:
- 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:
- 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:
- 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