QgsSymbol Class Reference

Abstract base class for all rendered symbols. More...

#include <qgssymbol.h>

Inheritance diagram for QgsSymbol:

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

Public Member Functions
virtual	~QgsSymbol ()
bool	appendSymbolLayer (QgsSymbolLayer *layer)
	Appends a symbol layer at the end of the current symbol layer list. More...
QImage	asImage (QSize size, QgsRenderContext *customContext=nullptr)
	Returns an image of the symbol at the specified size. More...
QImage	bigSymbolPreviewImage (QgsExpressionContext *expressionContext=nullptr)
	Returns a large (roughly 100x100 pixel) preview image for the symbol. More...
bool	changeSymbolLayer (int index, QgsSymbolLayer *layer)
	Deletes the current layer at the specified index and replaces it with layer. More...
bool	clipFeaturesToExtent () const
	Returns whether features drawn by the symbol will be clipped to the render context's extent. More...
virtual QgsSymbol *	clone () const =0
	Returns a deep copy of this symbol. More...
QColor	color () const
	Returns the symbol's color. More...
bool	deleteSymbolLayer (int index)
	Removes and deletes the symbol layer at the specified index. More...
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. More...
QString	dump () const
	Returns a string dump of the symbol's properties. More...
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. More...
bool	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. More...
bool	hasDataDefinedProperties () const
	Returns whether the symbol utilizes any data defined properties. More...
bool	insertSymbolLayer (int index, QgsSymbolLayer *layer)
	Inserts a symbol layer to specified index. More...
Q_DECL_DEPRECATED const QgsVectorLayer *	layer () const
QgsMapUnitScale	mapUnitScale () const
	Returns the map unit scale for the symbol. More...
qreal	opacity () const
	Returns the opacity for the symbol. More...
QgsUnitTypes::RenderUnit	outputUnit () const
	Returns the units to use for sizes and widths within the symbol. More...
void	renderFeature (const QgsFeature &feature, QgsRenderContext &context, int layer=-1, bool selected=false, bool drawVertexMarker=false, int currentVertexMarkerType=0, double currentVertexMarkerSize=0.0) SIP_THROW(QgsCsException)
	Render a feature. More...
RenderHints	renderHints () const
	Returns the rendering hint flags for the symbol. More...
void	setClipFeaturesToExtent (bool clipFeaturesToExtent)
	Sets whether features drawn by the symbol should be clipped to the render context's extent. More...
void	setColor (const QColor &color)
	Sets the color for the symbol. More...
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. More...
Q_DECL_DEPRECATED void	setLayer (const QgsVectorLayer *layer)
void	setMapUnitScale (const QgsMapUnitScale &scale)
	Sets the map unit scale for the symbol. More...
void	setOpacity (qreal opacity)
	Sets the opacity for the symbol. More...
void	setOutputUnit (QgsUnitTypes::RenderUnit unit)
	Sets the units to use for sizes and widths within the symbol. More...
void	setRenderHints (RenderHints hints)
	Sets rendering hint flags for the symbol. More...
void	startRender (QgsRenderContext &context, const QgsFields &fields=QgsFields())
	Begins the rendering process for the symbol. More...
void	stopRender (QgsRenderContext &context)
	Ends the rendering process. More...
QgsSymbolLayer *	symbolLayer (int layer)
	Returns a specific symbol layer contained in the symbol. More...
int	symbolLayerCount () const
	Returns the total number of symbol layers contained in the symbol. More...
QgsSymbolLayerList	symbolLayers ()
	Returns the list of symbol layers contained in the symbol. More...
QgsSymbolRenderContext *	symbolRenderContext ()
	Returns the symbol render context. More...
QgsSymbolLayer *	takeSymbolLayer (int index)
	Removes a symbol layer from the list and returns a pointer to it. More...
void	toSld (QDomDocument &doc, QDomElement &element, QgsStringMap props) const
	Converts the symbol to a SLD representation. More...
