mirror of
https://github.com/qgis/QGIS.git
synced 2025-02-25 00:58:06 -05:00
573 lines
22 KiB
Plaintext
573 lines
22 KiB
Plaintext
/** \ingroup core
|
|
* \class QgsScopedExpressionFunction
|
|
* \brief Expression function for use within a QgsExpressionContextScope. This differs from a
|
|
* standard QgsExpression::Function in that it requires an implemented
|
|
* clone() method.
|
|
* \note added in QGIS 2.12
|
|
*/
|
|
|
|
class QgsScopedExpressionFunction : QgsExpression::Function
|
|
{
|
|
%TypeHeaderCode
|
|
#include <qgsexpressioncontext.h>
|
|
%End
|
|
public:
|
|
QgsScopedExpressionFunction( const QString& fnname,
|
|
int params,
|
|
const QString& group,
|
|
const QString& helpText = QString(),
|
|
bool usesGeometry = false,
|
|
const QStringList& referencedColumns = QStringList(),
|
|
bool lazyEval = false,
|
|
bool handlesNull = false,
|
|
bool isContextual = true );
|
|
|
|
virtual ~QgsScopedExpressionFunction();
|
|
|
|
virtual QVariant func( const QVariantList& values, const QgsExpressionContext* context, QgsExpression* parent ) = 0;
|
|
|
|
/** Returns a clone of the function.
|
|
*/
|
|
virtual QgsScopedExpressionFunction* clone() const = 0 /Factory/;
|
|
|
|
};
|
|
|
|
|
|
/** \ingroup core
|
|
* \class QgsExpressionContextScope
|
|
* \brief 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).
|
|
* \note added in QGIS 2.12
|
|
*/
|
|
|
|
class QgsExpressionContextScope
|
|
{
|
|
%TypeHeaderCode
|
|
#include <qgsexpressioncontext.h>
|
|
%End
|
|
public:
|
|
|
|
/** Single variable definition for use within a QgsExpressionContextScope.
|
|
*/
|
|
struct StaticVariable
|
|
{
|
|
/** Constructor for StaticVariable.
|
|
* @param name variable name (should be unique within the QgsExpressionContextScope)
|
|
* @param value intial variable value
|
|
* @param readOnly true if variable should not be editable by users
|
|
*/
|
|
StaticVariable( const QString& name = QString(), const QVariant& value = QVariant(), bool readOnly = false );
|
|
|
|
/** Variable name */
|
|
QString name;
|
|
|
|
/** Variable value */
|
|
QVariant value;
|
|
|
|
/** True if variable should not be editable by users */
|
|
bool readOnly;
|
|
};
|
|
|
|
/** Constructor for QgsExpressionContextScope
|
|
* @param name friendly display name for the context scope
|
|
*/
|
|
QgsExpressionContextScope( const QString& name = QString() );
|
|
|
|
/** Copy constructor
|
|
*/
|
|
QgsExpressionContextScope( const QgsExpressionContextScope& other );
|
|
|
|
~QgsExpressionContextScope();
|
|
|
|
/** Returns the friendly display name of the context scope.
|
|
*/
|
|
QString name() const;
|
|
|
|
/** Convenience method for setting a variable in the context scope by 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.
|
|
* @param name variable name
|
|
* @param value variable value
|
|
* @see addVariable()
|
|
*/
|
|
void setVariable( const QString& name, const QVariant& value );
|
|
|
|
/** 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.
|
|
* @param variable definition of variable to insert
|
|
* @see setVariable()
|
|
* @see addFunction()
|
|
*/
|
|
void addVariable( const QgsExpressionContextScope::StaticVariable& variable );
|
|
|
|
/** Removes a variable from the context scope, if found.
|
|
* @param name name of variable to remove
|
|
* @returns true if variable was removed from the scope, false if matching variable was not
|
|
* found within the scope
|
|
*/
|
|
bool removeVariable( const QString& name );
|
|
|
|
/** Tests whether a variable with the specified name exists in the scope.
|
|
* @param name variable name
|
|
* @returns true if matching variable was found in the scope
|
|
* @see variable()
|
|
* @see hasFunction()
|
|
*/
|
|
bool hasVariable( const QString& name ) const;
|
|
|
|
/** Retrieves a variable's value from the scope.
|
|
* @param name variable name
|
|
* @returns variable value, or invalid QVariant if matching variable could not be found
|
|
* @see hasVariable()
|
|
* @see function()
|
|
*/
|
|
QVariant variable( const QString& name ) const;
|
|
|
|
/** Returns a list of variable names contained within the scope.
|
|
* @see functionNames()
|
|
* @see filteredVariableNames()
|
|
*/
|
|
QStringList variableNames() const;
|
|
|
|
/** Returns a fitlered 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 variableNames()
|
|
*/
|
|
QStringList filteredVariableNames() const;
|
|
|
|
/** Tests whether the specified variable is read only and should not be editable
|
|
* by users.
|
|
* @param name variable name
|
|
* @returns true if variable is read only
|
|
*/
|
|
bool isReadOnly( const QString& name ) const;
|
|
|
|
/** Returns the count of variables contained within the scope.
|
|
*/
|
|
int variableCount() const;
|
|
|
|
/** Tests whether a function with the specified name exists in the scope.
|
|
* @param name function name
|
|
* @returns true if matching function was found in the scope
|
|
* @see function()
|
|
* @see hasFunction()
|
|
*/
|
|
bool hasFunction( const QString &name ) const;
|
|
|
|
/** Retrieves a function from the scope.
|
|
* @param name function name
|
|
* @returns function, or null if matching function could not be found
|
|
* @see hasFunction()
|
|
* @see functionNames()
|
|
* @see variable()
|
|
*/
|
|
QgsExpression::Function* function( const QString &name ) const;
|
|
|
|
/** Retrieves a list of names of functions contained in the scope.
|
|
* @see function()
|
|
* @see variableNames()
|
|
*/
|
|
QStringList functionNames() const;
|
|
|
|
/** Adds a function to the scope.
|
|
* @param name function name
|
|
* @param function function to insert. Ownership is transferred to the scope.
|
|
* @see addVariable()
|
|
*/
|
|
void addFunction( const QString& name, QgsScopedExpressionFunction* function /Transfer/ );
|
|
|
|
/** Convenience function for setting a feature for the scope. Any existing
|
|
* feature set by the scope will be overwritten.
|
|
* @param feature feature for scope
|
|
*/
|
|
void setFeature( const QgsFeature& feature );
|
|
|
|
/** Convenience function for setting a fields for the scope. Any existing
|
|
* fields set by the scope will be overwritten.
|
|
* @param fields fields for scope
|
|
*/
|
|
void setFields( const QgsFields& fields );
|
|
};
|
|
|
|
/** \ingroup core
|
|
* \class QgsExpressionContext
|
|
* \brief 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.
|
|
* \note added in QGIS 2.12
|
|
*/
|
|
|
|
class QgsExpressionContext
|
|
{
|
|
%TypeHeaderCode
|
|
#include <qgsexpressioncontext.h>
|
|
%End
|
|
public:
|
|
|
|
QgsExpressionContext();
|
|
|
|
/** Copy constructor
|
|
*/
|
|
QgsExpressionContext( const QgsExpressionContext& other );
|
|
|
|
~QgsExpressionContext();
|
|
|
|
/** Check whether a variable is specified by any scope within the context.
|
|
* @param name variable name
|
|
* @returns true if variable is set
|
|
* @see variable()
|
|
* @see variableNames()
|
|
*/
|
|
bool hasVariable( 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.
|
|
* @param name variable name
|
|
* @returns variable value if matching variable exists in the context, otherwise an invalid QVariant
|
|
* @see hasVariable()
|
|
* @see variableNames()
|
|
*/
|
|
QVariant variable( 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.
|
|
* @param name variable name
|
|
* @see setHighlightedVariables()
|
|
*/
|
|
bool isHighlightedVariable( const QString& name ) const;
|
|
|
|
/** 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.
|
|
* @param variableNames variable names to highlight
|
|
* @see isHighlightedVariable()
|
|
*/
|
|
void setHighlightedVariables( const QStringList& variableNames );
|
|
|
|
/** 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.
|
|
* @param name variable name
|
|
* @returns matching scope containing variable, or null if none found
|
|
*/
|
|
QgsExpressionContextScope* 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.
|
|
* @param name variable name
|
|
* @returns matching scope containing variable, or null if none found
|
|
* @note not available in python bindings
|
|
*/
|
|
//const QgsExpressionContextScope* activeScopeForVariable( const QString& name ) const;
|
|
|
|
/** Returns the scope at the specified index within the context.
|
|
* @param index index of scope
|
|
* @returns matching scope, or null if none found
|
|
* @see lastScope()
|
|
*/
|
|
QgsExpressionContextScope* scope( int index );
|
|
|
|
/** Returns the last scope added to the context.
|
|
* @see scope()
|
|
*/
|
|
QgsExpressionContextScope* lastScope();
|
|
|
|
/** Returns a list of scopes contained within the stack.
|
|
* @returns list of pointers to scopes
|
|
*/
|
|
QList< QgsExpressionContextScope* > scopes();
|
|
|
|
/** Returns the index of the specified scope if it exists within the context.
|
|
* @param scope scope to find
|
|
* @returns index of scope, or -1 if scope was not found within the context.
|
|
*/
|
|
int indexOfScope( QgsExpressionContextScope* scope ) const;
|
|
|
|
/** Returns a list of variables names set by all scopes in the context.
|
|
* @returns list of unique variable names
|
|
* @see filteredVariableNames
|
|
* @see functionNames
|
|
* @see hasVariable
|
|
* @see variable
|
|
*/
|
|
QStringList variableNames() 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 variableNames
|
|
*/
|
|
QStringList filteredVariableNames() const;
|
|
|
|
/** Returns whether a variable is read only, and should not be modifiable by users.
|
|
* @param 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.
|
|
*/
|
|
bool isReadOnly( const QString& name ) const;
|
|
|
|
/** Checks whether a specified function is contained in the context.
|
|
* @param name function name
|
|
* @returns true if context provides a matching function
|
|
* @see function
|
|
*/
|
|
bool hasFunction( const QString& name ) const;
|
|
|
|
/** Retrieves a list of function names contained in the context.
|
|
* @see function()
|
|
* @see variableNames()
|
|
*/
|
|
QStringList functionNames() 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.
|
|
* @param name function name
|
|
* @returns function if contained by the context, otherwise null.
|
|
* @see hasFunction
|
|
*/
|
|
QgsExpression::Function* function( const QString& name ) const;
|
|
|
|
/** Returns the number of scopes contained in the context.
|
|
*/
|
|
int scopeCount() const;
|
|
|
|
/** 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.
|
|
* @param scope expression context to append to context
|
|
*/
|
|
void appendScope( QgsExpressionContextScope* scope /Transfer/ );
|
|
|
|
/**
|
|
* Removes the last scope from the expression context and return it.
|
|
*/
|
|
QgsExpressionContextScope* popScope();
|
|
|
|
/** 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.
|
|
*/
|
|
QgsExpressionContext& operator<< ( QgsExpressionContextScope* scope /Transfer/ );
|
|
|
|
/** 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.
|
|
* @param feature feature for context
|
|
* @see feature()
|
|
*/
|
|
void setFeature( const QgsFeature& feature );
|
|
|
|
/** Convenience function for retrieving the feature for the context, if set.
|
|
* @see setFeature
|
|
*/
|
|
QgsFeature feature() const;
|
|
|
|
/** 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.
|
|
* @param fields fields for context
|
|
* @see fields()
|
|
*/
|
|
void setFields( const QgsFields& fields );
|
|
|
|
/** Convenience function for retrieving the fields for the context, if set.
|
|
* @see setFields
|
|
*/
|
|
QgsFields fields() const;
|
|
|
|
/** Sets the original value variable value for the context.
|
|
* @param 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
|
|
*/
|
|
void setOriginalValueVariable( const QVariant& value );
|
|
|
|
//! Inbuilt variable name for fields storage
|
|
static const QString EXPR_FIELDS;
|
|
//! Inbuilt variable name for feature storage
|
|
static const QString EXPR_FEATURE;
|
|
//! Inbuilt variable name for value original value variable
|
|
static const QString EXPR_ORIGINAL_VALUE;
|
|
//! Inbuilt variable name for symbol color variable
|
|
static const QString EXPR_SYMBOL_COLOR;
|
|
//! Inbuilt variable name for symbol angle variable
|
|
static const QString EXPR_SYMBOL_ANGLE;
|
|
//! Inbuilt variable name for geometry part count variable
|
|
static const QString EXPR_GEOMETRY_PART_COUNT;
|
|
//! Inbuilt variable name for geometry part number variable
|
|
static const QString EXPR_GEOMETRY_PART_NUM;
|
|
};
|
|
|
|
/** \ingroup core
|
|
* \class QgsExpressionContextUtils
|
|
* \brief Contains utilities for working with QgsExpressionContext objects, including methods
|
|
* for creating scopes for specific uses (eg project scopes, layer scopes).
|
|
* \note added in QGIS 2.12
|
|
*/
|
|
|
|
class QgsExpressionContextUtils
|
|
{
|
|
%TypeHeaderCode
|
|
#include <qgsexpressioncontext.h>
|
|
%End
|
|
public:
|
|
|
|
/** Creates a new scope which contains variables and functions relating to the global QGIS context.
|
|
* For instance, QGIS version numbers and variables specified through QGIS options.
|
|
* @see setGlobalVariable()
|
|
*/
|
|
static QgsExpressionContextScope* globalScope() /Factory/;
|
|
|
|
/** Sets a global context variable. This variable will be contained within scopes retrieved via
|
|
* globalScope().
|
|
* @param name variable name
|
|
* @param value variable value
|
|
* @see setGlobalVariable()
|
|
* @see globalScope()
|
|
*/
|
|
static void setGlobalVariable( const QString& name, const QVariant& value );
|
|
|
|
/** Sets all global context variables. Existing global variables will be removed and replaced
|
|
* with the variables specified.
|
|
* @param variables new set of global variables
|
|
* @see setGlobalVariable()
|
|
* @see globalScope()
|
|
*/
|
|
static void setGlobalVariables( const QgsStringMap& variables );
|
|
|
|
/** Creates a new scope which contains variables and functions relating to the current QGIS project.
|
|
* For instance, project path and title, and variables specified through the project properties.
|
|
* @see setProjectVariable()
|
|
*/
|
|
static QgsExpressionContextScope* projectScope() /Factory/;
|
|
|
|
/** Sets a project context variable. This variable will be contained within scopes retrieved via
|
|
* projectScope().
|
|
* @param name variable name
|
|
* @param value variable value
|
|
* @see setProjectVariables()
|
|
* @see projectScope()
|
|
*/
|
|
static void setProjectVariable( const QString& name, const QVariant& value );
|
|
|
|
/** Sets all project context variables. Existing project variables will be removed and replaced
|
|
* with the variables specified.
|
|
* @param variables new set of project variables
|
|
* @see setProjectVariable()
|
|
* @see projectScope()
|
|
*/
|
|
static void setProjectVariables( const QgsStringMap& variables );
|
|
|
|
/** Creates a new scope which contains variables and functions relating to a QgsMapLayer.
|
|
* For instance, layer name, id and fields.
|
|
*/
|
|
static QgsExpressionContextScope* layerScope( const QgsMapLayer *layer ) /Factory/;
|
|
|
|
/** Sets a layer context variable. This variable will be contained within scopes retrieved via
|
|
* layerScope().
|
|
* @param layer map layer
|
|
* @param name variable name
|
|
* @param value variable value
|
|
* @see setLayerVariables()
|
|
* @see layerScope()
|
|
*/
|
|
static void setLayerVariable( QgsMapLayer* layer, const QString& name, const QVariant& value );
|
|
|
|
/** Sets all layer context variables. Existing layer variables will be removed and replaced
|
|
* with the variables specified.
|
|
* @param layer map layer
|
|
* @param variables new set of layer variables
|
|
* @see setLayerVariable()
|
|
* @see layerScope()
|
|
*/
|
|
static void setLayerVariables( QgsMapLayer* layer, const QgsStringMap& variables );
|
|
|
|
/** Creates a new scope which contains variables and functions relating to a QgsMapSettings object.
|
|
* For instance, map scale and rotation.
|
|
*/
|
|
static QgsExpressionContextScope* mapSettingsScope( const QgsMapSettings &mapSettings ) /Factory/;
|
|
|
|
/**
|
|
* Updates a symbol scope related to a QgsSymbolV2 to an expression context.
|
|
* @param symbol symbol to extract properties from
|
|
* @param symbolScope pointer to an existing scope to update
|
|
* @note added in QGIS 2.14
|
|
*/
|
|
static QgsExpressionContextScope* updateSymbolScope( const QgsSymbolV2* symbol, QgsExpressionContextScope* symbolScope = nullptr );
|
|
|
|
/** Creates a new scope which contains variables and functions relating to a QgsComposition.
|
|
* For instance, number of pages and page sizes.
|
|
* @param composition source composition
|
|
*/
|
|
static QgsExpressionContextScope* compositionScope( const QgsComposition *composition ) /Factory/;
|
|
|
|
/** Sets a composition context variable. This variable will be contained within scopes retrieved via
|
|
* compositionScope().
|
|
* @param composition target composition
|
|
* @param name variable name
|
|
* @param value variable value
|
|
* @see setCompositionVariables()
|
|
* @see compositionScope()
|
|
*/
|
|
static void setCompositionVariable( QgsComposition* composition, const QString& name, const QVariant& value );
|
|
|
|
/** Sets all composition context variables. Existing composition variables will be removed and replaced
|
|
* with the variables specified.
|
|
* @param composition target composition
|
|
* @param variables new set of layer variables
|
|
* @see setCompositionVariable()
|
|
* @see compositionScope()
|
|
*/
|
|
static void setCompositionVariables( QgsComposition* composition, const QgsStringMap& variables );
|
|
|
|
/** Creates a new scope which contains variables and functions relating to a QgsAtlasComposition.
|
|
* For instance, current page name and number.
|
|
* @param atlas source atlas. If null, a set of default atlas variables will be added to the scope.
|
|
*/
|
|
static QgsExpressionContextScope* atlasScope( const QgsAtlasComposition* atlas ) /Factory/;
|
|
|
|
/** Creates a new scope which contains variables and functions relating to a QgsComposerItem.
|
|
* For instance, item size and position.
|
|
* @param composerItem source composer item
|
|
*/
|
|
static QgsExpressionContextScope* composerItemScope( const QgsComposerItem *composerItem ) /Factory/;
|
|
|
|
/** Sets a composer item context variable. This variable will be contained within scopes retrieved via
|
|
* composerItemScope().
|
|
* @param composerItem target composer item
|
|
* @param name variable name
|
|
* @param value variable value
|
|
* @see setComposerItemVariables()
|
|
* @see composerItemScope()
|
|
*/
|
|
static void setComposerItemVariable( QgsComposerItem* composerItem, const QString& name, const QVariant& value );
|
|
|
|
/** Sets all composition context variables. Existing compositoin variables will be removed and replaced
|
|
* with the variables specified.
|
|
* @param composerItem target composer item
|
|
* @param variables new set of layer variables
|
|
* @see setComposerItemVariable()
|
|
* @see composerItemScope()
|
|
*/
|
|
static void setComposerItemVariables( QgsComposerItem* composerItem, const QgsStringMap& variables );
|
|
|
|
/** Helper function for creating an expression context which contains just a feature and fields
|
|
* collection. Generally this method should not be used as the created context does not include
|
|
* standard scopes such as the global and project scopes.
|
|
*/
|
|
static QgsExpressionContext createFeatureBasedContext( const QgsFeature& feature, const QgsFields& fields );
|
|
|
|
/** Registers all known core functions provided by QgsExpressionContextScope objects.
|
|
*/
|
|
static void registerContextFunctions();
|
|
|
|
};
|
|
|