QgsExpressionContext class

Expression contexts are used to encapsulate the parameters around which a QgsExpression should be evaluated.

Reference

QgsExpressions can then utilize the information stored within a context to contextualise their evaluated result. A QgsExpressionContext consists of a stack of QgsExpressionContextScope objects, where scopes added later to the stack will override conflicting variables and functions from scopes lower in the stack.

See QgsExpressionContextUtils for helper methods for working with QgsExpressionContext objects.

Public static variables

static const QString EXPR_CLUSTER_COLOR: Inbuilt variable name for cluster color variable.
static const QString EXPR_CLUSTER_SIZE: Inbuilt variable name for cluster size variable.
static const QString EXPR_FIELDS: Inbuilt variable name for fields storage.
static const QString EXPR_GEOMETRY_PART_COUNT: Inbuilt variable name for geometry part count variable.
static const QString EXPR_GEOMETRY_PART_NUM: Inbuilt variable name for geometry part number variable.
static const QString EXPR_GEOMETRY_POINT_COUNT: Inbuilt variable name for point count variable.
static const QString EXPR_GEOMETRY_POINT_NUM: Inbuilt variable name for point number variable.
static const QString EXPR_ORIGINAL_VALUE: Inbuilt variable name for value original value variable.
static const QString EXPR_SYMBOL_ANGLE: Inbuilt variable name for symbol angle variable.
static const QString EXPR_SYMBOL_COLOR: Inbuilt variable name for symbol color variable.

Constructors, destructors, conversion operators

QgsExpressionContext() defaulted: Constructor for QgsExpressionContext.
QgsExpressionContext(const QList<QgsExpressionContextScope*>& scopes) explicit: Initializes the context with given list of scopes.
QgsExpressionContext(const QgsExpressionContext& other): Copy constructor.

Public functions

auto activeScopeForVariable(const QString& name) -> QgsExpressionContextScope*: Returns the currently active scope from the context for a specified variable name.
auto activeScopeForVariable(const QString& name) const -> const QgsExpressionContextScope*: Returns the currently active scope from the context for a specified variable name.
void appendScope(QgsExpressionContextScope* scope): Appends a scope to the end of the context.
void appendScopes(const QList<QgsExpressionContextScope*>& scopes): Appends a list of scopes to the end of the context.
auto cachedValue(const QString& key) const -> QVariant: Returns the matching cached value, if set.
void clearCachedValues() const: Clears all cached values from the context.
auto description(const QString& name) const -> QString: Returns a translated description string for the variable with specified name.
auto feature() const -> QgsFeature: Convenience function for retrieving the feature for the context, if set.
auto fields() const -> QgsFields: Convenience function for retrieving the fields for the context, if set.
auto filteredVariableNames() const -> QStringList: Returns a filtered list of variables names set by all scopes in the context.
auto function(const QString& name) const -> QgsExpressionFunction*: Fetches a matching function from the context.
auto functionNames() const -> QStringList: Retrieves a list of function names contained in the context.
auto hasCachedValue(const QString& key) const -> bool: Returns true if the expression context contains a cached value with a matching key.
auto hasFeature() const -> bool: Returns true if the context has a feature associated with it.
auto hasFunction(const QString& name) const -> bool: Checks whether a specified function is contained in the context.
auto hasVariable(const QString& name) const -> bool: Check whether a variable is specified by any scope within the context.
auto indexOfScope(QgsExpressionContextScope* scope) const -> int: Returns the index of the specified scope if it exists within the context.
auto indexOfScope(const QString& scopeName) const -> int: Returns the index of the first scope with a matching name within the context.
auto isHighlightedFunction(const QString& name) const -> bool: Returns true if the specified function name is intended to be highlighted to the user.
auto isHighlightedVariable(const QString& name) const -> bool: Returns true if the specified variable name is intended to be highlighted to the user.
auto isReadOnly(const QString& name) const -> bool: Returns whether a variable is read only, and should not be modifiable by users.
auto lastScope() -> QgsExpressionContextScope*: Returns the last scope added to the context.
auto operator<<(QgsExpressionContextScope* scope) -> QgsExpressionContext&: Appends a scope to the end of the context.
auto popScope() -> QgsExpressionContextScope*: Removes the last scope from the expression context and return it.
auto scope(int index) -> QgsExpressionContextScope*: Returns the scope at the specified index within the context.
auto scopeCount() const -> int: Returns the number of scopes contained in the context.
auto scopes() -> QList<QgsExpressionContextScope*>: Returns a list of scopes contained within the stack.
void setCachedValue(const QString& key, const QVariant& value) const: Sets a value to cache within the expression context.
void setFeature(const QgsFeature& feature): Convenience function for setting a feature for the context.
void setFields(const QgsFields& fields): Convenience function for setting a fields for the context.
void setHighlightedFunctions(const QStringList& names): Sets the list of function names intended to be highlighted to the user.
void setHighlightedVariables(const QStringList& variableNames): Sets the list of variable names within the context intended to be highlighted to the user.
void setOriginalValueVariable(const QVariant& value): Sets the original value variable value for the context.
auto takeScopes() -> QList<QgsExpressionContextScope*>: Returns all scopes from this context and remove them, leaving this context without any context.
auto variable(const QString& name) const -> QVariant: Fetches a matching variable from the context.
auto variableNames() const -> QStringList: Returns a list of variables names set by all scopes in the context.
auto variablesToMap() const -> QVariantMap: Returns a map of variable name to value representing all the expression variables contained by the context.

