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

#include <qgsexpressioncontext.h>

Public Member Functions
	QgsExpressionContext ()=default
	Constructor for QgsExpressionContext. More...

	QgsExpressionContext (const QgsExpressionContext &other)
	Copy constructor. More...

	QgsExpressionContext (const QList< QgsExpressionContextScope * > &scopes)
	Initializes the context with given list of scopes. More...

	~QgsExpressionContext ()

QgsExpressionContextScope *	activeScopeForVariable (const QString &name)
	Returns the currently active scope from the context for a specified variable name. More...

const QgsExpressionContextScope *	activeScopeForVariable (const QString &name) const
	Returns the currently active scope from the context for a specified variable name. More...

void	appendScope (QgsExpressionContextScope *scope)
	Appends a scope to the end of the context. More...

void	appendScopes (const QList< QgsExpressionContextScope * > &scopes)
	Appends a list of scopes to the end of the context. More...

QVariant	cachedValue (const QString &key) const
	Returns the matching cached value, if set. More...

void	clearCachedValues () const
	Clears all cached values from the context. More...

QString	description (const QString &name) const
	Returns a translated description string for the variable with specified name. More...

QgsFeature	feature () const
	Convenience function for retrieving the feature for the context, if set. More...

QgsFields	fields () const
	Convenience function for retrieving the fields for the context, if set. More...

QStringList	filteredVariableNames () const
	Returns a filtered list of variables names set by all scopes in the context. More...

QgsExpressionFunction *	function (const QString &name) const
	Fetches a matching function from the context. More...

QStringList	functionNames () const
	Retrieves a list of function names contained in the context. More...

bool	hasCachedValue (const QString &key) const
	Returns `true` if the expression context contains a cached value with a matching key. More...

bool	hasFeature () const
	Returns `true` if the context has a feature associated with it. More...

bool	hasFunction (const QString &name) const
	Checks whether a specified function is contained in the context. More...

bool	hasVariable (const QString &name) const
	Check whether a variable is specified by any scope within the context. More...

QStringList	highlightedVariables () const
	Returns the current list of variables highlighted within the context. More...

int	indexOfScope (const QString &scopeName) const
	Returns the index of the first scope with a matching name within the context. More...

int	indexOfScope (QgsExpressionContextScope *scope) const
	Returns the index of the specified scope if it exists within the context. More...

bool	isHighlightedFunction (const QString &name) const
	Returns `true` if the specified function name is intended to be highlighted to the user. More...

bool	isHighlightedVariable (const QString &name) const
	Returns `true` if the specified variable name is intended to be highlighted to the user. More...

bool	isReadOnly (const QString &name) const
	Returns whether a variable is read only, and should not be modifiable by users. More...

QgsExpressionContextScope *	lastScope ()
	Returns the last scope added to the context. More...

QgsExpressionContext &	operator<< (QgsExpressionContextScope *scope)
	Appends a scope to the end of the context. More...

QgsExpressionContext &	operator= (const QgsExpressionContext &other)

QgsExpressionContext &	operator= (QgsExpressionContext &&other) noexcept

QgsExpressionContextScope *	popScope ()
	Removes the last scope from the expression context and return it. More...

QgsExpressionContextScope *	scope (int index)
	Returns the scope at the specified index within the context. More...

int	scopeCount () const
	Returns the number of scopes contained in the context. More...

QList< QgsExpressionContextScope * >	scopes ()
	Returns a list of scopes contained within the stack. More...

void	setCachedValue (const QString &key, const QVariant &value) const
	Sets a value to cache within the expression context. More...

void	setFeature (const QgsFeature &feature)
	Convenience function for setting a feature for the context. More...

void	setFields (const QgsFields &fields)
	Convenience function for setting a fields for the context. More...

void	setHighlightedFunctions (const QStringList &names)
	Sets the list of function names intended to be highlighted to the user. More...

void	setHighlightedVariables (const QStringList &variableNames)
	Sets the list of variable names within the context intended to be highlighted to the user. More...

void	setOriginalValueVariable (const QVariant &value)
	Sets the original value variable value for the context. More...

QList< QgsExpressionContextScope * >	takeScopes ()
	Returns all scopes from this context and remove them, leaving this context without any context. More...

QVariant	variable (const QString &name) const
	Fetches a matching variable from the context. More...

QStringList	variableNames () const
	Returns a list of variables names set by all scopes in the context. More...

QVariantMap	variablesToMap () const
	Returns a map of variable name to value representing all the expression variables contained by the context. More...

Static Public Attributes
static const QString	EXPR_CLUSTER_COLOR
	Inbuilt variable name for cluster color variable. More...

static const QString	EXPR_CLUSTER_SIZE
	Inbuilt variable name for cluster size variable. More...

static const QString	EXPR_FIELDS
	Inbuilt variable name for fields storage. More...

