QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Classes | Public Member Functions | List of all members
QgsExpressionContextScope Class Reference

Single scope for storing variables and functions for use within a QgsExpressionContext. More...

#include <qgsexpressioncontext.h>

Classes

struct  StaticVariable
 Single variable definition for use within a QgsExpressionContextScope. More...
 

Public Member Functions

 QgsExpressionContextScope (const QgsExpressionContextScope &other)
 Copy constructor. More...
 
 QgsExpressionContextScope (const QString &name=QString())
 Constructor for QgsExpressionContextScope. More...
 
 ~QgsExpressionContextScope ()
 
void addFunction (const QString &name, QgsScopedExpressionFunction *function)
 Adds a function to the scope. More...
 
void addHiddenVariable (const QString &hiddenVariable)
 Adds the passed variable to a list of hidden variables that won't be visible in the expression builder dialog and widget. More...
 
void addLayerStore (QgsMapLayerStore *store)
 Adds a layer store to the scope. More...
 
void addVariable (const QgsExpressionContextScope::StaticVariable &variable)
 Adds a variable into the context scope. More...
 
QString description (const QString &name) const
 Returns the translated description for the variable with the specified name (if set). More...
 
QgsFeature feature () const
 Sets the feature associated with the scope. More...
 
QStringList filteredVariableNames () const
 Returns a filtered and sorted list of variable names contained within the scope. More...
 
QgsExpressionFunctionfunction (const QString &name) const
 Retrieves a function from the scope. More...
 
QStringList functionNames () const
 Retrieves a list of names of functions contained in the scope. More...
 
QgsGeometry geometry () const
 Sets the geometry associated with the scope. More...
 
bool hasFeature () const
 Returns true if the scope has a feature associated with it. More...
 
bool hasFunction (const QString &name) const
 Tests whether a function with the specified name exists in the scope. More...
 
bool hasGeometry () const
 Returns true if the scope has a geometry associated with it. More...
 
bool hasVariable (const QString &name) const
 Tests whether a variable with the specified name exists in the scope. More...
 
QStringList hiddenVariables () const
 Returns the list of variables hidden within the scope. More...
 
bool isReadOnly (const QString &name) const
 Tests whether the specified variable is read only and should not be editable by users. More...
 
bool isStatic (const QString &name) const
 Tests whether the variable with the specified name is static and can be cached. More...
 
QList< QgsMapLayerStore * > layerStores () const
 Returns the list of layer stores associated with the scope. More...
 
QString name () const
 Returns the friendly display name of the context scope. More...
 
QgsExpressionContextScopeoperator= (const QgsExpressionContextScope &other)
 
void readXml (const QDomElement &element, const QgsReadWriteContext &context)
 Reads scope variables from an XML element. More...
 
void removeFeature ()
 Removes any feature associated with the scope. More...
 
void removeGeometry ()
 Removes any geometry associated with the scope. More...
 
void removeHiddenVariable (const QString &hiddenVariable)
 Removes the passed variable from a list of hidden variables. More...
 
bool removeVariable (const QString &name)
 Removes a variable from the context scope, if found. More...
 
void setFeature (const QgsFeature &feature)
 Convenience function for setting a feature for the scope. More...
 
void setFields (const QgsFields &fields)
 Convenience function for setting a fields for the scope. More...
 
void setGeometry (const QgsGeometry &geometry)
 Convenience function for setting a geometry for the scope. More...
 
void setHiddenVariables (const QStringList &hiddenVariables)
 Sets the list of variables intended to be hidden in the expression builder dialog and widget. More...
 
void setVariable (const QString &name, const QVariant &value, bool isStatic=false)
 Convenience method for setting a variable in the context scope by name name and value. More...
 
QVariant variable (const QString &name) const
 Retrieves a variable's value from the scope. More...
 
int variableCount () const
 Returns the count of variables contained within the scope. More...
 
QStringList variableNames () const
 Returns a list of variable names contained within the scope. More...
 
bool writeXml (QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context) const
 Writes scope variables to an XML element. More...
 

Detailed Description

Single scope for storing variables and functions for use within a QgsExpressionContext.

Examples include a project's scope, which could contain information about the current project such as the project file's location. QgsExpressionContextScope can encapsulate both variables (static values) and functions(which are calculated only when an expression is evaluated).

See QgsExpressionContextUtils for helper methods for working with QgsExpressionContextScope objects.

Definition at line 113 of file qgsexpressioncontext.h.

Constructor & Destructor Documentation

◆ QgsExpressionContextScope() [1/2]

QgsExpressionContextScope::QgsExpressionContextScope ( const QString &  name = QString())

Constructor for QgsExpressionContextScope.

Parameters
namefriendly display name for the context scope

Definition at line 38 of file qgsexpressioncontext.cpp.

◆ QgsExpressionContextScope() [2/2]

QgsExpressionContextScope::QgsExpressionContextScope ( const QgsExpressionContextScope other)

Copy constructor.

