Class: QgsRuleBasedRenderer

class qgis.core.QgsRuleBasedRenderer

Bases: QgsFeatureRenderer

Rule based renderer.

When drawing a vector layer with rule-based renderer, it goes through the rules and draws features with symbols from rules that match.

QgsRuleBasedRenderer(root: Optional[QgsRuleBasedRenderer.Rule]) Constructs the renderer from given tree of rules (takes ownership)

QgsRuleBasedRenderer(defaultSymbol: Optional[QgsSymbol]) Constructor for convenience. Creates a root rule and adds a default rule with symbol (takes ownership)

Methods

accept

param visitor:

canSkipRender

rtype:

bool

capabilities

rtype:

QgsFeatureRenderer.Capabilities

checkLegendSymbolItem

param key:

clone

rtype:

Optional[QgsRuleBasedRenderer]

convertFromRenderer

Creates a new QgsRuleBasedRenderer from an existing renderer.

convertSymbolRotation

convertSymbolSizeScale

convertToDataDefinedSymbology

helper function to convert the size scale and rotation fields present in some other renderers to data defined symbology

create

Creates a new rule-based renderer instance from XML

createFromSld

Creates a new rule based renderer from an SLD XML element.

dump

rtype:

str

filter

param fields:

filterNeedsGeometry

rtype:

bool

legendKeyToExpression

param key:

legendKeysForFeature

param feature:

legendSymbolItemChecked

param key:

legendSymbolItems

rtype:

List[QgsLegendSymbolItem]

legendSymbolItemsCheckable

rtype:

bool

originalSymbolsForFeature

param feature:

refineRuleCategories

take a rule and create a list of new rules based on the categories from categorized symbol renderer

refineRuleRanges

take a rule and create a list of new rules based on the ranges from graduated symbol renderer

refineRuleScales

take a rule and create a list of new rules with intervals of scales given by the passed scale denominators

renderFeature

param feature:

renderFeatureWithSymbol

Render the feature with the symbol using context.

renderVertexMarker

render editing vertex marker at specified point

renderVertexMarkerPolygon

render editing vertex marker for a polygon

renderVertexMarkerPolyline

render editing vertex marker for a polyline

rootRule

rtype:

Optional[QgsRuleBasedRenderer.Rule]

save

param doc:

saveRendererData

Saves generic renderer data into the specified element.

setLegendSymbolItem

param key:

startRender

param context:

stopRender

param context:

symbolForFeature

Returns symbol for current feature.

symbols

param context:

symbolsForFeature

param feature:

toSld

param doc:

usedAttributes

param context:

willRenderFeature

param feature:

Attributes

FeatDrawMarkers

FeatIsSelected

FeatDrawMarkers = 2
FeatIsSelected = 1
class FeatureFlags

Bases: int

class FeatureToRender(_f: QgsFeature, _flags: int)
class FeatureToRender(a0: QgsRuleBasedRenderer.FeatureToRender)

Bases: sip.wrapper

feat
flags
class RenderJob(_ftr: QgsRuleBasedRenderer.FeatureToRender, _s: QgsSymbol | None)

Bases: sip.wrapper

Constructor for a render job, with the specified feature to render and symbol.

Note

The symbol ownership is not transferred.

QgsRuleBasedRenderer.RenderJob(a0: QgsRuleBasedRenderer.RenderJob)

ftr
symbol
class RenderLevel(z: int)
class RenderLevel(other: QgsRuleBasedRenderer.RenderLevel)

Bases: sip.wrapper

jobs
zIndex
class Rule

Bases: sip.wrapper

This class keeps data about a rules for rule-based renderer.

A rule consists of a symbol, filter expression and range of scales. If filter is empty, it matches all features. If scale range has both values zero, it matches all scales. If one of the min/max scale denominators is zero, there is no lower/upper bound for scales. A rule matches if both filter and scale range match.

QgsRuleBasedRenderer.Rule(symbol: Optional[QgsSymbol], maximumScale: int = 0, minimumScale: int = 0, filterExp: Optional[str] = ‘’, label: Optional[str] = ‘’, description: Optional[str] = ‘’, elseRule: bool = False) Constructor takes ownership of the symbol