static const QString	EXPR_GEOMETRY_PART_COUNT
	Inbuilt variable name for geometry part count variable. More...

static const QString	EXPR_GEOMETRY_PART_NUM
	Inbuilt variable name for geometry part number variable. More...

static const QString	EXPR_GEOMETRY_POINT_COUNT
	Inbuilt variable name for point count variable. More...

static const QString	EXPR_GEOMETRY_POINT_NUM
	Inbuilt variable name for point number variable. More...

static const QString	EXPR_ORIGINAL_VALUE
	Inbuilt variable name for value original value variable. More...

static const QString	EXPR_SYMBOL_ANGLE
	Inbuilt variable name for symbol angle variable. More...

static const QString	EXPR_SYMBOL_COLOR
	Inbuilt variable name for symbol color variable. More...

Detailed Description

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

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.

Since: QGIS 2.12

Definition at line 369 of file qgsexpressioncontext.h.

Constructor & Destructor Documentation

◆ QgsExpressionContext() [1/3]

QgsExpressionContext::QgsExpressionContext ( )

default

Constructor for QgsExpressionContext.

◆ QgsExpressionContext() [2/3]

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

explicit

Initializes the context with given list of scopes.

Ownership of the scopes is transferred to the stack.

Since: QGIS 3.0

Definition at line 230 of file qgsexpressioncontext.cpp.

◆ QgsExpressionContext() [3/3]

QgsExpressionContext::QgsExpressionContext ( const QgsExpressionContext & other )

Copy constructor.

Definition at line 235 of file qgsexpressioncontext.cpp.

◆ ~QgsExpressionContext()

QgsExpressionContext::~QgsExpressionContext ( )

Definition at line 279 of file qgsexpressioncontext.cpp.

Member Function Documentation

◆ activeScopeForVariable() [1/2]

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

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

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

Parameters

name	variable name

Returns: matching scope containing variable, or nullptr if none found

Definition at line 352 of file qgsexpressioncontext.cpp.

◆ activeScopeForVariable() [2/2]

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

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

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

Parameters

name	variable name

Returns: matching scope containing variable, or nullptr if none found

Note: not available in Python bindings

Definition at line 339 of file qgsexpressioncontext.cpp.

◆ appendScope()