SymbolType	type () const
	Returns the symbol's type. More...
QSet< QString >	usedAttributes (const QgsRenderContext &context) const
	Returns a list of attributes required to render this feature. More...

Static Public Member Functions
static QgsSymbol *	defaultSymbol (QgsWkbTypes::GeometryType geomType)
	Returns a new default symbol for the specified geometry type. More...

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

Static Protected Member Functions
static QPolygonF	_getLineString (QgsRenderContext &context, const QgsCurve &curve, bool clipToExtent=true)
	Creates a line string in screen coordinates from a QgsCurve in map coordinates. More...
static QPointF	_getPoint (QgsRenderContext &context, const QgsPoint &point)
	Creates a point in screen coordinates from a QgsPoint in map coordinates. More...
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. More...
static QPolygonF	_getPolygonRing (QgsRenderContext &context, const QgsCurve &curve, bool clipToExtent, bool isExteriorRing=false, bool correctRingOrientation=false)
	Creates a polygon ring in screen coordinates from a QgsCurve in map coordinates. More...

Protected Attributes
bool	mClipFeaturesToExtent = true
bool	mForceRHR = false
Q_DECL_DEPRECATED const QgsVectorLayer *	mLayer = nullptr
QgsSymbolLayerList	mLayers
qreal	mOpacity = 1.0
	Symbol opacity (in the range 0 - 1) More...
RenderHints	mRenderHints = nullptr
SymbolType	mType

Friends
class	QgsFeatureRenderer

Detailed Description

Abstract base class for all rendered symbols.

Definition at line 61 of file qgssymbol.h.

Member Enumeration Documentation

enum QgsSymbol::RenderHint

Flags controlling behavior of symbols during rendering.

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

Definition at line 102 of file qgssymbol.h.

enum QgsSymbol::ScaleMethod

Scale method.

Enumerator
ScaleArea	Calculate scale by the area.
ScaleDiameter	Calculate scale by the diameter.

Definition at line 94 of file qgssymbol.h.

enum QgsSymbol::SymbolType

Type of the symbol.

Enumerator
Marker	Marker symbol.
Line	Line symbol.
Fill	Fill symbol.
Hybrid	Hybrid symbol.

Definition at line 83 of file qgssymbol.h.

Constructor & Destructor Documentation

QgsSymbol::~QgsSymbol ( )

virtual

Definition at line 208 of file qgssymbol.cpp.

Q_NOWARN_DEPRECATED_PUSH QgsSymbol::QgsSymbol ( SymbolType  type, const QgsSymbolLayerList &  layers  )

protected

Definition at line 79 of file qgssymbol.cpp.

Member Function Documentation

Q_NOWARN_DEPRECATED_POP QPolygonF QgsSymbol::_getLineString ( QgsRenderContext &  context, const QgsCurve &  curve, bool  clipToExtent = true  )

staticprotected

Creates a line string in screen coordinates from a QgsCurve in map coordinates.

Definition at line 100 of file qgssymbol.cpp.

static QPointF QgsSymbol::_getPoint ( QgsRenderContext &  context, const QgsPoint &  point  )

inlinestaticprotected

Creates a point in screen coordinates from a QgsPoint in map coordinates.

Definition at line 447 of file qgssymbol.h.

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

staticprotected

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.

Definition at line 196 of file qgssymbol.cpp.

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

staticprotected

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.

Definition at line 144 of file qgssymbol.cpp.

bool QgsSymbol::appendSymbolLayer

(

QgsSymbolLayer *

layer

)

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

Definition at line 358 of file qgssymbol.cpp.

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.

See also

exportImage()

drawPreviewIcon()

Definition at line 522 of file qgssymbol.cpp.

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

See also

asImage()

drawPreviewIcon()

Definition at line 536 of file qgssymbol.cpp.

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.

Definition at line 388 of file qgssymbol.cpp.

bool QgsSymbol::clipFeaturesToExtent ( ) const

