QGIS API Documentation 3.41.0-Master (3440c17df1d)
|
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) | |
QgsExpressionContext (const QList< QgsExpressionContextScope * > &scopes) | |
Initializes the context with given list of scopes. | |
~QgsExpressionContext () | |
QgsExpressionContextScope * | activeScopeForVariable (const QString &name) |
Returns the currently active scope from the context for a specified variable name. | |
const QgsExpressionContextScope * | activeScopeForVariable (const QString &name) const |
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. | |
QVariant | cachedValue (const QString &key) const |
Returns the matching cached value, if set. | |
void | clearCachedValues () const |
Clears all cached values from the context. | |
QString | description (const QString &name) const |
Returns a translated description string for the variable with specified name. | |
QgsFeature | feature () const |
Convenience function for retrieving the feature for the context, if set. | |
QgsFeedback * | feedback () const |
Returns the feedback object that can be queried regularly by the expression to check if evaluation should be canceled, if set. | |
QgsFields | fields () const |
Convenience function for retrieving the fields for the context, if set. | |
QStringList | filteredVariableNames () const |
Returns a filtered list of variables names set by all scopes in the context. | |
QgsExpressionFunction * | function (const QString &name) const |
Fetches a matching function from the context. | |
QStringList | functionNames () const |
Retrieves a list of function names contained in the context. | |
QgsGeometry | geometry () const |
Convenience function for retrieving the geometry for the context, if set. | |
bool | hasCachedValue (const QString &key) const |
Returns true if the expression context contains a cached value with a matching key. | |
bool | hasFeature () const |
Returns true if the context has a feature associated with it. | |
bool | hasFunction (const QString &name) const |
Checks whether a specified function is contained in the context. | |
bool | hasGeometry () const |
Returns true if the context has a geometry associated with it. | |
bool | hasVariable (const QString &name) const |
Check whether a variable is specified by any scope within the context. | |
QStringList | highlightedVariables () const |
Returns the current list of variables highlighted within the context. | |
int | indexOfScope (const QString &scopeName) const |
Returns the index of the first scope with a matching name within the context. | |
int | indexOfScope (QgsExpressionContextScope *scope) const |
Returns the index of the specified scope if it exists within the context. | |
bool | isHighlightedFunction (const QString &name) const |
Returns true if the specified function name is intended to be highlighted to the user. | |
bool | isHighlightedVariable (const QString &name) const |
Returns true if the specified variable name is intended to be highlighted to the user. | |
bool | isReadOnly (const QString &name) const |
Returns whether a variable is read only, and should not be modifiable by users. | |
QgsExpressionContextScope * | lastScope () |
Returns the last scope added to the context. | |
QList< QgsMapLayerStore * > | layerStores () const |
Returns the list of layer stores associated with the context. | |
QgsMapLayerStore * | loadedLayerStore () const |
Returns the destination layer store for any layers loaded during expression evaluation. | |
QgsExpressionContext & | operator<< (QgsExpressionContextScope *scope) |
Appends a scope to the end of the context. | |
QgsExpressionContext & | operator= (const QgsExpressionContext &other) |
QgsExpressionContext & | operator= (QgsExpressionContext &&other) noexcept |
QgsExpressionContextScope * | popScope () |
Removes the last scope from the expression context and return it. | |
QgsExpressionContextScope * | scope (int index) |
Returns the scope at the specified index within the context. | |
int | scopeCount () const |
Returns the number of scopes contained in the context. | |
QList< QgsExpressionContextScope * > | scopes () |
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 | setFeedback (QgsFeedback *feedback) |
Attach a feedback object that can be queried regularly by the expression engine to check if expression evaluation should be canceled. | |
void | setFields (const QgsFields &fields) |
Convenience function for setting a fields for the context. | |
void | setGeometry (const QgsGeometry &geometry) |
Convenience function for setting a geometry 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 | setLoadedLayerStore (QgsMapLayerStore *store) |
Sets the destination layer store for any layers loaded during expression evaluation. | |
void | setOriginalValueVariable (const QVariant &value) |
Sets the original value variable value for the context. | |
QList< QgsExpressionContextScope * > | takeScopes () |
Returns all scopes from this context and remove them, leaving this context without any context. | |
QString | uniqueHash (bool &ok, const QSet< QString > &variables=QSet< QString >()) const |
Returns a unique hash representing the current state of the context. | |
QVariant | variable (const QString &name) const |
Fetches a matching variable from the context. | |
QStringList | variableNames () const |
Returns a list of variables names set by all scopes in the context. | |
QVariantMap | variablesToMap () const |
Returns a map of variable name to value representing all the expression variables contained by the context. | |
Static Public Attributes | |
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_GEOMETRY_RING_NUM |
Inbuilt variable name for geometry ring 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. | |
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.
Definition at line 470 of file qgsexpressioncontext.h.
QgsExpressionContext::QgsExpressionContext | ( | ) |
Definition at line 303 of file qgsexpressioncontext.cpp.
|
explicit |
Initializes the context with given list of scopes.
Ownership of the scopes is transferred to the stack.
Definition at line 308 of file qgsexpressioncontext.cpp.
QgsExpressionContext::QgsExpressionContext | ( | const QgsExpressionContext & | other | ) |
Definition at line 314 of file qgsexpressioncontext.cpp.
QgsExpressionContext::~QgsExpressionContext | ( | ) |
Definition at line 367 of file qgsexpressioncontext.cpp.
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.
name | variable name |
nullptr
if none found Definition at line 440 of file qgsexpressioncontext.cpp.
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.
name | variable name |
nullptr
if none found Definition at line 427 of file qgsexpressioncontext.cpp.
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.
scope | expression context to append to context |
Definition at line 602 of file qgsexpressioncontext.cpp.
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.
scopes | scopes to append to context |
Definition at line 607 of file qgsexpressioncontext.cpp.
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.
key | unique key used to store cached value |
Definition at line 727 of file qgsexpressioncontext.cpp.
void QgsExpressionContext::clearCachedValues | ( | ) | const |
Clears all cached values from the context.
Definition at line 732 of file qgsexpressioncontext.cpp.
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.
Definition at line 542 of file qgsexpressioncontext.cpp.
QgsFeature QgsExpressionContext::feature | ( | ) | const |
Convenience function for retrieving the feature for the context, if set.
Definition at line 651 of file qgsexpressioncontext.cpp.
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.
Definition at line 768 of file qgsexpressioncontext.cpp.
QgsFields QgsExpressionContext::fields | ( | ) | const |
Convenience function for retrieving the fields for the context, if set.
Definition at line 703 of file qgsexpressioncontext.cpp.
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.
Definition at line 503 of file qgsexpressioncontext.cpp.
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.
name | function name |
nullptr
. Definition at line 579 of file qgsexpressioncontext.cpp.
QStringList QgsExpressionContext::functionNames | ( | ) | const |
Retrieves a list of function names contained in the context.
Definition at line 561 of file qgsexpressioncontext.cpp.
QgsGeometry QgsExpressionContext::geometry | ( | ) | const |
Convenience function for retrieving the geometry for the context, if set.
Definition at line 682 of file qgsexpressioncontext.cpp.
bool QgsExpressionContext::hasCachedValue | ( | const QString & | key | ) | const |
Returns true
if the expression context contains a cached value with a matching key.
key | unique key used to store cached value |
Definition at line 722 of file qgsexpressioncontext.cpp.
bool QgsExpressionContext::hasFeature | ( | ) | const |
Returns true
if the context has a feature associated with it.
Definition at line 641 of file qgsexpressioncontext.cpp.
bool QgsExpressionContext::hasFunction | ( | const QString & | name | ) | const |
Checks whether a specified function is contained in the context.
name | function name |
true
if context provides a matching function Definition at line 548 of file qgsexpressioncontext.cpp.
bool QgsExpressionContext::hasGeometry | ( | ) | const |
Returns true
if the context has a geometry associated with it.
Definition at line 672 of file qgsexpressioncontext.cpp.
bool QgsExpressionContext::hasVariable | ( | const QString & | name | ) | const |
Check whether a variable is specified by any scope within the context.
name | variable name |
true
if variable is set Definition at line 373 of file qgsexpressioncontext.cpp.
QStringList QgsExpressionContext::highlightedVariables | ( | ) | const |
Returns the current list of variables highlighted within the context.
Definition at line 407 of file qgsexpressioncontext.cpp.
int QgsExpressionContext::indexOfScope | ( | const QString & | scopeName | ) | const |
Returns the index of the first scope with a matching name within the context.
scopeName | name of scope to find |
Definition at line 477 of file qgsexpressioncontext.cpp.
int QgsExpressionContext::indexOfScope | ( | QgsExpressionContextScope * | scope | ) | const |
Returns the index of the specified scope if it exists within the context.
scope | scope to find |
Definition at line 469 of file qgsexpressioncontext.cpp.
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.
Definition at line 417 of file qgsexpressioncontext.cpp.
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.
Definition at line 402 of file qgsexpressioncontext.cpp.
bool QgsExpressionContext::isReadOnly | ( | const QString & | name | ) | const |
Returns whether a variable is read only, and should not be modifiable by users.
name | variable name |
true
if variable is read only. Read only status will be taken from last matching scope which contains a matching variable. Definition at line 531 of file qgsexpressioncontext.cpp.
QgsExpressionContextScope * QgsExpressionContext::lastScope | ( | ) |
Returns the last scope added to the context.
Definition at line 461 of file qgsexpressioncontext.cpp.
QList< QgsMapLayerStore * > QgsExpressionContext::layerStores | ( | ) | const |
Returns the list of layer stores associated with the context.
Definition at line 737 of file qgsexpressioncontext.cpp.
QgsMapLayerStore * QgsExpressionContext::loadedLayerStore | ( | ) | const |
Returns the destination layer store for any layers loaded during expression evaluation.
Definition at line 758 of file qgsexpressioncontext.cpp.
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 627 of file qgsexpressioncontext.cpp.
QgsExpressionContext & QgsExpressionContext::operator= | ( | const QgsExpressionContext & | other | ) |
Definition at line 348 of file qgsexpressioncontext.cpp.
|
noexcept |
Definition at line 329 of file qgsexpressioncontext.cpp.
QgsExpressionContextScope * QgsExpressionContext::popScope | ( | ) |
Removes the last scope from the expression context and return it.
Definition at line 612 of file qgsexpressioncontext.cpp.
QgsExpressionContextScope * QgsExpressionContext::scope | ( | int | index | ) |
Returns the scope at the specified index within the context.
index | index of scope |
nullptr
if none found Definition at line 453 of file qgsexpressioncontext.cpp.
int QgsExpressionContext::scopeCount | ( | ) | const |
Returns the number of scopes contained in the context.
Definition at line 597 of file qgsexpressioncontext.cpp.
|
inline |
Returns a list of scopes contained within the stack.
Definition at line 602 of file qgsexpressioncontext.h.
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.
key | unique key for retrieving cached value |
value | value to cache |
Definition at line 717 of file qgsexpressioncontext.cpp.
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.
feature | feature for context |
Definition at line 633 of file qgsexpressioncontext.cpp.
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.
Definition at line 763 of file qgsexpressioncontext.cpp.
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.
fields | fields for context |
Definition at line 695 of file qgsexpressioncontext.cpp.
void QgsExpressionContext::setGeometry | ( | const QgsGeometry & | geometry | ) |
Convenience function for setting a geometry for the context.
The geometry will be set within the last scope of the context, so will override any existing geometries within the context.
Definition at line 664 of file qgsexpressioncontext.cpp.
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.
Definition at line 422 of file qgsexpressioncontext.cpp.
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.
variableNames | variable names to highlight |
Definition at line 412 of file qgsexpressioncontext.cpp.
void QgsExpressionContext::setLoadedLayerStore | ( | QgsMapLayerStore * | store | ) |
Sets the destination layer store for any layers loaded during expression evaluation.
Ownership of the store is not transferred to the context, it is the caller's responsibility to ensure that the store remains alive for the duration of the expression context.
Definition at line 753 of file qgsexpressioncontext.cpp.
void QgsExpressionContext::setOriginalValueVariable | ( | const QVariant & | value | ) |
Sets the original value variable value for the context.
value | value for original value variable. This usually represents an original widget value before any data defined overrides have been applied. |
Definition at line 708 of file qgsexpressioncontext.cpp.
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.
Definition at line 620 of file qgsexpressioncontext.cpp.
QString QgsExpressionContext::uniqueHash | ( | bool & | ok, |
const QSet< QString > & | variables = QSet<QString>() |
||
) | const |
Returns a unique hash representing the current state of the context.
ok | will be set to true if the hash could be generated, or false if e.g. a variable value is of a type which cannot be hashed |
variables | optional names of a subset of variables to include in the hash. If not specified, all variables will be considered. |
Definition at line 773 of file qgsexpressioncontext.cpp.
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.
name | variable name |
Definition at line 384 of file qgsexpressioncontext.cpp.
QStringList QgsExpressionContext::variableNames | ( | ) | const |
Returns a list of variables names set by all scopes in the context.
Definition at line 491 of file qgsexpressioncontext.cpp.
QVariantMap QgsExpressionContext::variablesToMap | ( | ) | const |
Returns a map of variable name to value representing all the expression variables contained by the context.
Definition at line 390 of file qgsexpressioncontext.cpp.
|
static |
Inbuilt variable name for cluster color variable.
Definition at line 916 of file qgsexpressioncontext.h.
|
static |
Inbuilt variable name for cluster size variable.
Definition at line 914 of file qgsexpressioncontext.h.
|
static |
Inbuilt variable name for fields storage.
Definition at line 892 of file qgsexpressioncontext.h.
|
static |
Inbuilt variable name for geometry part count variable.
Definition at line 900 of file qgsexpressioncontext.h.
|
static |
Inbuilt variable name for geometry part number variable.
Definition at line 902 of file qgsexpressioncontext.h.
|
static |
Inbuilt variable name for point count variable.
Definition at line 910 of file qgsexpressioncontext.h.
|
static |
Inbuilt variable name for point number variable.
Definition at line 912 of file qgsexpressioncontext.h.
|
static |
Inbuilt variable name for geometry ring number variable.
Definition at line 908 of file qgsexpressioncontext.h.
|
static |
Inbuilt variable name for value original value variable.
Definition at line 894 of file qgsexpressioncontext.h.
|
static |
Inbuilt variable name for symbol angle variable.
Definition at line 898 of file qgsexpressioncontext.h.
|
static |
Inbuilt variable name for symbol color variable.
Definition at line 896 of file qgsexpressioncontext.h.