/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgsexpressioncontext.h                                      *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/





class QgsScopedExpressionFunction : QgsExpressionFunction
{
%Docstring(signature="appended")
Expression function for use within a
:py:class:`QgsExpressionContextScope`. This differs from a standard
:py:class:`QgsExpression`.Function in that it requires an implemented
:py:func:`~clone` method.
%End

%TypeHeaderCode
#include "qgsexpressioncontext.h"
%End
  public:

    QgsScopedExpressionFunction( const QString &fnname,
                                 int params,
                                 const QString &group,
                                 const QString &helpText = QString(),
                                 bool usesGeometry = false,
                                 const QSet<QString> &referencedColumns = QSet<QString>(),
                                 bool lazyEval = false,
                                 bool handlesNull = false,
                                 bool isContextual = true );
%Docstring
Create a new QgsScopedExpressionFunction
%End

    QgsScopedExpressionFunction( const QString &fnname,
                                 const QgsExpressionFunction::ParameterList &params,
                                 const QString &group,
                                 const QString &helpText = QString(),
                                 bool usesGeometry = false,
                                 const QSet<QString> &referencedColumns = QSet<QString>(),
                                 bool lazyEval = false,
                                 bool handlesNull = false,
                                 bool isContextual = true );
%Docstring
Create a new QgsScopedExpressionFunction using named parameters.
%End

    virtual QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) = 0;


    virtual QgsScopedExpressionFunction *clone() const = 0 /Factory/;
%Docstring
Returns a clone of the function.
%End

    virtual bool usesGeometry( const QgsExpressionNodeFunction *node ) const;


    virtual QSet<QString> referencedColumns( const QgsExpressionNodeFunction *node ) const;


    virtual bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const;


};



class QgsExpressionContextScope
{
%Docstring(signature="appended")
Single scope for storing variables and functions for use within a
:py:class:`QgsExpressionContext`.

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

See :py:class:`QgsExpressionContextUtils` for helper methods for working
with :py:class:`QgsExpressionContextScope` objects.
%End

%TypeHeaderCode
#include "qgsexpressioncontext.h"
%End
  public:

    struct StaticVariable
    {

      StaticVariable( const QString &name = QString(), const QVariant &value = QVariant(), bool readOnly = false, bool isStatic = false, const QString &description = QString() );
%Docstring
Constructor for StaticVariable.

:param name: variable name (should be unique within the
             QgsExpressionContextScope)
:param value: initial variable value
:param readOnly: ``True`` if variable should not be editable by users
:param isStatic: ``True`` if the variable will not change during the
                 lifteime of an iterator.
:param description: optional translated description of variable, for use
                    in expression builder widgets
%End

      QString name;

      QVariant value;

      bool readOnly;

      bool isStatic;

      QString description;
    };

    QgsExpressionContextScope( const QString &name = QString() );
%Docstring
Constructor for QgsExpressionContextScope

:param name: friendly display name for the context scope
%End

    QgsExpressionContextScope( const QgsExpressionContextScope &other );


    ~QgsExpressionContextScope();

    QString name() const;
%Docstring
Returns the friendly display name of the context scope.
%End

    void setVariable( const QString &name, const QVariant &value, bool isStatic = false );
%Docstring
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
:py:func:`QgsExpression.prepare()`.

.. seealso:: :py:func:`addVariable`
%End

    void addVariable( const QgsExpressionContextScope::StaticVariable &variable );
%Docstring
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

.. seealso:: :py:func:`setVariable`

.. seealso:: :py:func:`addFunction`
%End

    bool removeVariable( const QString &name );
%Docstring
Removes a variable from the context scope, if found.

:param name: name of variable to remove

:return: ``True`` if variable was removed from the scope, ``False`` if
         matching variable was not found within the scope
%End

    bool hasVariable( const QString &name ) const;
%Docstring
Tests whether a variable with the specified name exists in the scope.

:param name: variable name

:return: ``True`` if matching variable was found in the scope

.. seealso:: :py:func:`variable`

.. seealso:: :py:func:`hasFunction`
%End

    QVariant variable( const QString &name ) const;
%Docstring
Retrieves a variable's value from the scope.

:param name: variable name

:return: variable value, or invalid QVariant if matching variable could
         not be found

.. seealso:: :py:func:`hasVariable`

.. seealso:: :py:func:`function`
%End

