QGIS API Documentation  2.18.3-Las Palmas (77b8c3d)
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 ()
 
 QgsExpressionContext (const QgsExpressionContext &other)
 Copy constructor. 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...
 
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::Functionfunction (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...
 
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)
 
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 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::QgsExpressionContext ( )
inline

Definition at line 254 of file qgsexpressioncontext.h.

QgsExpressionContext::QgsExpressionContext ( const QgsExpressionContext other)

Copy constructor.

Definition at line 209 of file qgsexpressioncontext.cpp.

QgsExpressionContext::~QgsExpressionContext ( )

Definition at line 232 of file qgsexpressioncontext.cpp.

Member Function Documentation

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 null if none found

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

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

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

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

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.

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.

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.

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.

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
namefunction name
Returns
function if contained by the context, otherwise null.
See also
hasFunction

Definition at line 385 of file qgsexpressioncontext.cpp.

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.

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()
Note
added in QGIS 2.16

Definition at line 462 of file qgsexpressioncontext.cpp.

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 363 of file qgsexpressioncontext.cpp.

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 238 of file qgsexpressioncontext.cpp.

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

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

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
namevariable name
See also
setHighlightedVariables()

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

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 353 of file qgsexpressioncontext.cpp.

QgsExpressionContextScope * QgsExpressionContext::lastScope ( )

Returns the last scope added to the context.

See also
scope()

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

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

Definition at line 219 of file qgsexpressioncontext.cpp.

QgsExpressionContextScope * QgsExpressionContext::popScope ( )

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

Definition at line 408 of file qgsexpressioncontext.cpp.

QgsExpressionContextScope * QgsExpressionContext::scope ( int  index)

Returns the scope at the specified index within the context.

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

Definition at line 290 of file qgsexpressioncontext.cpp.

int QgsExpressionContext::scopeCount ( ) const

Returns the number of scopes contained in the context.

Definition at line 398 of file qgsexpressioncontext.cpp.

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.

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()
Note
added in QGIS 2.16

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

Parameters
featurefeature for context
See also
feature()

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

Parameters
fieldsfields for context
See also
fields()

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

Parameters
variableNamesvariable names to highlight
See also
isHighlightedVariable()

Definition at line 259 of file qgsexpressioncontext.cpp.

void QgsExpressionContext::setOriginalValueVariable ( const QVariant value)

Sets the original value variable value for the context.

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

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 248 of file qgsexpressioncontext.cpp.

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

const QString QgsExpressionContext::EXPR_FEATURE
static

Inbuilt variable name for feature storage.

Definition at line 487 of file qgsexpressioncontext.h.

const QString QgsExpressionContext::EXPR_FIELDS
static

Inbuilt variable name for fields storage.

Definition at line 485 of file qgsexpressioncontext.h.

const QString QgsExpressionContext::EXPR_GEOMETRY_PART_COUNT
static

Inbuilt variable name for geometry part count variable.

Definition at line 495 of file qgsexpressioncontext.h.

const QString QgsExpressionContext::EXPR_GEOMETRY_PART_NUM
static

Inbuilt variable name for geometry part number variable.

Definition at line 497 of file qgsexpressioncontext.h.

const QString QgsExpressionContext::EXPR_GEOMETRY_POINT_COUNT
static

Inbuilt variable name for point count variable.

Definition at line 499 of file qgsexpressioncontext.h.

const QString QgsExpressionContext::EXPR_GEOMETRY_POINT_NUM
static

Inbuilt variable name for point number variable.

Definition at line 501 of file qgsexpressioncontext.h.

const QString QgsExpressionContext::EXPR_ORIGINAL_VALUE
static

Inbuilt variable name for value original value variable.

Definition at line 489 of file qgsexpressioncontext.h.

const QString QgsExpressionContext::EXPR_SYMBOL_ANGLE
static

Inbuilt variable name for symbol angle variable.

Definition at line 493 of file qgsexpressioncontext.h.

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: