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

#include <qgsexpressioncontext.h>

Public Member Functions
	QgsExpressionContext ()

	QgsExpressionContext (const QgsExpressionContext &other)
	Copy constructor. 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...

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...

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...

QgsExpression::Function *	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	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...

int	indexOfScope (QgsExpressionContextScope *scope) const
	Returns the index of the specified scope if it exists 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...

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)

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	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...

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...

Static Public Attributes
static const QString	EXPR_FEATURE
	Inbuilt variable name for feature storage. 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 utilise 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.

Note: added in QGIS 2.12

Definition at line 250 of file qgsexpressioncontext.h.

Constructor & Destructor Documentation

◆ QgsExpressionContext() [1/2]

QgsExpressionContext::QgsExpressionContext ( )

inline

Definition at line 254 of file qgsexpressioncontext.h.

◆ QgsExpressionContext() [2/2]

QgsExpressionContext::QgsExpressionContext ( const QgsExpressionContext & other )

Copy constructor.

Definition at line 209 of file qgsexpressioncontext.cpp.

◆ ~QgsExpressionContext()

QgsExpressionContext::~QgsExpressionContext ( )

Definition at line 232 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 null if none found

Definition at line 277 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 null if none found

Note: not available in python bindings

Definition at line 264 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 403 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()

Note: added in QGIS 2.16

Definition at line 467 of file qgsexpressioncontext.cpp.

◆ clearCachedValues()

void QgsExpressionContext::clearCachedValues ( ) const

Clears all cached values from the context.

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

Note: added in QGIS 2.16

Definition at line 472 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 430 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 443 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 337 of file qgsexpressioncontext.cpp.

◆ function()

QgsExpression::Function * 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 null.

See also: hasFunction

Definition at line 385 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 373 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()

Note: added in QGIS 2.16

Definition at line 462 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 363 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 238 of file qgsexpressioncontext.cpp.

◆ indexOfScope() [1/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 306 of file qgsexpressioncontext.cpp.

◆ indexOfScope() [2/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.

Note: added in QGIS 2.18

Definition at line 314 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.

Parameters

name	variable name

See also: setHighlightedVariables()

Definition at line 254 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 353 of file qgsexpressioncontext.cpp.

◆ lastScope()

QgsExpressionContextScope * QgsExpressionContext::lastScope ( )

Returns the last scope added to the context.

See also: scope()

Definition at line 298 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 416 of file qgsexpressioncontext.cpp.

◆ operator=()

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

Definition at line 219 of file qgsexpressioncontext.cpp.

◆ popScope()

QgsExpressionContextScope * QgsExpressionContext::popScope ( )

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

Definition at line 408 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 null if none found

See also: lastScope()

Definition at line 290 of file qgsexpressioncontext.cpp.

◆ scopeCount()

int QgsExpressionContext::scopeCount ( ) const

Returns the number of scopes contained in the context.

Definition at line 398 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 329 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()

Note: added in QGIS 2.16

Definition at line 457 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 422 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 435 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()

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

Note: added in QGIS 2.12

Definition at line 448 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 248 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 327 of file qgsexpressioncontext.cpp.

Member Data Documentation

◆ EXPR_FEATURE

const QString QgsExpressionContext::EXPR_FEATURE

static

Inbuilt variable name for feature storage.

Definition at line 487 of file qgsexpressioncontext.h.

◆ EXPR_FIELDS

const QString QgsExpressionContext::EXPR_FIELDS

static

Inbuilt variable name for fields storage.

Definition at line 485 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 495 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 497 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 499 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 501 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 489 of file qgsexpressioncontext.h.

◆ EXPR_SYMBOL_ANGLE

const QString QgsExpressionContext::EXPR_SYMBOL_ANGLE

static

Inbuilt variable name for symbol angle variable.

Definition at line 493 of file qgsexpressioncontext.h.

◆ EXPR_SYMBOL_COLOR

const QString QgsExpressionContext::EXPR_SYMBOL_COLOR

static

Inbuilt variable name for symbol color variable.

Definition at line 491 of file qgsexpressioncontext.h.

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

/tmp/buildd/qgis-2.18.21+99unstable/src/core/qgsexpressioncontext.h
/tmp/buildd/qgis-2.18.21+99unstable/src/core/qgsexpressioncontext.cpp

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QgsExpressionContext() [1/2]

◆ QgsExpressionContext() [2/2]

◆ ~QgsExpressionContext()

Member Function Documentation

◆ activeScopeForVariable() [1/2]

◆ activeScopeForVariable() [2/2]

◆ appendScope()

◆ cachedValue()

◆ clearCachedValues()

◆ feature()

◆ fields()

◆ filteredVariableNames()

◆ function()

◆ functionNames()

◆ hasCachedValue()

◆ hasFunction()

◆ hasVariable()

◆ indexOfScope() [1/2]

◆ indexOfScope() [2/2]

◆ isHighlightedVariable()

◆ isReadOnly()

◆ lastScope()

◆ operator<<()

◆ operator=()

◆ popScope()

◆ scope()

◆ scopeCount()

◆ scopes()

◆ setCachedValue()

◆ setFeature()

◆ setFields()

◆ setHighlightedVariables()

◆ setOriginalValueVariable()

◆ variable()

◆ variableNames()

Member Data Documentation

◆ EXPR_FEATURE

◆ 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