Filtered = 0
Inactive = 1
class RenderResult

Bases: int

Rendered = 2
accept(self, visitor: QgsStyleEntityVisitorInterface | None) bool

Accepts the specified symbology visitor, causing it to visit all child rules associated with the rule.

Returns True if the visitor should continue visiting other objects, or False if visiting should be canceled.

Added in version 3.10.

Parameters:

visitor (Optional[QgsStyleEntityVisitorInterface])

Return type:

bool

active(self) bool

Returns if this rule is active

Return type:

bool

Returns:

True if the rule is active

appendChild(self, rule: QgsRuleBasedRenderer.Rule | None)

add child rule, take ownership, sets this as parent

Parameters:

rule (Optional[QgsRuleBasedRenderer.Rule])

children(self) List[QgsRuleBasedRenderer.Rule]

Returns all children rules of this rule

Return type:

List[QgsRuleBasedRenderer.Rule]

Returns:

A list of rules

clone(self) QgsRuleBasedRenderer.Rule | None

clone this rule, return new instance

Return type:

Optional[QgsRuleBasedRenderer.Rule]

collectZLevels(self) Any

Gets all used z-levels from this rule and children

Return type:

Any

create(ruleElem: QDomElement, symbolMap: Any, reuseId: bool = True) QgsRuleBasedRenderer.Rule | None

Create a rule from an XML definition

Parameters:
  • ruleElem (QDomElement) – The XML rule element

  • symbolMap (Any) – Symbol map

  • reuseId (bool = True) – set to True to create an exact copy of the original symbol or False to create a new rule with the same parameters as the original but a new unique ruleKey(). (Since QGIS 3.30)

Return type:

Optional[QgsRuleBasedRenderer.Rule]

Returns:

A new rule

createFromSld(element: QDomElement, geomType: Qgis.GeometryType) QgsRuleBasedRenderer.Rule | None

Create a rule from the SLD provided in element and for the specified geometry type.

Parameters:
Return type:

Optional[QgsRuleBasedRenderer.Rule]

dependsOnScale(self) bool
Return type:

bool

descendants(self) List[QgsRuleBasedRenderer.Rule]

Returns all children, grand-children, grand-grand-children, grand-gra… you get it

Return type:

List[QgsRuleBasedRenderer.Rule]

Returns:

A list of descendant rules

description(self) str

A human readable description for this rule

Return type:

str

Returns:

Description

dump(self, indent: int = 0) str

Dump for debug purpose

Parameters:

indent (int = 0) – How many characters to indent. Will increase by two with every of the recursive calls

Return type:

str

Returns:

A string representing this rule

filter(self) QgsExpression | None

A filter that will check if this rule applies

Return type:

Optional[QgsExpression]

Returns:

An expression

filterExpression(self) str

A filter that will check if this rule applies

Return type:

str

Returns:

An expression

findRuleByKey(self, key: str | None) QgsRuleBasedRenderer.Rule | None

Try to find a rule given its unique key

Parameters:

key (Optional[str])

Return type:

Optional[QgsRuleBasedRenderer.Rule]

hasActiveChildren(self) bool

Returns True if the rule has any active children.

Note

Must be called after startRender()

Added in version 3.30.

Return type:

bool

initFilter(self)
insertChild(self, i: int, rule: QgsRuleBasedRenderer.Rule | None)

add child rule, take ownership, sets this as parent

Parameters:
isElse(self) bool

Check if this rule is an ELSE rule

Return type:

bool

Returns:

True if this rule is an else rule

isFilterOK(self, f: QgsFeature, context: QgsRenderContext | None = None) bool

Check if a given feature shall be rendered by this rule

Parameters:
  • f (QgsFeature) – The feature to test

  • context (Optional[QgsRenderContext] = None) – The context in which the rendering happens

Return type:

bool

Returns:

True if the feature shall be rendered

isScaleOK(self, scale: float) bool

Check if this rule applies for a given scale. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. If set to 0, it will always return True.

Return type:

bool

Returns:

If the rule will be evaluated at this scale

Parameters:

scale (float)

label(self) str
Return type:

str

