QGIS/python/core/qgsexpressioncontext.sip

/** \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();

};