Definition at line 44 of file qgsexpressioncontext.cpp.

◆ ~QgsExpressionContextScope()

QgsExpressionContextScope::~QgsExpressionContextScope ( )

Definition at line 83 of file qgsexpressioncontext.cpp.

Member Function Documentation

◆ addFunction()

void QgsExpressionContextScope::addFunction ( const QString &  name,
QgsScopedExpressionFunction function 
)

Adds a function to the scope.

Parameters
namefunction name
functionfunction to insert. Ownership is transferred to the scope.
See also
addVariable()

Definition at line 245 of file qgsexpressioncontext.cpp.

◆ addHiddenVariable()

void QgsExpressionContextScope::addHiddenVariable ( const QString &  hiddenVariable)

Adds the passed variable to a list of hidden variables that won't be visible in the expression builder dialog and widget.

See also
hiddenVariables()
setHiddenVariables()
removeHiddenVariable()
Since
QGIS 3.28

Definition at line 146 of file qgsexpressioncontext.cpp.

◆ addLayerStore()

void QgsExpressionContextScope::addLayerStore ( QgsMapLayerStore store)

Adds a layer store to the scope.

Ownership of the store is not transferred to the scope, it is the caller's responsibility to ensure that the store remains alive for the duration of the expression context.

See also
layerStores()
Since
QGIS 3.30

Definition at line 158 of file qgsexpressioncontext.cpp.

◆ addVariable()

void QgsExpressionContextScope::addVariable ( const QgsExpressionContextScope::StaticVariable variable)

Adds a variable into the context scope.

If a variable with the same name is already set then its value is overwritten, otherwise a new variable is added to the scope.

Parameters
variabledefinition of variable to insert
See also
setVariable()
addFunction()

Definition at line 102 of file qgsexpressioncontext.cpp.

◆ description()

QString QgsExpressionContextScope::description ( const QString &  name) const

Returns the translated description for the variable with the specified name (if set).

Definition at line 225 of file qgsexpressioncontext.cpp.

◆ feature()

QgsFeature QgsExpressionContextScope::feature ( ) const
inline

Sets the feature associated with the scope.

See also
setFeature()
hasFeature()

Definition at line 306 of file qgsexpressioncontext.h.

◆ filteredVariableNames()

QStringList QgsExpressionContextScope::filteredVariableNames ( ) const

Returns a filtered and sorted list of variable names contained within the scope.

Hidden variable names will be excluded, and the list will be sorted so that read only variables are listed first.

See also
variableNames()

Definition at line 197 of file qgsexpressioncontext.cpp.

◆ function()

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

Retrieves a function from the scope.

Parameters
namefunction name
Returns
function, or nullptr if matching function could not be found
See also
hasFunction()
functionNames()
variable()

Definition at line 235 of file qgsexpressioncontext.cpp.

◆ functionNames()

QStringList QgsExpressionContextScope::functionNames ( ) const

Retrieves a list of names of functions contained in the scope.

See also
function()
variableNames()

Definition at line 240 of file qgsexpressioncontext.cpp.

◆ geometry()

QgsGeometry QgsExpressionContextScope::geometry ( ) const
inline

Sets the geometry associated with the scope.

See also
setGeometry()
hasGeometry()
Since
QGIS 3.24

Definition at line 337 of file qgsexpressioncontext.h.

◆ hasFeature()

bool QgsExpressionContextScope::hasFeature ( ) const
inline

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

See also
feature()

Definition at line 299 of file qgsexpressioncontext.h.

◆ hasFunction()

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

Tests whether a function with the specified name exists in the scope.

Parameters
namefunction name
Returns
true if matching function was found in the scope
See also
function()
hasFunction()

Definition at line 230 of file qgsexpressioncontext.cpp.

◆ hasGeometry()

bool QgsExpressionContextScope::hasGeometry ( ) const
inline

Returns true if the scope has a geometry associated with it.

See also
geometry()
Since
QGIS 3.24

Definition at line 329 of file qgsexpressioncontext.h.

◆ hasVariable()

bool QgsExpressionContextScope::hasVariable ( const QString &  name) const

Tests whether a variable with the specified name exists in the scope.

Parameters
namevariable name
Returns
true if matching variable was found in the scope
See also
variable()
hasFunction()

Definition at line 112 of file qgsexpressioncontext.cpp.

◆ hiddenVariables()

QStringList QgsExpressionContextScope::hiddenVariables ( ) const

Returns the list of variables hidden within the scope.

See also
setHiddenVariables()
addHiddenVariable()
removeHiddenVariable()
Since
QGIS 3.28

Definition at line 136 of file qgsexpressioncontext.cpp.

◆ isReadOnly()

bool QgsExpressionContextScope::isReadOnly ( const QString &  name) const

Tests whether the specified variable is read only and should not be editable by users.

Parameters
namevariable name
Returns
true if variable is read only

Definition at line 215 of file qgsexpressioncontext.cpp.

◆ isStatic()

bool QgsExpressionContextScope::isStatic ( const QString &  name) const

Tests whether the variable with the specified name is static and can be cached.

Definition at line 220 of file qgsexpressioncontext.cpp.

◆ layerStores()

QList< QgsMapLayerStore * > QgsExpressionContextScope::layerStores ( ) const

Returns the list of layer stores associated with the scope.

See also
addLayerStore()
Since
QGIS 3.30

Definition at line 163 of file qgsexpressioncontext.cpp.

◆ name()

QString QgsExpressionContextScope::name ( ) const
inline

Returns the friendly display name of the context scope.

Definition at line 173 of file qgsexpressioncontext.h.

◆ operator=()

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

Definition at line 61 of file qgsexpressioncontext.cpp.

◆ readXml()

void QgsExpressionContextScope::readXml ( const QDomElement &  element,
const QgsReadWriteContext context 
)

Reads scope variables from an XML element.

See also
writeXml()
Since
QGIS 3.6

Definition at line 256 of file qgsexpressioncontext.cpp.

◆ removeFeature()

void QgsExpressionContextScope::removeFeature ( )
inline

Removes any feature associated with the scope.

See also
setFeature()
hasFeature()

Definition at line 322 of file qgsexpressioncontext.h.

◆ removeGeometry()

void QgsExpressionContextScope::removeGeometry ( )
inline

Removes any geometry associated with the scope.

See also
setGeometry()
hasGeometry()
Since
QGIS 3.24

Definition at line 355 of file qgsexpressioncontext.h.

◆ removeHiddenVariable()

void QgsExpressionContextScope::removeHiddenVariable ( const QString &  hiddenVariable)

Removes the passed variable from a list of hidden variables.

See also
hiddenVariables()
setHiddenVariables()
addHiddenVariable()
Since
QGIS 3.28

Definition at line 152 of file qgsexpressioncontext.cpp.

◆ removeVariable()

bool QgsExpressionContextScope::removeVariable ( const QString &  name)

Removes a variable from the context scope, if found.

Parameters
namename of variable to remove
Returns
true if variable was removed from the scope, false if matching variable was not found within the scope

Definition at line 107 of file qgsexpressioncontext.cpp.

◆ setFeature()

void QgsExpressionContextScope::setFeature ( const QgsFeature feature)
inline

Convenience function for setting a feature for the scope.

Any existing feature set by the scope will be overwritten.

Parameters
featurefeature for scope
See also
removeFeature()
feature()

Definition at line 315 of file qgsexpressioncontext.h.

◆ setFields()

void QgsExpressionContextScope::setFields ( const QgsFields fields)

Convenience function for setting a fields for the scope.

Any existing fields set by the scope will be overwritten.

Parameters
fieldsfields for scope

Definition at line 251 of file qgsexpressioncontext.cpp.

◆ setGeometry()

void QgsExpressionContextScope::setGeometry ( const QgsGeometry geometry)
inline

Convenience function for setting a geometry for the scope.

Any existing geometry set by the scope will be overwritten.

See also
removeGeometry()
geometry()
Since
QGIS 3.24

Definition at line 347 of file qgsexpressioncontext.h.

◆ setHiddenVariables()

void QgsExpressionContextScope::setHiddenVariables ( const QStringList &  hiddenVariables)

Sets the list of variables intended to be hidden in the expression builder dialog and widget.

See also
hiddenVariables()
addHiddenVariable()
removeHiddenVariable()
Since
QGIS 3.28

Definition at line 141 of file qgsexpressioncontext.cpp.

◆ setVariable()

void QgsExpressionContextScope::setVariable ( const QString &  name,
const QVariant &  value,
bool  isStatic = false 
)

Convenience method for setting a variable in the context scope by name name and value.

If a variable with the same name is already set then its value is overwritten, otherwise a new variable is added to the scope. If the isStatic parameter is set to true, this variable can be cached during the execution of QgsExpression::prepare().

See also
addVariable()

Definition at line 88 of file qgsexpressioncontext.cpp.

◆ variable()

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

Retrieves a variable's value from the scope.

Parameters
namevariable name
Returns
variable value, or invalid QVariant if matching variable could not be found
See also
hasVariable()
function()

Definition at line 117 of file qgsexpressioncontext.cpp.

◆ variableCount()

int QgsExpressionContextScope::variableCount ( ) const
inline

Returns the count of variables contained within the scope.

Definition at line 259 of file qgsexpressioncontext.h.

◆ variableNames()

QStringList QgsExpressionContextScope::variableNames ( ) const

Returns a list of variable names contained within the scope.

See also
functionNames()
filteredVariableNames()

Definition at line 122 of file qgsexpressioncontext.cpp.

◆ writeXml()

bool QgsExpressionContextScope::writeXml ( QDomElement &  element,
QDomDocument &  document,
const QgsReadWriteContext context 
) const

Writes scope variables to an XML element.

See also
readXml()
Since
QGIS 3.6

Definition at line 274 of file qgsexpressioncontext.cpp.


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