QGIS API Documentation  3.22.4-Białowieża (ce8e65e95e)
Public Member Functions | Static Public Attributes | List of all members
QgsExpressionContext Class Reference

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 ()
 
QgsExpressionContextScopeactiveScopeForVariable (const QString &name)
 Returns the currently active scope from the context for a specified variable name. More...
 
const QgsExpressionContextScopeactiveScopeForVariable (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...
 
QgsFeedbackfeedback () const
 Returns the feedback object that can be queried regularly by the expression to check if evaluation should be canceled, 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...
 
QgsExpressionFunctionfunction (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...
 
QgsExpressionContextScopelastScope ()
 Returns the last scope added to the context. More...
 
QgsExpressionContextoperator<< (QgsExpressionContextScope *scope)
 Appends a scope to the end of the context. More...
 
QgsExpressionContextoperator= (const QgsExpressionContext &other)
 
QgsExpressionContextoperator= (QgsExpressionContext &&other) noexcept
 
QgsExpressionContextScopepopScope ()
 Removes the last scope from the expression context and return it. More...
 
QgsExpressionContextScopescope (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 setFeedback (QgsFeedback *feedback)
 Attach a feedback object that can be queried regularly by the expression engine to check if expression evaluation should be canceled. 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_GEOMETRY_RING_NUM
 Inbuilt variable name for geometry ring 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 371 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 231 of file qgsexpressioncontext.cpp.

◆ QgsExpressionContext() [3/3]

QgsExpressionContext::QgsExpressionContext ( const QgsExpressionContext other)

Copy constructor.

Definition at line 236 of file qgsexpressioncontext.cpp.

◆ ~QgsExpressionContext()

QgsExpressionContext::~QgsExpressionContext ( )

Definition at line 280 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
namevariable name
Returns
matching scope containing variable, or nullptr if none found

Definition at line 353 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
namevariable name
Returns
matching scope containing variable, or nullptr if none found
Note
not available in Python bindings

Definition at line 340 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
scopeexpression context to append to context

Definition at line 491 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
scopesscopes to append to context
Since
QGIS 3.0

Definition at line 496 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
keyunique 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 586 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 591 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 443 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 541 of file qgsexpressioncontext.cpp.

◆ feedback()

QgsFeedback * QgsExpressionContext::feedback ( ) const

Returns the feedback object that can be queried regularly by the expression to check if evaluation should be canceled, if set.

See also
setFeedback()
Since
QGIS 3.20

Definition at line 601 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 562 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 415 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
namefunction name
Returns
function if contained by the context, otherwise nullptr.
See also
hasFunction

Definition at line 473 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 460 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
keyunique key used to store cached value
See also
setCachedValue()
cachedValue()
clearCachedValues()
Since
QGIS 2.16

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

◆ hasFunction()

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

Checks whether a specified function is contained in the context.

Parameters
namefunction name
Returns
true if context provides a matching function
See also
function

Definition at line 449 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
namevariable name
Returns
true if variable is set
See also
variable()
variableNames()

Definition at line 286 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 320 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
scopeNamename 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 390 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
scopescope to find
Returns
index of scope, or -1 if scope was not found within the context.

Definition at line 382 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 330 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 315 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
namevariable 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 432 of file qgsexpressioncontext.cpp.

◆ lastScope()

QgsExpressionContextScope * QgsExpressionContext::lastScope ( )

Returns the last scope added to the context.

See also
scope()

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

◆ operator=() [1/2]

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

Definition at line 263 of file qgsexpressioncontext.cpp.

◆ operator=() [2/2]

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

Definition at line 247 of file qgsexpressioncontext.cpp.

◆ popScope()

QgsExpressionContextScope * QgsExpressionContext::popScope ( )

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

Definition at line 501 of file qgsexpressioncontext.cpp.

◆ scope()

QgsExpressionContextScope * QgsExpressionContext::scope ( int  index)

Returns the scope at the specified index within the context.

Parameters
indexindex of scope
Returns
matching scope, or nullptr if none found
See also
lastScope()

Definition at line 366 of file qgsexpressioncontext.cpp.

◆ scopeCount()

int QgsExpressionContext::scopeCount ( ) const

Returns the number of scopes contained in the context.

Definition at line 486 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 509 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
keyunique key for retrieving cached value
valuevalue to cache
See also
hasCachedValue()
cachedValue()
clearCachedValues()
Since
QGIS 2.16

Definition at line 576 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
featurefeature for context
See also
feature()

Definition at line 522 of file qgsexpressioncontext.cpp.

◆ setFeedback()

void QgsExpressionContext::setFeedback ( QgsFeedback feedback)

Attach a feedback object that can be queried regularly by the expression engine to check if expression evaluation should be canceled.

Ownership of feedback is NOT transferred, and the caller must take care that it exists for the lifetime of the expression context.

See also
feedback()
Since
QGIS 3.20

Definition at line 596 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
fieldsfields for context
See also
fields()

Definition at line 554 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 335 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
variableNamesvariable names to highlight
See also
isHighlightedVariable()
setHighlightedFunctions()

Definition at line 325 of file qgsexpressioncontext.cpp.

◆ setOriginalValueVariable()

void QgsExpressionContext::setOriginalValueVariable ( const QVariant &  value)

Sets the original value variable value for the context.

Parameters
valuevalue 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 567 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 509 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
namevariable name
Returns
variable value if matching variable exists in the context, otherwise an invalid QVariant
See also
hasVariable()
variableNames()

Definition at line 297 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 404 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 303 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 768 of file qgsexpressioncontext.h.

◆ EXPR_CLUSTER_SIZE

const QString QgsExpressionContext::EXPR_CLUSTER_SIZE
static

Inbuilt variable name for cluster size variable.

Definition at line 766 of file qgsexpressioncontext.h.

◆ EXPR_FIELDS

const QString QgsExpressionContext::EXPR_FIELDS
static

Inbuilt variable name for fields storage.

Definition at line 744 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 752 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 754 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 762 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 764 of file qgsexpressioncontext.h.

◆ EXPR_GEOMETRY_RING_NUM

const QString QgsExpressionContext::EXPR_GEOMETRY_RING_NUM
static

Inbuilt variable name for geometry ring number variable.

Since
QGIS 3.20

Definition at line 760 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 746 of file qgsexpressioncontext.h.

◆ EXPR_SYMBOL_ANGLE

const QString QgsExpressionContext::EXPR_SYMBOL_ANGLE
static

Inbuilt variable name for symbol angle variable.

Definition at line 750 of file qgsexpressioncontext.h.

◆ EXPR_SYMBOL_COLOR

const QString QgsExpressionContext::EXPR_SYMBOL_COLOR
static

Inbuilt variable name for symbol color variable.

Definition at line 748 of file qgsexpressioncontext.h.


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