    QStringList variableNames() const;
%Docstring
Returns a list of variable names contained within the scope.

.. seealso:: :py:func:`functionNames`

.. seealso:: :py:func:`filteredVariableNames`
%End

    QStringList filteredVariableNames() const;
%Docstring
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.

.. seealso:: :py:func:`variableNames`
%End

    bool isReadOnly( const QString &name ) const;
%Docstring
Tests whether the specified variable is read only and should not be
editable by users.

:param name: variable name

:return: ``True`` if variable is read only
%End

    bool isStatic( const QString &name ) const;
%Docstring
Tests whether the variable with the specified ``name`` is static and can
be cached.
%End

    QString description( const QString &name ) const;
%Docstring
Returns the translated description for the variable with the specified
``name`` (if set).
%End

    int variableCount() const;
%Docstring
Returns the count of variables contained within the scope.
%End

    bool hasFunction( const QString &name ) const;
%Docstring
Tests whether a function with the specified name exists in the scope.

:param name: function name

:return: ``True`` if matching function was found in the scope

.. seealso:: :py:func:`function`

.. seealso:: :py:func:`hasFunction`
%End

    QgsExpressionFunction *function( const QString &name ) const;
%Docstring
Retrieves a function from the scope.

:param name: function name

:return: function, or ``None`` if matching function could not be found

.. seealso:: :py:func:`hasFunction`

.. seealso:: :py:func:`functionNames`

.. seealso:: :py:func:`variable`
%End

    QStringList functionNames() const;
%Docstring
Retrieves a list of names of functions contained in the scope.

.. seealso:: :py:func:`function`

.. seealso:: :py:func:`variableNames`
%End

    void addFunction( const QString &name, QgsScopedExpressionFunction *function /Transfer/ );
%Docstring
Adds a function to the scope.

:param name: function name
:param function: function to insert. Ownership is transferred to the
                 scope.

.. seealso:: :py:func:`addVariable`
%End

    bool hasFeature() const;
%Docstring
Returns ``True`` if the scope has a feature associated with it.

.. seealso:: :py:func:`feature`
%End

    QgsFeature feature() const;
%Docstring
Sets the feature associated with the scope.

.. seealso:: :py:func:`setFeature`

.. seealso:: :py:func:`hasFeature`
%End

    void setFeature( const QgsFeature &feature );
%Docstring
Convenience function for setting a feature for the scope. Any existing
feature set by the scope will be overwritten.

:param feature: feature for scope

.. seealso:: :py:func:`removeFeature`

.. seealso:: :py:func:`feature`
%End

    void removeFeature();
%Docstring
Removes any feature associated with the scope.

.. seealso:: :py:func:`setFeature`

.. seealso:: :py:func:`hasFeature`
%End

    bool hasGeometry() const;
%Docstring
Returns ``True`` if the scope has a geometry associated with it.

.. seealso:: :py:func:`geometry`

.. versionadded:: 3.24
%End

    QgsGeometry geometry() const;
%Docstring
Sets the geometry associated with the scope.

.. seealso:: :py:func:`setGeometry`

.. seealso:: :py:func:`hasGeometry`

.. versionadded:: 3.24
%End

    void setGeometry( const QgsGeometry &geometry );
%Docstring
Convenience function for setting a ``geometry`` for the scope. Any
existing geometry set by the scope will be overwritten.

.. seealso:: :py:func:`removeGeometry`

.. seealso:: :py:func:`geometry`

.. versionadded:: 3.24
%End

    void removeGeometry();
%Docstring
Removes any geometry associated with the scope.

.. seealso:: :py:func:`setGeometry`

.. seealso:: :py:func:`hasGeometry`

.. versionadded:: 3.24
%End

    void setFields( const QgsFields &fields );
%Docstring
Convenience function for setting a fields for the scope. Any existing
fields set by the scope will be overwritten.

:param fields: fields for scope
%End

    void readXml( const QDomElement &element, const QgsReadWriteContext &context );
%Docstring
Reads scope variables from an XML element.

.. seealso:: :py:func:`writeXml`

.. versionadded:: 3.6
%End

    bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
%Docstring
Writes scope variables to an XML ``element``.

.. seealso:: :py:func:`readXml`

.. versionadded:: 3.6
%End


    QStringList hiddenVariables() const;
%Docstring
Returns the list of variables hidden within the scope.

.. seealso:: :py:func:`setHiddenVariables`

.. seealso:: :py:func:`addHiddenVariable`

.. seealso:: :py:func:`removeHiddenVariable`

.. versionadded:: 3.28
%End

    void setHiddenVariables( const QStringList &hiddenVariables );
%Docstring
Sets the list of variables intended to be hidden in the expression
builder dialog and widget.

.. seealso:: :py:func:`hiddenVariables`

.. seealso:: :py:func:`addHiddenVariable`

.. seealso:: :py:func:`removeHiddenVariable`

.. versionadded:: 3.28
%End


    void addHiddenVariable( const QString &hiddenVariable );
%Docstring
Adds the passed variable to a list of hidden variables that won't be
visible in the expression builder dialog and widget.

.. seealso:: :py:func:`hiddenVariables`

.. seealso:: :py:func:`setHiddenVariables`

.. seealso:: :py:func:`removeHiddenVariable`

.. versionadded:: 3.28
%End

    void removeHiddenVariable( const QString &hiddenVariable );
%Docstring
Removes the passed variable from a list of hidden variables.

.. seealso:: :py:func:`hiddenVariables`

.. seealso:: :py:func:`setHiddenVariables`

.. seealso:: :py:func:`addHiddenVariable`

.. versionadded:: 3.28
%End

    void addLayerStore( QgsMapLayerStore *store );
%Docstring
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.

.. seealso:: :py:func:`layerStores`

.. versionadded:: 3.30
%End

    QList< QgsMapLayerStore * > layerStores() const;
%Docstring
Returns the list of layer stores associated with the scope.

.. seealso:: :py:func:`addLayerStore`

.. versionadded:: 3.30
%End

};

class QgsExpressionContext
{
%Docstring(signature="appended")
Expression contexts are used to encapsulate the parameters around which
a :py:class:`QgsExpression` should be evaluated.

:py:class:`QgsExpressions` can then utilize the information stored
within a context to contextualise their evaluated result. A
:py:class:`QgsExpressionContext` consists of a stack of
:py:class:`QgsExpressionContextScope` objects, where scopes added later
to the stack will override conflicting variables and functions from
scopes lower in the stack.

See :py:class:`QgsExpressionContextUtils` for helper methods for working
with :py:class:`QgsExpressionContext` objects.
%End

%TypeHeaderCode
#include "qgsexpressioncontext.h"
%End
  public:

    QgsExpressionContext();

    explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes /Transfer/ );
%Docstring
Initializes the context with given list of scopes. Ownership of the
scopes is transferred to the stack.
%End

    QgsExpressionContext( const QgsExpressionContext &other );



    ~QgsExpressionContext();

    bool hasVariable( const QString &name ) const;
%Docstring
Check whether a variable is specified by any scope within the context.

:param name: variable name

:return: ``True`` if variable is set

.. seealso:: :py:func:`variable`

.. seealso:: :py:func:`variableNames`
%End

    QVariant variable( const QString &name ) const;
%Docstring
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

:return: variable value if matching variable exists in the context,
         otherwise an invalid QVariant

.. seealso:: :py:func:`hasVariable`

.. seealso:: :py:func:`variableNames`
%End

    QVariantMap variablesToMap() const;
%Docstring
Returns a map of variable name to value representing all the expression
variables contained by the context.
%End

    bool isHighlightedVariable( const QString &name ) const;
%Docstring
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.

.. seealso:: :py:func:`setHighlightedVariables`

.. seealso:: :py:func:`isHighlightedFunction`
%End

    QStringList highlightedVariables() const;
%Docstring
Returns the current list of variables highlighted within the context.

.. seealso:: :py:func:`setHighlightedVariables`

.. versionadded:: 3.8
%End

    void setHighlightedVariables( const QStringList &variableNames );
%Docstring
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

.. seealso:: :py:func:`isHighlightedVariable`

.. seealso:: :py:func:`setHighlightedFunctions`
%End

    bool isHighlightedFunction( const QString &name ) const;
%Docstring
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.

.. seealso:: :py:func:`setHighlightedFunctions`