inline

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

See also

setClipFeaturesToExtent

Since

QGIS 2.9

Definition at line 380 of file qgssymbol.h.

virtual QgsSymbol* QgsSymbol::clone ( ) const

pure virtual

Returns a deep copy of this symbol.

Ownership is transferred to the caller.

Implemented in QgsFillSymbol, QgsLineSymbol, and QgsMarkerSymbol.

QgsSymbolLayerList QgsSymbol::cloneLayers ( ) const

protected

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

Ownership is transferred to the caller.

Definition at line 619 of file qgssymbol.cpp.

QColor QgsSymbol::color

(

)

const

Returns the symbol's color.

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

See also

setColor()

Definition at line 459 of file qgssymbol.cpp.

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

static

Returns a new default symbol for the specified geometry type.

The caller takes ownership of the returned object.

Definition at line 275 of file qgssymbol.cpp.

bool QgsSymbol::deleteSymbolLayer

(

int

index

)

Removes and deletes the symbol layer at the specified index.

Definition at line 368 of file qgssymbol.cpp.

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.

See also

exportImage()

asImage()

Since

QGIS 2.6

Definition at line 470 of file qgssymbol.cpp.

QString QgsSymbol::dump

(

)

const

Returns a string dump of the symbol's properties.

Definition at line 580 of file qgssymbol.cpp.

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.

See also

asImage()

drawPreviewIcon()

Definition at line 502 of file qgssymbol.cpp.

bool QgsSymbol::forceRHR ( ) const

inline

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

Since

QGIS 3.4.3

Definition at line 402 of file qgssymbol.h.

bool QgsSymbol::hasDataDefinedProperties

(

)

const

Returns whether the symbol utilizes any data defined properties.

Since

QGIS 2.12

Definition at line 668 of file qgssymbol.cpp.

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

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

Definition at line 345 of file qgssymbol.cpp.

const QgsVectorLayer * QgsSymbol::layer

(

)

const

Deprecated:

Will be removed in QGIS 4.0

Definition at line 685 of file qgssymbol.cpp.

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.

See also

setMapUnitScale()

Definition at line 235 of file qgssymbol.cpp.

qreal QgsSymbol::opacity ( ) const

inline

Returns the opacity for the symbol.

Returns

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

See also

setOpacity()

Definition at line 339 of file qgssymbol.h.

QgsUnitTypes::RenderUnit QgsSymbol::outputUnit

(

)

const

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

Definition at line 214 of file qgssymbol.cpp.

PRIVATE void QgsSymbol::renderFeature	(	const QgsFeature &	feature,
		QgsRenderContext &	context,
		int	layer = -1,
		bool	selected = false,
		bool	drawVertexMarker = false,
		int	currentVertexMarkerType = 0,
		double	currentVertexMarkerSize = 0.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.

Definition at line 734 of file qgssymbol.cpp.

RenderHints QgsSymbol::renderHints ( ) const

inline

Returns the rendering hint flags for the symbol.

See also

setRenderHints()

Definition at line 358 of file qgssymbol.h.

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.

Definition at line 633 of file qgssymbol.cpp.

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

protected

Render editing vertex marker at specified point.

Since

QGIS 2.16

Definition at line 1068 of file qgssymbol.cpp.

void QgsSymbol::setClipFeaturesToExtent ( bool  clipFeaturesToExtent )

inline

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)

See also

clipFeaturesToExtent

Since

QGIS 2.9

Definition at line 369 of file qgssymbol.h.

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.

See also

color()

Definition at line 450 of file qgssymbol.cpp.

void QgsSymbol::setForceRHR ( bool  force )

inline

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

Since

QGIS 3.4.3

Definition at line 391 of file qgssymbol.h.

void QgsSymbol::setLayer

(

const QgsVectorLayer *

layer

)

Note

the layer will be NULL after stopRender

Deprecated:

Will be removed in QGIS 4.0

Definition at line 678 of file qgssymbol.cpp.

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.