void QgsExpressionContext::appendScope ( 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.

Parameters

scope expression context to append to context

Definition at line 490 of file qgsexpressioncontext.cpp.

◆ appendScopes()

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

Appends a list of scopes to the end of the 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.

Parameters

scopes scopes to append to context

Since: QGIS 3.0

Definition at line 495 of file qgsexpressioncontext.cpp.

◆ cachedValue()

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

Returns the matching cached value, if set.

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

Parameters

key	unique key used to store cached value

Returns: matching cached value, or invalid QVariant if not set

See also: setCachedValue(); hasCachedValue(); clearCachedValues()

Since: QGIS 2.16

Definition at line 585 of file qgsexpressioncontext.cpp.

◆ clearCachedValues()

void QgsExpressionContext::clearCachedValues ( ) const

Clears all cached values from the context.

See also: setCachedValue(); hasCachedValue(); cachedValue()

Since: QGIS 2.16

Definition at line 590 of file qgsexpressioncontext.cpp.

◆ description()

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.

Since: QGIS 3.0

Definition at line 442 of file qgsexpressioncontext.cpp.

◆ feature()

QgsFeature QgsExpressionContext::feature ( ) const

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

See also: setFeature

Definition at line 540 of file qgsexpressioncontext.cpp.

◆ fields()

QgsFields QgsExpressionContext::fields ( ) const

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

See also: setFields

Definition at line 561 of file qgsexpressioncontext.cpp.

◆ filteredVariableNames()

QStringList QgsExpressionContext::filteredVariableNames ( ) const

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

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

Returns: filtered list of unique variable names

See also: variableNames

Definition at line 414 of file qgsexpressioncontext.cpp.

◆ function()

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

Fetches a matching function from the context.

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

Parameters

name	function name

Returns: function if contained by the context, otherwise nullptr.

See also: hasFunction

Definition at line 472 of file qgsexpressioncontext.cpp.

◆ functionNames()

QStringList QgsExpressionContext::functionNames ( ) const

Retrieves a list of function names contained in the context.

See also: function(); variableNames()

Definition at line 459 of file qgsexpressioncontext.cpp.

◆ hasCachedValue()

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

See also: setCachedValue(); cachedValue(); clearCachedValues()

Since: QGIS 2.16

Definition at line 580 of file qgsexpressioncontext.cpp.

◆ hasFeature()

bool QgsExpressionContext::hasFeature ( ) const

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

See also: feature()

Since: QGIS 3.0

Definition at line 529 of file qgsexpressioncontext.cpp.

◆ hasFunction()

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

See also: function

Definition at line 448 of file qgsexpressioncontext.cpp.

◆ hasVariable()

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

See also: variable(); variableNames()

Definition at line 285 of file qgsexpressioncontext.cpp.

◆ highlightedVariables()

QStringList QgsExpressionContext::highlightedVariables ( ) const

Returns the current list of variables highlighted within the context.

See also: setHighlightedVariables()

Since: QGIS 3.8

Definition at line 319 of file qgsexpressioncontext.cpp.

◆ indexOfScope() [1/2]

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.

Since: QGIS 3.0

Definition at line 389 of file qgsexpressioncontext.cpp.

◆ indexOfScope() [2/2]

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.

Definition at line 381 of file qgsexpressioncontext.cpp.

◆ isHighlightedFunction()

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.

See also: setHighlightedFunctions(); isHighlightedVariable()

Since: QGIS 3.4

Definition at line 329 of file qgsexpressioncontext.cpp.

◆ isHighlightedVariable()

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.

See also: setHighlightedVariables(); isHighlightedFunction()

Definition at line 314 of file qgsexpressioncontext.cpp.

◆ isReadOnly()

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.

Definition at line 431 of file qgsexpressioncontext.cpp.

◆ lastScope()

QgsExpressionContextScope * QgsExpressionContext::lastScope ( )

Returns the last scope added to the context.

See also: scope()

Definition at line 373 of file qgsexpressioncontext.cpp.

◆ operator<<()

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.

Definition at line 515 of file qgsexpressioncontext.cpp.

◆ operator=() [1/2]

QgsExpressionContext & QgsExpressionContext::operator= ( const QgsExpressionContext & other )

Definition at line 262 of file qgsexpressioncontext.cpp.

◆ operator=() [2/2]

QgsExpressionContext & QgsExpressionContext::operator= ( QgsExpressionContext && other )

noexcept

Definition at line 246 of file qgsexpressioncontext.cpp.

◆ popScope()

QgsExpressionContextScope * QgsExpressionContext::popScope ( )

Removes the last scope from the expression context and return it.

Definition at line 500 of file qgsexpressioncontext.cpp.

◆ scope()

QgsExpressionContextScope * QgsExpressionContext::scope ( int index )

Returns the scope at the specified index within the context.

Parameters

index index of scope

Returns: matching scope, or nullptr if none found

See also: lastScope()

Definition at line 365 of file qgsexpressioncontext.cpp.

◆ scopeCount()

int QgsExpressionContext::scopeCount ( ) const

Returns the number of scopes contained in the context.

Definition at line 485 of file qgsexpressioncontext.cpp.

◆ scopes()

QList< QgsExpressionContextScope * > QgsExpressionContext::scopes ( )

inline

Returns a list of scopes contained within the stack.

Returns: list of pointers to scopes

Definition at line 507 of file qgsexpressioncontext.h.

◆ setCachedValue()

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

Sets a value to cache within the expression context.

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

Parameters

key	unique key for retrieving cached value
value	value to cache

See also: hasCachedValue(); cachedValue(); clearCachedValues()

Since: QGIS 2.16

Definition at line 575 of file qgsexpressioncontext.cpp.

◆ setFeature()

void QgsExpressionContext::setFeature ( const QgsFeature & feature )

Convenience function for setting a feature for the context.

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

Parameters

feature feature for context

See also: feature()

Definition at line 521 of file qgsexpressioncontext.cpp.

◆ setFields()

void QgsExpressionContext::setFields ( const QgsFields & fields )

Convenience function for setting a fields for the context.

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

Parameters

fields fields for context

See also: fields()

Definition at line 553 of file qgsexpressioncontext.cpp.

◆ setHighlightedFunctions()

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.

See also: isHighlightedFunction(); setHighlightedVariables()

Since: QGIS 3.4

Definition at line 334 of file qgsexpressioncontext.cpp.

◆ setHighlightedVariables()

void QgsExpressionContext::setHighlightedVariables ( const QStringList & variableNames )

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

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

Parameters

variableNames variable names to highlight

See also: isHighlightedVariable(); setHighlightedFunctions()

Definition at line 324 of file qgsexpressioncontext.cpp.

◆ setOriginalValueVariable()

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 an original widget value before any data defined overrides have been applied.

Since: QGIS 2.12

Definition at line 566 of file qgsexpressioncontext.cpp.

◆ takeScopes()

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.

Note: Not available in Python

Since: QGIS 3.0

Definition at line 508 of file qgsexpressioncontext.cpp.

◆ variable()

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

Fetches a matching variable from the context.

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

Parameters

name	variable name

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

See also: hasVariable(); variableNames()

Definition at line 296 of file qgsexpressioncontext.cpp.

◆ variableNames()

QStringList QgsExpressionContext::variableNames ( ) const

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

Returns: list of unique variable names

See also: filteredVariableNames; functionNames; hasVariable; variable

Definition at line 403 of file qgsexpressioncontext.cpp.

◆ variablesToMap()

QVariantMap QgsExpressionContext::variablesToMap ( ) const

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

Since: QGIS 3.0

Definition at line 302 of file qgsexpressioncontext.cpp.

Member Data Documentation

◆ EXPR_CLUSTER_COLOR

const QString QgsExpressionContext::EXPR_CLUSTER_COLOR

static

Inbuilt variable name for cluster color variable.

Definition at line 737 of file qgsexpressioncontext.h.

◆ EXPR_CLUSTER_SIZE

const QString QgsExpressionContext::EXPR_CLUSTER_SIZE

static

Inbuilt variable name for cluster size variable.

Definition at line 735 of file qgsexpressioncontext.h.

◆ EXPR_FIELDS

const QString QgsExpressionContext::EXPR_FIELDS

static

Inbuilt variable name for fields storage.

Definition at line 719 of file qgsexpressioncontext.h.

◆ EXPR_GEOMETRY_PART_COUNT

const QString QgsExpressionContext::EXPR_GEOMETRY_PART_COUNT

static

Inbuilt variable name for geometry part count variable.

Definition at line 727 of file qgsexpressioncontext.h.

◆ EXPR_GEOMETRY_PART_NUM

const QString QgsExpressionContext::EXPR_GEOMETRY_PART_NUM

static

Inbuilt variable name for geometry part number variable.

Definition at line 729 of file qgsexpressioncontext.h.

◆ EXPR_GEOMETRY_POINT_COUNT

const QString QgsExpressionContext::EXPR_GEOMETRY_POINT_COUNT

static

Inbuilt variable name for point count variable.

Definition at line 731 of file qgsexpressioncontext.h.

◆ EXPR_GEOMETRY_POINT_NUM

const QString QgsExpressionContext::EXPR_GEOMETRY_POINT_NUM

static

Inbuilt variable name for point number variable.

Definition at line 733 of file qgsexpressioncontext.h.

◆ EXPR_ORIGINAL_VALUE

const QString QgsExpressionContext::EXPR_ORIGINAL_VALUE

static

Inbuilt variable name for value original value variable.

Definition at line 721 of file qgsexpressioncontext.h.

◆ EXPR_SYMBOL_ANGLE

const QString QgsExpressionContext::EXPR_SYMBOL_ANGLE

static

Inbuilt variable name for symbol angle variable.

Definition at line 725 of file qgsexpressioncontext.h.

◆ EXPR_SYMBOL_COLOR

const QString QgsExpressionContext::EXPR_SYMBOL_COLOR

static

Inbuilt variable name for symbol color variable.

Definition at line 723 of file qgsexpressioncontext.h.

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

/build/qgis-3.16.0+99unstable/src/core/qgsexpressioncontext.h
/build/qgis-3.16.0+99unstable/src/core/qgsexpressioncontext.cpp

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QgsExpressionContext() [1/3]

◆ QgsExpressionContext() [2/3]

◆ QgsExpressionContext() [3/3]

◆ ~QgsExpressionContext()

Member Function Documentation

◆ activeScopeForVariable() [1/2]

◆ activeScopeForVariable() [2/2]

◆ appendScope()

◆ appendScopes()

◆ cachedValue()

◆ clearCachedValues()

◆ description()

◆ feature()

◆ fields()

◆ filteredVariableNames()

◆ function()

◆ functionNames()

◆ hasCachedValue()

◆ hasFeature()

◆ hasFunction()

◆ hasVariable()

◆ highlightedVariables()

◆ indexOfScope() [1/2]

◆ indexOfScope() [2/2]

◆ isHighlightedFunction()

◆ isHighlightedVariable()

◆ isReadOnly()

◆ lastScope()

◆ operator<<()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ popScope()

◆ scope()

◆ scopeCount()

◆ scopes()

◆ setCachedValue()

◆ setFeature()

◆ setFields()

◆ setHighlightedFunctions()

◆ setHighlightedVariables()

◆ setOriginalValueVariable()

◆ takeScopes()

◆ variable()

◆ variableNames()

◆ variablesToMap()

Member Data Documentation

◆ EXPR_CLUSTER_COLOR

◆ EXPR_CLUSTER_SIZE

◆ EXPR_FIELDS

◆ EXPR_GEOMETRY_PART_COUNT

◆ EXPR_GEOMETRY_PART_NUM

◆ EXPR_GEOMETRY_POINT_COUNT

◆ EXPR_GEOMETRY_POINT_NUM

◆ EXPR_ORIGINAL_VALUE

◆ EXPR_SYMBOL_ANGLE

◆ EXPR_SYMBOL_COLOR