QgsRuleBasedRenderer class

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

Reference

Public types

struct FeatureToRender: Feature for rendering by a QgsRuleBasedRenderer.
struct RenderJob: A QgsRuleBasedRenderer rendering job, consisting of a feature to be rendered with a particular symbol.
struct RenderLevel: Render level: a list of jobs to be drawn at particular level for a QgsRuleBasedRenderer.
class Rule: This class keeps data about a rules for rule-based renderer.
using RenderQueue = QList<QgsRuleBasedRenderer::RenderLevel>: Rendering queue: a list of rendering levels.

Public static functions

static auto convertFromRenderer(const QgsFeatureRenderer* renderer) -> QgsRuleBasedRenderer*: creates a QgsRuleBasedRenderer from an existing renderer.
static void convertToDataDefinedSymbology(QgsSymbol* symbol, const QString& sizeScaleField, const QString& rotationField = QString()): helper function to convert the size scale and rotation fields present in some other renderers to data defined symbology
static auto create(QDomElement& element, const QgsReadWriteContext& context) -> QgsFeatureRenderer*: Creates a new rule-based renderer instance from XML.
static void refineRuleCategories(QgsRuleBasedRenderer::Rule* initialRule, QgsCategorizedSymbolRenderer* r): take a rule and create a list of new rules based on the categories from categorized symbol renderer
static void refineRuleRanges(QgsRuleBasedRenderer::Rule* initialRule, QgsGraduatedSymbolRenderer* r): take a rule and create a list of new rules based on the ranges from graduated symbol renderer
static void refineRuleScales(QgsRuleBasedRenderer::Rule* initialRule, QList<int> scales): take a rule and create a list of new rules with intervals of scales given by the passed scale denominators

Constructors, destructors, conversion operators

QgsRuleBasedRenderer(QgsRuleBasedRenderer::Rule* root): Constructs the renderer from given tree of rules (takes ownership)
QgsRuleBasedRenderer(QgsSymbol* defaultSymbol): Constructor for convenience. Creates a root rule and adds a default rule with symbol (takes ownership)

Public functions

auto capabilities() -> QgsFeatureRenderer::Capabilities override: Returns details about internals of this renderer.
void checkLegendSymbolItem(const QString& key, bool state = true) override: item in symbology was checked
auto clone() const -> QgsRuleBasedRenderer* override: Create a deep copy of this renderer.
auto dump() const -> QString override: Returns debug information about this renderer.
auto filter(const QgsFields& fields = QgsFields()) -> QString override: If a renderer does not require all the features this method may be overridden and return an expression used as where clause.
auto filterNeedsGeometry() const -> bool override: Returns true if this renderer requires the geometry to apply the filter.
auto legendKeysForFeature(const QgsFeature& feature, QgsRenderContext& context) const -> QSet<QString> override: Returns legend keys matching a specified feature.
auto legendSymbolItemChecked(const QString& key) -> bool override: items of symbology items in legend is checked
auto legendSymbolItems() const -> QgsLegendSymbolList override: Returns a list of symbology items for the legend.
auto legendSymbolItemsCheckable() const -> bool override: items of symbology items in legend should be checkable
auto originalSymbolsForFeature(const QgsFeature& feature, QgsRenderContext& context) const -> QgsSymbolList override: Equivalent of originalSymbolsForFeature() call extended to support renderers that may use more symbols per feature - similar to symbolsForFeature()
auto renderFeature(const QgsFeature& feature, QgsRenderContext& context, int layer = -1, bool selected = false, bool drawVertexMarker = false) -> bool override: Render a feature using this renderer in the given context.
auto save(QDomDocument& doc, const QgsReadWriteContext& context) -> QDomElement override: store renderer info to XML element
void setLegendSymbolItem(const QString& key, QgsSymbol* symbol) override: Sets the symbol to be used for a legend symbol item.
void startRender(QgsRenderContext& context, const QgsFields& fields) override: Must be called when a new render cycle is started.
void stopRender(QgsRenderContext& context) override: Must be called when a render cycle has finished, to allow the renderer to clean up.
auto symbolForFeature(const QgsFeature& feature, QgsRenderContext& context) const -> QgsSymbol* override: Returns symbol for current feature. Should not be used individually: there could be more symbols for a feature.
auto symbols(QgsRenderContext& context) const -> QgsSymbolList override: Returns list of symbols used by the renderer.
auto symbolsForFeature(const QgsFeature& feature, QgsRenderContext& context) const -> QgsSymbolList override: Returns list of symbols used for rendering the feature.
void toSld(QDomDocument& doc, QDomElement& element, const QgsStringMap& props = QgsStringMap()) const override: used from subclasses to create SLD Rule elements following SLD v1.1 specs
auto usedAttributes(const QgsRenderContext& context) const -> QSet<QString> override: Returns a list of attributes required by this renderer.
auto willRenderFeature(const QgsFeature& feature, QgsRenderContext& context) const -> bool override: Returns whether the renderer will render a feature or not.