See also

mapUnitScale()

Definition at line 267 of file qgssymbol.cpp.

void QgsSymbol::setOpacity ( qreal  opacity )

inline

Sets the opacity for the symbol.

Parameters

opacity

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

See also

opacity()

Definition at line 346 of file qgssymbol.h.

void QgsSymbol::setOutputUnit

(

QgsUnitTypes::RenderUnit

unit

)

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

Definition at line 259 of file qgssymbol.cpp.

void QgsSymbol::setRenderHints ( RenderHints  hints )

inline

Sets rendering hint flags for the symbol.

See also

renderHints()

Definition at line 352 of file qgssymbol.h.

void QgsSymbol::startRender	(	QgsRenderContext &	context,
		const QgsFields &	fields = 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()

Definition at line 404 of file qgssymbol.cpp.

void QgsSymbol::stopRender

(

QgsRenderContext &

context

)

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

Definition at line 426 of file qgssymbol.cpp.

QgsSymbolLayer * QgsSymbol::symbolLayer

(

int

layer

)

Returns a specific symbol layer contained in the symbol.

Parameters

layer

layer number

Returns

corresponding symbol layer

See also

symbolLayers

symbolLayerCount

Since

QGIS 2.7

Definition at line 340 of file qgssymbol.cpp.

int QgsSymbol::symbolLayerCount ( ) const

inline

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

Returns

count of symbol layers

See also

symbolLayers

symbolLayer

Since

QGIS 2.7

Definition at line 150 of file qgssymbol.h.

QgsSymbolLayerList QgsSymbol::symbolLayers ( )

inline

Returns the list of symbol layers contained in the symbol.

Returns

symbol layers list

See also

symbolLayer

symbolLayerCount

Since

QGIS 2.7

Definition at line 131 of file qgssymbol.h.

QgsSymbolRenderContext * QgsSymbol::symbolRenderContext

(

)

Returns the symbol render context.

Only valid between startRender and stopRender calls.

Returns

The symbol render context

Definition at line 1063 of file qgssymbol.cpp.

QgsSymbolLayer * QgsSymbol::takeSymbolLayer

(

int

index

)

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

Definition at line 379 of file qgssymbol.cpp.

void QgsSymbol::toSld	(	QDomDocument &	doc,
		QDomElement &	element,
		QgsStringMap	props
	)		const

Converts the symbol to a SLD representation.

Definition at line 606 of file qgssymbol.cpp.

SymbolType QgsSymbol::type ( ) const

inline

Returns the symbol's type.

Definition at line 120 of file qgssymbol.h.

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.

Definition at line 654 of file qgssymbol.cpp.

Friends And Related Function Documentation

friend class QgsFeatureRenderer

friend

Definition at line 76 of file qgssymbol.h.

Member Data Documentation

bool QgsSymbol::mClipFeaturesToExtent = true

protected

Definition at line 518 of file qgssymbol.h.

bool QgsSymbol::mForceRHR = false

protected

Definition at line 519 of file qgssymbol.h.

Q_DECL_DEPRECATED const QgsVectorLayer* QgsSymbol::mLayer = nullptr

protected

Definition at line 521 of file qgssymbol.h.

QgsSymbolLayerList QgsSymbol::mLayers

protected

Definition at line 512 of file qgssymbol.h.

qreal QgsSymbol::mOpacity = 1.0

protected

Symbol opacity (in the range 0 - 1)

Definition at line 515 of file qgssymbol.h.

RenderHints QgsSymbol::mRenderHints = nullptr

protected

Definition at line 517 of file qgssymbol.h.

SymbolType QgsSymbol::mType

protected

Definition at line 511 of file qgssymbol.h.

---

The documentation for this class was generated from the following files:

• /build/qgis-3.4.15+24xenial/src/core/symbology/qgssymbol.h
• /build/qgis-3.4.15+24xenial/src/core/symbology/qgssymbol.cpp