.. seealso:: :py:func:`isHighlightedVariable`

.. versionadded:: 3.4
%End

    void setHighlightedFunctions( const QStringList &names );
%Docstring
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.

.. seealso:: :py:func:`isHighlightedFunction`

.. seealso:: :py:func:`setHighlightedVariables`

.. versionadded:: 3.4
%End

    QgsExpressionContextScope *activeScopeForVariable( const QString &name );
%Docstring
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

:return: matching scope containing variable, or ``None`` if none found
%End


    QgsExpressionContextScope *scope( int index );
%Docstring
Returns the scope at the specified index within the context.

:param index: index of scope

:return: matching scope, or ``None`` if none found

.. seealso:: :py:func:`lastScope`
%End

    QgsExpressionContextScope *lastScope();
%Docstring
Returns the last scope added to the context.

.. seealso:: :py:func:`scope`
%End

    QList< QgsExpressionContextScope * > scopes();
%Docstring
Returns a list of scopes contained within the stack.

:return: list of pointers to scopes
%End

    int indexOfScope( QgsExpressionContextScope *scope ) const;
%Docstring
Returns the index of the specified scope if it exists within the
context.

:param scope: scope to find

:return: index of scope, or -1 if scope was not found within the
         context.
%End

    int indexOfScope( const QString &scopeName ) const;
%Docstring
Returns the index of the first scope with a matching name within the
context.

:param scopeName: name of scope to find

:return: index of scope, or -1 if scope was not found within the
         context.
%End

    QStringList variableNames() const;
%Docstring
Returns a list of variables names set by all scopes in the context.

:return: list of unique variable names

.. seealso:: :py:func:`filteredVariableNames`

.. seealso:: :py:func:`functionNames`

.. seealso:: :py:func:`hasVariable`

.. seealso:: :py:func:`variable`
%End

    QStringList filteredVariableNames() const;
%Docstring
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.

:return: filtered list of unique variable names

.. seealso:: :py:func:`variableNames`
%End

    bool isReadOnly( const QString &name ) const;
%Docstring
Returns whether a variable is read only, and should not be modifiable by
users.

:param name: variable name

:return: ``True`` if variable is read only. Read only status will be
         taken from last matching scope which contains a matching
         variable.
%End

    QString description( const QString &name ) const;
%Docstring
Returns a translated description string for the variable with specified
``name``.

If no specific description has been provided for the variable, the value
from :py:func:`QgsExpression.variableHelpText()` will be returned.
%End

    bool hasFunction( const QString &name ) const;
%Docstring
Checks whether a specified function is contained in the context.

:param name: function name

:return: ``True`` if context provides a matching function

.. seealso:: :py:func:`function`
%End

    QStringList functionNames() const;
%Docstring
Retrieves a list of function names contained in the context.

.. seealso:: :py:func:`function`

.. seealso:: :py:func:`variableNames`
%End

    QgsExpressionFunction *function( const QString &name ) const;
%Docstring
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

:return: function if contained by the context, otherwise ``None``.

.. seealso:: :py:func:`hasFunction`
%End

    int scopeCount() const;
%Docstring
Returns the number of scopes contained in the context.
%End

    void appendScope( QgsExpressionContextScope *scope /Transfer/ );
%Docstring
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
%End

    void appendScopes( const QList<QgsExpressionContextScope *> &scopes /Transfer/ );
%Docstring
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.

:param scopes: scopes to append to context
%End

    QgsExpressionContextScope *popScope();
%Docstring
Removes the last scope from the expression context and return it.
%End



    void setFeature( const QgsFeature &feature );
%Docstring
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

.. seealso:: :py:func:`feature`
%End

    bool hasFeature() const;
%Docstring
Returns ``True`` if the context has a feature associated with it.

.. seealso:: :py:func:`feature`
%End

    QgsFeature feature() const;
%Docstring
Convenience function for retrieving the feature for the context, if set.

.. seealso:: :py:func:`setFeature`
%End

    void setGeometry( const QgsGeometry &geometry );
%Docstring
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.

.. seealso:: :py:func:`geometry`

.. versionadded:: 3.24
%End

    bool hasGeometry() const;
%Docstring
Returns ``True`` if the context has a geometry associated with it.

.. seealso:: :py:func:`geometry`