Function documentation

QgsExpressionContext::QgsExpressionContext(const QList<QgsExpressionContextScope*>& scopes) explicit

Initializes the context with given list of scopes.

Ownership of the scopes is transferred to the stack.

QgsExpressionContextScope* QgsExpressionContext::activeScopeForVariable(const QString& name)

Returns the currently active scope from the context for a specified variable name.

Parameters
name	variable name
Returns	matching scope containing variable, or null if none found

As scopes later in the stack override earlier contexts, this will be the last matching scope which contains a matching variable.

const QgsExpressionContextScope* QgsExpressionContext::activeScopeForVariable(const QString& name) const

Returns the currently active scope from the context for a specified variable name.

Parameters
name	variable name
Returns	matching scope containing variable, or null if none found

As scopes later in the stack override earlier contexts, this will be the last matching scope which contains a matching variable.

void QgsExpressionContext::appendScope(QgsExpressionContextScope* scope)

Appends a scope to the end of the context.

Parameters
scope	expression context to append to context

This scope will override any matching variables or functions provided by existing scopes within the context. Ownership of the scope is transferred to the stack.

void QgsExpressionContext::appendScopes(const QList<QgsExpressionContextScope*>& scopes)

Appends a list of scopes to the end of the context.

Parameters
scopes	scopes to append to context

This scopes will override any matching variables or functions provided by existing scopes within the context. Ownership of the scopes is transferred to the stack.

QVariant QgsExpressionContext::cachedValue(const QString& key) const

Returns the matching cached value, if set.

Parameters
key	unique key used to store cached value
Returns	matching cached value, or invalid QVariant if not set

This can be used to retrieve the previously stored results of an expensive expression sub-calculation.

void QgsExpressionContext::clearCachedValues() const

Clears all cached values from the context.

QString QgsExpressionContext::description(const QString& name) const

Returns a translated description string for the variable with specified name.

If no specific description has been provided for the variable, the value from QgsExpression::variableHelpText() will be returned.

QgsFeature QgsExpressionContext::feature() const

Convenience function for retrieving the feature for the context, if set.

QgsFields QgsExpressionContext::fields() const

Convenience function for retrieving the fields for the context, if set.

QStringList QgsExpressionContext::filteredVariableNames() const

Returns a filtered list of variables names set by all scopes in the context.

Returns	filtered list of unique variable names

The included variables are those which should be seen by users.

QgsExpressionFunction* QgsExpressionContext::function(const QString& name) const

Fetches a matching function from the context.

Parameters
name	function name
Returns	function if contained by the context, otherwise null.

The function will be fetched from the last scope contained within the context which has a matching function set.

QStringList QgsExpressionContext::functionNames() const

Retrieves a list of function names contained in the context.

bool QgsExpressionContext::hasCachedValue(const QString& key) const

Returns true if the expression context contains a cached value with a matching key.

Parameters
key	unique key used to store cached value

bool QgsExpressionContext::hasFeature() const

Returns true if the context has a feature associated with it.