legendKeysForFeature(self, feature: QgsFeature, context: QgsRenderContext | None = None) Set[str]

Returns which legend keys match the feature

Parameters:
Return type:

Set[str]

legendSymbolItems(self, currentLevel: int = -1) List[QgsLegendSymbolItem]
Parameters:

currentLevel (int = -1)

Return type:

List[QgsLegendSymbolItem]

maximumScale(self) float

Returns the maximum map scale (i.e. most “zoomed in” scale) at which the rule will be active. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. A scale of 0 indicates no maximum scale visibility.

See also

minimumScale()

Return type:

float

minimumScale(self) float

Returns the minimum map scale (i.e. most “zoomed out” scale) at which the rule will be active. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. A scale of 0 indicates no minimum scale visibility.

See also

maximumScale()

Return type:

float

needsGeometry(self) bool

Returns True if this rule or one of its children needs the geometry to be applied.

Return type:

bool

parent(self) QgsRuleBasedRenderer.Rule | None

The parent rule

Return type:

Optional[QgsRuleBasedRenderer.Rule]

Returns:

Parent rule

removeChild(self, rule: QgsRuleBasedRenderer.Rule | None)

delete child rule

Parameters:

rule (Optional[QgsRuleBasedRenderer.Rule])

removeChildAt(self, i: int)

delete child rule

Parameters:

i (int)

renderFeature(self, featToRender: QgsRuleBasedRenderer.FeatureToRender, context: QgsRenderContext, renderQueue: Iterable[QgsRuleBasedRenderer.RenderLevel]) QgsRuleBasedRenderer.Rule.RenderResult

Render a given feature, will recursively call subclasses and only render if the constraints apply.

Parameters:
Return type:

QgsRuleBasedRenderer.Rule.RenderResult

Returns:

The result of the rendering. In explicit if the feature is added to the queue or the reason for not rendering the feature.

ruleKey(self) str

Unique rule identifier (for identification of rule within renderer)

Return type:

str

rulesForFeature(self, feature: QgsFeature, context: QgsRenderContext | None = None, onlyActive: bool = True) List[QgsRuleBasedRenderer.Rule]

Returns the list of rules used to render the feature in a specific context.

Parameters:
  • feature (QgsFeature) – The feature for which rules have to be find

  • context (Optional[QgsRenderContext] = None) – The rendering context

  • onlyActive (bool = True) – True to search for active rules only, False otherwise

Return type:

List[QgsRuleBasedRenderer.Rule]

save(self, doc: QDomDocument, symbolMap: Any) QDomElement
Parameters:
  • doc (QDomDocument)

  • symbolMap (Any)

Return type:

QDomElement

setActive(self, state: bool)

Sets if this rule is active

Parameters:

state (bool) – Determines if the rule should be activated or deactivated

setDescription(self, description: str | None)

Set a human readable description for this rule

Parameters:

description (Optional[str]) – Description

setFilterExpression(self, filterExp: str | None)

Set the expression used to check if a given feature shall be rendered with this rule

Parameters:

filterExp (Optional[str]) – An expression

setIsElse(self, iselse: bool)

Sets if this rule is an ELSE rule

Parameters:

iselse (bool) – If True, this rule is an ELSE rule

setLabel(self, label: str | None)
Parameters:

label (Optional[str])

setMaximumScale(self, scale: float)

Sets the maximum map scale (i.e. most “zoomed in” scale) at which the rule will be active. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. A scale of 0 indicates no maximum scale visibility.

See also

maximumScale()

Parameters:

scale (float)

setMinimumScale(self, scale: float)

Sets the minimum map scale (i.e. most “zoomed out” scale) at which the rule will be active. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. A scale of 0 indicates no minimum scale visibility.

See also

minimumScale()

Parameters:

scale (float)

setRuleKey(self, key: str | None)

Override the assigned rule key (should be used just internally by rule-based renderer)

Parameters:

key (Optional[str])

setSymbol(self, sym: QgsSymbol | None)

Sets a new symbol (or None). Deletes old symbol.

Parameters:

sym (Optional[QgsSymbol])

startRender(self, context: QgsRenderContext, fields: QgsFields, filter: str | None) bool