.. versionadded:: 3.24
%End

    QgsGeometry geometry() const;
%Docstring
Convenience function for retrieving the geometry for the context, if
set.

.. seealso:: :py:func:`setGeometry`

.. versionadded:: 3.24
%End

    void setFields( const QgsFields &fields );
%Docstring
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

.. seealso:: :py:func:`fields`
%End

    QgsFields fields() const;
%Docstring
Convenience function for retrieving the fields for the context, if set.

.. seealso:: :py:func:`setFields`
%End

    void setOriginalValueVariable( const QVariant &value );
%Docstring
Sets the original value variable value for the context.

:param value: value for original value variable. This usually represents
              an original widget value before any data defined overrides
              have been applied.
%End

    void setCachedValue( const QString &key, const QVariant &value ) const;
%Docstring
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.

:param key: unique key for retrieving cached value
:param value: value to cache

.. seealso:: :py:func:`hasCachedValue`

.. seealso:: :py:func:`cachedValue`

.. seealso:: :py:func:`clearCachedValues`
%End

    bool hasCachedValue( const QString &key ) const;
%Docstring
Returns ``True`` if the expression context contains a cached value with
a matching key.

:param key: unique key used to store cached value

.. seealso:: :py:func:`setCachedValue`

.. seealso:: :py:func:`cachedValue`

.. seealso:: :py:func:`clearCachedValues`
%End

    QVariant cachedValue( const QString &key ) const;
%Docstring
Returns the matching cached value, if set. This can be used to retrieve
the previously stored results of an expensive expression
sub-calculation.

:param key: unique key used to store cached value

:return: matching cached value, or invalid QVariant if not set

.. seealso:: :py:func:`setCachedValue`

.. seealso:: :py:func:`hasCachedValue`

.. seealso:: :py:func:`clearCachedValues`
%End

    void clearCachedValues() const;
%Docstring
Clears all cached values from the context.

.. seealso:: :py:func:`setCachedValue`

.. seealso:: :py:func:`hasCachedValue`

.. seealso:: :py:func:`cachedValue`
%End

    QList< QgsMapLayerStore * > layerStores() const;
%Docstring
Returns the list of layer stores associated with the context.

.. versionadded:: 3.30
%End

    void setLoadedLayerStore( QgsMapLayerStore *store );
%Docstring
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.

.. seealso:: :py:func:`loadedLayerStore`

.. versionadded:: 3.30
%End

    QgsMapLayerStore *loadedLayerStore() const;
%Docstring
Returns the destination layer store for any layers loaded during
expression evaluation.

.. seealso:: :py:func:`setLoadedLayerStore`

.. versionadded:: 3.30
%End

    void setFeedback( QgsFeedback *feedback );
%Docstring
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.

.. seealso:: :py:func:`feedback`

.. versionadded:: 3.20
%End

    QgsFeedback *feedback() const;
%Docstring
Returns the feedback object that can be queried regularly by the
expression to check if evaluation should be canceled, if set.

.. seealso:: :py:func:`setFeedback`

.. versionadded:: 3.20
%End

    QString uniqueHash( bool &ok /Out/, const QSet<QString> &variables = QSet<QString>() ) const;
%Docstring
Returns a unique hash representing the current state of the context.

:param variables: optional names of a subset of variables to include in
                  the hash. If not specified, all variables will be
                  considered.

:return: - calculated hash
         - ok: ``True`` if the hash could be generated, or false if e.g.
           a variable value is of a type which cannot be hashed

.. versionadded:: 3.40
%End

    static const QString EXPR_FIELDS;
    static const QString EXPR_ORIGINAL_VALUE;
    static const QString EXPR_SYMBOL_COLOR;
    static const QString EXPR_SYMBOL_ANGLE;
    static const QString EXPR_GEOMETRY_PART_COUNT;
    static const QString EXPR_GEOMETRY_PART_NUM;

    static const QString EXPR_GEOMETRY_RING_NUM;
    static const QString EXPR_GEOMETRY_POINT_COUNT;
    static const QString EXPR_GEOMETRY_POINT_NUM;
    static const QString EXPR_CLUSTER_SIZE;
    static const QString EXPR_CLUSTER_COLOR;

};

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgsexpressioncontext.h                                      *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/