Protected variables

Rule* mRootRule: the root node with hierarchical list of rules

Function documentation

static QgsRuleBasedRenderer* QgsRuleBasedRenderer::convertFromRenderer(const QgsFeatureRenderer* renderer)

creates a QgsRuleBasedRenderer from an existing renderer.

Returns	a new renderer if the conversion was possible, otherwise 0.

QgsFeatureRenderer::Capabilities QgsRuleBasedRenderer::capabilities() override

Returns details about internals of this renderer.

E.g. if you only want to deal with visible features:

if not renderer.capabilities().testFlag(QgsFeatureRenderer.Filter) or renderer.willRenderFeature(feature, context):
    deal_with_my_feature()
else:
    skip_the_curren_feature()

void QgsRuleBasedRenderer::checkLegendSymbolItem(const QString& key, bool state = true) override

item in symbology was checked

QgsRuleBasedRenderer* QgsRuleBasedRenderer::clone() const override

Create a deep copy of this renderer.

Returns	A copy of this renderer

Should be implemented by all subclasses and generate a proper subclass.

QString QgsRuleBasedRenderer::filter(const QgsFields& fields = QgsFields()) override

If a renderer does not require all the features this method may be overridden and return an expression used as where clause.

Returns	An expression used as where clause

This will be called once after startRender() and before the first call to renderFeature(). By default this returns a null string and all features will be requested. You do not need to specify the extent in here, this is taken care of separately and will be combined with a filter returned from this method.

QSet<QString> QgsRuleBasedRenderer::legendKeysForFeature(const QgsFeature& feature, QgsRenderContext& context) const override

Returns legend keys matching a specified feature.

bool QgsRuleBasedRenderer::legendSymbolItemChecked(const QString& key) override

items of symbology items in legend is checked

QgsLegendSymbolList QgsRuleBasedRenderer::legendSymbolItems() const override

Returns a list of symbology items for the legend.

bool QgsRuleBasedRenderer::legendSymbolItemsCheckable() const override

items of symbology items in legend should be checkable

QgsSymbolList QgsRuleBasedRenderer::originalSymbolsForFeature(const QgsFeature& feature, QgsRenderContext& context) const override

Equivalent of originalSymbolsForFeature() call extended to support renderers that may use more symbols per feature - similar to symbolsForFeature()

bool QgsRuleBasedRenderer::renderFeature(const QgsFeature& feature, QgsRenderContext& context, int layer = -1, bool selected = false, bool drawVertexMarker = false) override

Render a feature using this renderer in the given context.

Must be called between startRender() and stopRender() calls. Default implementation renders a symbol as determined by symbolForFeature() call. Returns true if the feature has been returned (this is used for example to determine whether the feature may be labelled).

If layer is not -1, the renderer should draw only a particula layer from symbols (in order to support symbol level rendering).

void QgsRuleBasedRenderer::setLegendSymbolItem(const QString& key, QgsSymbol* symbol) override

Sets the symbol to be used for a legend symbol item.

Parameters
key	rule key for legend symbol
symbol	new symbol for legend item. Ownership is transferred to renderer.

void QgsRuleBasedRenderer::startRender(QgsRenderContext& context, const QgsFields& fields) override

Must be called when a new render cycle is started.

Parameters
context	Additional information passed to the renderer about the job which will be rendered
fields	The fields available for rendering

A call to startRender() must always be followed by a corresponding call to stopRender() after all features have been rendered.

void QgsRuleBasedRenderer::stopRender(QgsRenderContext& context) override

Must be called when a render cycle has finished, to allow the renderer to clean up.

Calls to stopRender() must always be preceded by a call to startRender().

QgsSymbolList QgsRuleBasedRenderer::symbols(QgsRenderContext& context) const override

Returns list of symbols used by the renderer.

Parameters
context	render context

QgsSymbolList QgsRuleBasedRenderer::symbolsForFeature(const QgsFeature& feature, QgsRenderContext& context) const override

Returns list of symbols used for rendering the feature.

For renderers that do not support MoreSymbolsPerFeature it is more efficient to use symbolForFeature()

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

Returns a list of attributes required by this renderer.

Returns	A set of attributes

Attributes not listed in here may not have been requested from the provider at rendering time.

bool QgsRuleBasedRenderer::willRenderFeature(const QgsFeature& feature, QgsRenderContext& context) const override

Returns whether the renderer will render a feature or not.

Must be called between startRender() and stopRender() calls. Default implementation uses symbolForFeature().