bool QgsExpressionContext::hasFunction(const QString& name) const

Checks whether a specified function is contained in the context.

Parameters
name	function name
Returns	true if context provides a matching function

bool QgsExpressionContext::hasVariable(const QString& name) const

Check whether a variable is specified by any scope within the context.

Parameters
name	variable name
Returns	true if variable is set

int QgsExpressionContext::indexOfScope(QgsExpressionContextScope* scope) const

Returns the index of the specified scope if it exists within the context.

Parameters
scope	scope to find
Returns	index of scope, or -1 if scope was not found within the context.

int QgsExpressionContext::indexOfScope(const QString& scopeName) const

Returns the index of the first scope with a matching name within the context.

Parameters
scopeName	name of scope to find
Returns	index of scope, or -1 if scope was not found within the context.

bool QgsExpressionContext::isHighlightedFunction(const QString& name) const

Returns true if the specified function name is intended to be highlighted to the user.

This is used by the expression builder to more prominently display the function.

bool QgsExpressionContext::isHighlightedVariable(const QString& name) const

Returns true if the specified variable name is intended to be highlighted to the user.

This is used by the expression builder to more prominently display the variable.

bool QgsExpressionContext::isReadOnly(const QString& name) const

Returns whether a variable is read only, and should not be modifiable by users.

Parameters
name	variable name
Returns	true if variable is read only. Read only status will be taken from last matching scope which contains a matching variable.

QgsExpressionContextScope* QgsExpressionContext::lastScope()

Returns the last scope added to the context.

QgsExpressionContext& QgsExpressionContext::operator<<(QgsExpressionContextScope* scope)

Appends a scope to the end of the context.

This scope will override any matching variables or functions provided by existing scopes within the context. Ownership of the scope is transferred to the stack.

QgsExpressionContextScope* QgsExpressionContext::scope(int index)

Returns the scope at the specified index within the context.

Parameters
index	index of scope
Returns	matching scope, or null if none found

QList<QgsExpressionContextScope*> QgsExpressionContext::scopes()

Returns a list of scopes contained within the stack.

Returns	list of pointers to scopes

void QgsExpressionContext::setCachedValue(const QString& key, const QVariant& value) const

Sets a value to cache within the expression context.

Parameters
key	unique key for retrieving cached value
value	value to cache

This can be used to cache the results of expensive expression sub-calculations, to speed up future evaluations using the same expression context.

void QgsExpressionContext::setFeature(const QgsFeature& feature)

Convenience function for setting a feature for the context.

Parameters
feature	feature for context

The feature will be set within the last scope of the context, so will override any existing features within the context.

void QgsExpressionContext::setFields(const QgsFields& fields)

Convenience function for setting a fields for the context.

Parameters
fields	fields for context

The fields will be set within the last scope of the context, so will override any existing fields within the context.

void QgsExpressionContext::setHighlightedFunctions(const QStringList& names)

Sets the list of function names intended to be highlighted to the user.

This is used by the expression builder to more prominently display these functions.

Note that these function names may include standard functions which are not functions specific to this context, and these standard functions will also be highlighted to users.

void QgsExpressionContext::setHighlightedVariables(const QStringList& variableNames)

Sets the list of variable names within the context intended to be highlighted to the user.

Parameters
variableNames	variable names to highlight

This is used by the expression builder to more prominently display these variables.

void QgsExpressionContext::setOriginalValueVariable(const QVariant& value)

Sets the original value variable value for the context.

Parameters
value	value for original value variable. This usually represents the an original widget value before any data defined overrides have been applied.

QList<QgsExpressionContextScope*> QgsExpressionContext::takeScopes()

Returns all scopes from this context and remove them, leaving this context without any context.

Ownership is transferred to the caller.

QVariant QgsExpressionContext::variable(const QString& name) const

Fetches a matching variable from the context.

Parameters
name	variable name
Returns	variable value if matching variable exists in the context, otherwise an invalid QVariant

The variable will be fetched from the last scope contained within the context which has a matching variable set.

QStringList QgsExpressionContext::variableNames() const

Returns a list of variables names set by all scopes in the context.

Returns	list of unique variable names

QVariantMap QgsExpressionContext::variablesToMap() const

Returns a map of variable name to value representing all the expression variables contained by the context.