QgsRuleBasedRenderer::Rule class

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

Reference

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.

Public types

enum RenderResult { Filtered = 0, Inactive, Rendered }: The result of rendering a rule.

Public static functions

static auto create(QDomElement& ruleElem, QgsSymbolMap& symbolMap) -> QgsRuleBasedRenderer::Rule*: Create a rule from an XML definition.
static auto createFromSld(QDomElement& element, QgsWkbTypes::GeometryType geomType) -> QgsRuleBasedRenderer::Rule*: Create a rule from the SLD provided in element and for the specified geometry type.

Constructors, destructors, conversion operators

Rule(QgsSymbol* symbol, int maximumScale = 0, int minimumScale = 0, const QString& filterExp = QString(), const QString& label = QString(), const QString& description = QString(), bool elseRule = false): Constructor takes ownership of the symbol.
Rule(const Rule& rh) deleted: Rules cannot be copied.

Public functions

auto active() const -> bool: Returns if this rule is active.
void appendChild(QgsRuleBasedRenderer::Rule* rule): add child rule, take ownership, sets this as parent
auto children() -> const QgsRuleBasedRenderer::RuleList&: Returns all children rules of this rule.
auto clone() const -> QgsRuleBasedRenderer::Rule*: clone this rule, return new instance
auto collectZLevels() -> QSet<int>: Gets all used z-levels from this rule and children.
auto descendants() const -> QgsRuleBasedRenderer::RuleList: Returns all children, grand-children, grand-grand-children, grand-gra...
auto description() const -> QString: A human readable description for this rule.
auto dump(int indent = 0) const -> QString: Dump for debug purpose.
auto filter() const -> QgsExpression*: A filter that will check if this rule applies.
auto filterExpression() const -> QString: A filter that will check if this rule applies.
auto findRuleByKey(const QString& key) -> QgsRuleBasedRenderer::Rule*: Try to find a rule given its unique key.
void insertChild(int i, QgsRuleBasedRenderer::Rule* rule): add child rule, take ownership, sets this as parent
auto isElse() const -> bool: Check if this rule is an ELSE rule.
auto isFilterOK(const QgsFeature& f, QgsRenderContext* context = nullptr) const -> bool: Check if a given feature shall be rendered by this rule.
auto isScaleOK(double scale) const -> bool: Check if this rule applies for a given scale.
auto legendKeysForFeature(const QgsFeature& feature, QgsRenderContext* context = nullptr) -> QSet<QString>: Returns which legend keys match the feature.
auto legendSymbolItems(int currentLevel = -1) const -> QgsLegendSymbolList
auto maximumScale() const -> double: Returns the maximum map scale (i.e.
auto minimumScale() const -> double: Returns the minimum map scale (i.e.
auto needsGeometry() const -> bool: Returns true if this rule or one of its chilren needs the geometry to be applied.
auto operator=(const Rule& rh) -> Rule& deleted: Rules cannot be copied.
auto parent() -> QgsRuleBasedRenderer::Rule*: The parent rule.
void removeChild(QgsRuleBasedRenderer::Rule* rule): delete child rule
void removeChildAt(int i): delete child rule
auto renderFeature(QgsRuleBasedRenderer::FeatureToRender& featToRender, QgsRenderContext& context, QgsRuleBasedRenderer::RenderQueue& renderQueue) -> QgsRuleBasedRenderer::Rule::RenderResult: Render a given feature, will recursively call subclasses and only render if the constraints apply.
auto ruleKey() const -> QString: Unique rule identifier (for identification of rule within renderer)
auto rulesForFeature(const QgsFeature& feature, QgsRenderContext* context = nullptr, bool onlyActive = true) -> QgsRuleBasedRenderer::RuleList: Returns the list of rules used to render the feature in a specific context.
void setActive(bool state): Sets if this rule is active.
void setDescription(const QString& description): Set a human readable description for this rule.
void setFilterExpression(const QString& filterExp): Set the expression used to check if a given feature shall be rendered with this rule.
void setIsElse(bool iselse): Sets if this rule is an ELSE rule.
void setMaximumScale(double scale): Sets the maximum map scale (i.e.
void setMinimumScale(double scale): Sets the minimum map scale (i.e.
void setNormZLevels(const QMap<int, int>& zLevelsToNormLevels): assign normalized z-levels [0..N-1] for this rule's symbol for quick access during rendering
void setRuleKey(const QString& key): Override the assigned rule key (should be used just internally by rule-based renderer)
void setSymbol(QgsSymbol* sym): Sets a new symbol (or NULL). Deletes old symbol.
auto startRender(QgsRenderContext& context, const QgsFields& fields, QString& filter) -> bool: prepare the rule for rendering and its children (build active children array)
void stopRender(QgsRenderContext& context): Stop a rendering process.
auto symbols(const QgsRenderContext& context = QgsRenderContext()) const -> QgsSymbolList
auto symbolsForFeature(const QgsFeature& feature, QgsRenderContext* context = nullptr) -> QgsSymbolList: tell which symbols will be used to render the feature
auto takeChild(QgsRuleBasedRenderer::Rule* rule) -> QgsRuleBasedRenderer::Rule*: take child rule out, set parent as null
auto takeChildAt(int i) -> QgsRuleBasedRenderer::Rule*: take child rule out, set parent as null
auto usedAttributes(const QgsRenderContext& context) const -> QSet<QString>: Returns the attributes used to evaluate the expression of this rule.
auto willRenderFeature(const QgsFeature& feature, QgsRenderContext* context = nullptr) -> bool: only tell whether a feature will be rendered without actually rendering it

Enum documentation

enum QgsRuleBasedRenderer::Rule::RenderResult

The result of rendering a rule.

Enumerators
Filtered	The rule does not apply.
Inactive	The rule is inactive.
Rendered	Something was rendered.

Function documentation

static QgsRuleBasedRenderer::Rule* QgsRuleBasedRenderer::Rule::create(QDomElement& ruleElem, QgsSymbolMap& symbolMap)

Create a rule from an XML definition.

Parameters
ruleElem	The XML rule element
symbolMap	Symbol map
Returns	A new rule

bool QgsRuleBasedRenderer::Rule::active() const

Returns if this rule is active.

Returns	True if the rule is active

const QgsRuleBasedRenderer::RuleList& QgsRuleBasedRenderer::Rule::children()

Returns all children rules of this rule.

Returns	A list of rules

QgsRuleBasedRenderer::RuleList QgsRuleBasedRenderer::Rule::descendants() const

Returns all children, grand-children, grand-grand-children, grand-gra...

Returns	A list of descendant rules

you get it

QString QgsRuleBasedRenderer::Rule::description() const

A human readable description for this rule.

Returns	Description

QString QgsRuleBasedRenderer::Rule::dump(int indent = 0) const

Dump for debug purpose.

Parameters
indent	How many characters to indent. Will increase by two with every of the recursive calls
Returns	A string representing this rule

QgsExpression* QgsRuleBasedRenderer::Rule::filter() const

A filter that will check if this rule applies.

Returns	An expression

QString QgsRuleBasedRenderer::Rule::filterExpression() const

A filter that will check if this rule applies.

Returns	An expression

QgsRuleBasedRenderer::Rule* QgsRuleBasedRenderer::Rule::findRuleByKey(const QString& key)

Try to find a rule given its unique key.

bool QgsRuleBasedRenderer::Rule::isElse() const

Check if this rule is an ELSE rule.

Returns	True if this rule is an else rule

bool QgsRuleBasedRenderer::Rule::isFilterOK(const QgsFeature& f, QgsRenderContext* context = nullptr) const

Check if a given feature shall be rendered by this rule.

Parameters
f	The feature to test
context	The context in which the rendering happens
Returns	True if the feature shall be rendered

bool QgsRuleBasedRenderer::Rule::isScaleOK(double scale) const

Check if this rule applies for a given scale.

Returns	If the rule will be evaluated at this 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.

QSet<QString> QgsRuleBasedRenderer::Rule::legendKeysForFeature(const QgsFeature& feature, QgsRenderContext* context = nullptr)

Returns which legend keys match the feature.

QgsLegendSymbolList QgsRuleBasedRenderer::Rule::legendSymbolItems(int currentLevel = -1) const

double QgsRuleBasedRenderer::Rule::maximumScale() const

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.

double QgsRuleBasedRenderer::Rule::minimumScale() const

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.

QgsRuleBasedRenderer::Rule* QgsRuleBasedRenderer::Rule::parent()

The parent rule.

Returns	Parent rule

QgsRuleBasedRenderer::Rule::RenderResult QgsRuleBasedRenderer::Rule::renderFeature(QgsRuleBasedRenderer::FeatureToRender& featToRender, QgsRenderContext& context, QgsRuleBasedRenderer::RenderQueue& renderQueue)

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

Parameters
featToRender	The feature to render
context	The rendering context
renderQueue	The rendering queue to which the feature should be added
Returns	The result of the rendering. In explicit if the feature is added to the queue or the reason for not rendering the feature.

QString QgsRuleBasedRenderer::Rule::ruleKey() const

Unique rule identifier (for identification of rule within renderer)

QgsRuleBasedRenderer::RuleList QgsRuleBasedRenderer::Rule::rulesForFeature(const QgsFeature& feature, QgsRenderContext* context = nullptr, bool onlyActive = true)

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

Parameters
feature	The feature for which rules have to be find
context	The rendering context
onlyActive	True to search for active rules only, false otherwise

void QgsRuleBasedRenderer::Rule::setActive(bool state)

Sets if this rule is active.

Parameters
state	Determines if the rule should be activated or deactivated

void QgsRuleBasedRenderer::Rule::setDescription(const QString& description)

Set a human readable description for this rule.

Parameters
description	Description

void QgsRuleBasedRenderer::Rule::setFilterExpression(const QString& filterExp)

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

Parameters
filterExp	An expression

void QgsRuleBasedRenderer::Rule::setIsElse(bool iselse)

Sets if this rule is an ELSE rule.

Parameters
iselse	If true, this rule is an ELSE rule

void QgsRuleBasedRenderer::Rule::setMaximumScale(double scale)

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.

void QgsRuleBasedRenderer::Rule::setMinimumScale(double scale)

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.

void QgsRuleBasedRenderer::Rule::setNormZLevels(const QMap<int, int>& zLevelsToNormLevels)

assign normalized z-levels [0..N-1] for this rule's symbol for quick access during rendering

void QgsRuleBasedRenderer::Rule::setRuleKey(const QString& key)

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

void QgsRuleBasedRenderer::Rule::stopRender(QgsRenderContext& context)

Stop a rendering process.

Parameters
context	The rendering context

Used to clean up the internal state of this rule

QgsSymbolList QgsRuleBasedRenderer::Rule::symbols(const QgsRenderContext& context = QgsRenderContext()) const

QSet<QString> QgsRuleBasedRenderer::Rule::usedAttributes(const QgsRenderContext& context) const

Returns the attributes used to evaluate the expression of this rule.

Returns	A set of attribute names