prepare the rule for rendering and its children (build active children array)

Parameters:
Return type:

bool

stopRender(self, context: QgsRenderContext)

Stop a rendering process. Used to clean up the internal state of this rule

Parameters:

context (QgsRenderContext) – The rendering context

symbol(self) QgsSymbol | None
Return type:

Optional[QgsSymbol]

symbols(self, context: QgsRenderContext = QgsRenderContext()) List[QgsSymbol]

Note

available in Python bindings as symbol2

Parameters:

context (QgsRenderContext = QgsRenderContext())

Return type:

List[QgsSymbol]

symbolsForFeature(self, feature: QgsFeature, context: QgsRenderContext | None = None) List[QgsSymbol]

tell which symbols will be used to render the feature

Parameters:
Return type:

List[QgsSymbol]

takeChild(self, rule: QgsRuleBasedRenderer.Rule | None) QgsRuleBasedRenderer.Rule | None

take child rule out, set parent as None

Parameters:

rule (Optional[QgsRuleBasedRenderer.Rule])

Return type:

Optional[QgsRuleBasedRenderer.Rule]

takeChildAt(self, i: int) QgsRuleBasedRenderer.Rule | None

take child rule out, set parent as None

Parameters:

i (int)

Return type:

Optional[QgsRuleBasedRenderer.Rule]

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

Saves the symbol layer as SLD

Parameters:
  • doc (QDomDocument)

  • element (QDomElement)

  • props (Dict[str)

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

Returns the attributes used to evaluate the expression of this rule

Return type:

Set[str]

Returns:

A set of attribute names

Parameters:

context (QgsRenderContext)

willRenderFeature(self, feature: QgsFeature, context: QgsRenderContext | None = None) bool

only tell whether a feature will be rendered without actually rendering it

Parameters:
Return type:

bool

accept(self, visitor: QgsStyleEntityVisitorInterface | None) bool
Parameters:

visitor (Optional[QgsStyleEntityVisitorInterface])

Return type:

bool

canSkipRender(self) bool
Return type:

bool

capabilities(self) QgsFeatureRenderer.Capabilities
Return type:

QgsFeatureRenderer.Capabilities

checkLegendSymbolItem(self, key: str | None, state: bool = True)
Parameters:
  • key (Optional[str])

  • state (bool = True)

clone(self) QgsRuleBasedRenderer | None
Return type:

Optional[QgsRuleBasedRenderer]

convertFromRenderer(renderer: QgsFeatureRenderer | None, layer: QgsVectorLayer | None = None) QgsRuleBasedRenderer | None

Creates a new QgsRuleBasedRenderer from an existing renderer.

Since QGIS 3.20, the optional layer parameter is required for conversions of some renderer types.

Return type:

Optional[QgsRuleBasedRenderer]

Returns:

a new renderer if the conversion was possible, otherwise None.

Parameters:
convertSymbolRotation(symbol: QgsSymbol | None, field: str | None)

Note

this function is used to convert old rotations expressions to symbol level DataDefined angle

convertSymbolSizeScale(symbol: QgsSymbol | None, method: Qgis.ScaleMethod, field: str | None)

Note

this function is used to convert old sizeScale expressions to symbol level DataDefined size

convertToDataDefinedSymbology(symbol: QgsSymbol | None, sizeScaleField: str | None, rotationField: str | None = '')

helper function to convert the size scale and rotation fields present in some other renderers to data defined symbology

Parameters:
  • symbol (Optional[QgsSymbol])

  • sizeScaleField (Optional[str])

  • rotationField (Optional[str] = '')

create(element: QDomElement, context: QgsReadWriteContext) QgsFeatureRenderer | None

Creates a new rule-based renderer instance from XML

Parameters:
Return type:

Optional[QgsFeatureRenderer]

createFromSld(element: QDomElement, geomType: Qgis.GeometryType) QgsFeatureRenderer | None

Creates a new rule based renderer from an SLD XML element.

Parameters:
Return type:

Optional[QgsFeatureRenderer]

dump(self) str
Return type:

str

filter(self, fields: QgsFields = QgsFields()) str
Parameters:

fields (QgsFields = QgsFields())

Return type:

str

filterNeedsGeometry(self) bool
Return type:

bool

legendKeyToExpression(self, key: str | None, layer: QgsVectorLayer | None)
Parameters:
legendKeysForFeature(self, feature: QgsFeature, context: QgsRenderContext) Set[str]
Parameters:
Return type:

Set[str]

legendSymbolItemChecked(self, key: str | None) bool
Parameters:

key (Optional[str])

Return type:

bool

legendSymbolItems(self) List[QgsLegendSymbolItem]
Return type:

List[QgsLegendSymbolItem]

legendSymbolItemsCheckable(self) bool
Return type:

bool

originalSymbolsForFeature(self, feature: QgsFeature, context: QgsRenderContext) List[QgsSymbol]
Parameters:
Return type:

List[QgsSymbol]

refineRuleCategories(initialRule: QgsRuleBasedRenderer.Rule | None, r: QgsCategorizedSymbolRenderer | None)

take a rule and create a list of new rules based on the categories from categorized symbol renderer

Parameters:
refineRuleRanges(initialRule: QgsRuleBasedRenderer.Rule | None, r: QgsGraduatedSymbolRenderer | None)

take a rule and create a list of new rules based on the ranges from graduated symbol renderer

Parameters:
refineRuleScales(initialRule: QgsRuleBasedRenderer.Rule | None, scales: Iterable[int])

take a rule and create a list of new rules with intervals of scales given by the passed scale denominators

Parameters:
renderFeature(self, feature: QgsFeature, context: QgsRenderContext, layer: int = -1, selected: bool = False, drawVertexMarker: bool = False) bool
Parameters:
Return type:

bool

renderFeatureWithSymbol(self, feature: QgsFeature, symbol: QgsSymbol | None, context: QgsRenderContext, layer: int, selected: bool, drawVertexMarker: bool)

Render the feature with the symbol using context. Use layer to specify the symbol layer, selected to specify if it should be rendered as selected and drawVertexMarker to specify if vertex markers should be rendered.

renderVertexMarker(self, pt: QPointF | QPoint, context: QgsRenderContext)

render editing vertex marker at specified point

renderVertexMarkerPolygon(self, pts: QPolygonF, rings: Iterable[QPolygonF] | None, context: QgsRenderContext)

render editing vertex marker for a polygon

renderVertexMarkerPolyline(self, pts: QPolygonF, context: QgsRenderContext)

render editing vertex marker for a polyline

rootRule(self) QgsRuleBasedRenderer.Rule | None
Return type:

Optional[QgsRuleBasedRenderer.Rule]

save(self, doc: QDomDocument, context: QgsReadWriteContext) QDomElement
Parameters:
Return type:

QDomElement

saveRendererData(self, doc: QDomDocument, element: QDomElement, context: QgsReadWriteContext)

Saves generic renderer data into the specified element.

This method should be called in a subclass’ save() implementation in order to store all common base class properties in the DOM element.

Added in version 3.22.

setLegendSymbolItem(self, key: str | None, symbol: QgsSymbol | None)
Parameters:
  • key (Optional[str])

  • symbol (Optional[QgsSymbol])

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

context (QgsRenderContext)

symbolForFeature(self, feature: QgsFeature, context: QgsRenderContext) QgsSymbol | None

Returns symbol for current feature. Should not be used individually: there could be more symbols for a feature

Parameters:
Return type:

Optional[QgsSymbol]

symbols(self, context: QgsRenderContext) List[QgsSymbol]
Parameters:

context (QgsRenderContext)

Return type:

List[QgsSymbol]

symbolsForFeature(self, feature: QgsFeature, context: QgsRenderContext) List[QgsSymbol]
Parameters:
Return type:

List[QgsSymbol]

toSld(self, doc: QDomDocument, element: QDomElement, props: Dict[str, Any] = {})
Parameters:
  • doc (QDomDocument)

  • element (QDomElement)

  • props (Dict[str)

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

context (QgsRenderContext)

Return type:

Set[str]

willRenderFeature(self, feature: QgsFeature, context: QgsRenderContext) bool
Parameters:
Return type:

bool