qgsexpressioncontext.h

Go to the documentation of this file.

/***************************************************************************
     qgsexpressioncontext.h
     ----------------------
    Date                 : April 2015
    Copyright            : (C) 2015 by Nyall Dawson
    Email                : nyall dot dawson at gmail dot com
 ***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
#ifndef QGSEXPRESSIONCONTEXT_H
#define QGSEXPRESSIONCONTEXT_H

#include "qgis_core.h"
#include "qgis_sip.h"
#include "qgis.h"
#include <QVariant>
#include <QHash>
#include <QString>
#include <QStringList>
#include <QSet>
#include "qgsfeature.h"
#include "qgsexpression.h"
#include "qgsexpressionfunction.h"
#include "qgspointlocator.h"

class QgsExpression;
class QgsExpressionNodeFunction;
class QgsMapLayer;
class QgsLayout;
class QgsComposition;
class QgsComposerItem;
class QgsAtlasComposition;
class QgsMapSettings;
class QgsProject;
class QgsSymbol;
class QgsProcessingAlgorithm;
class QgsProcessingContext;
class QgsLayoutAtlas;
class QgsLayoutItem;

class CORE_EXPORT QgsScopedExpressionFunction : public QgsExpressionFunction
{
  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 )
      : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
      , mUsesGeometry( usesGeometry )
      , mReferencedColumns( referencedColumns )
    {}

    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 )
      : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
      , mUsesGeometry( usesGeometry )
      , mReferencedColumns( referencedColumns )
    {}

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

    virtual QgsScopedExpressionFunction *clone() const = 0 SIP_FACTORY;

    bool usesGeometry( const QgsExpressionNodeFunction *node ) const override;

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

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

  private:
    bool mUsesGeometry;
    QSet<QString> mReferencedColumns;
};


class CORE_EXPORT QgsExpressionContextScope
{
  public:

    struct StaticVariable
    {

      StaticVariable( const QString &name = QString(), const QVariant &value = QVariant(), bool readOnly = false, bool isStatic = false, const QString &description = QString() )
        : name( name )
        , value( value )
        , readOnly( readOnly )
        , isStatic( isStatic )
        , description( description )
      {}

      QString name;

      QVariant value;

      bool readOnly;

      bool isStatic;

      QString description;
    };

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

    QgsExpressionContextScope( const QgsExpressionContextScope &other );

    QgsExpressionContextScope &operator=( const QgsExpressionContextScope &other );

    ~QgsExpressionContextScope();

    QString name() const { return mName; }

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

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

    bool removeVariable( const QString &name );

    bool hasVariable( const QString &name ) const;

    QVariant variable( const QString &name ) const;

    QStringList variableNames() const;

    QStringList filteredVariableNames() const;

    bool isReadOnly( const QString &name ) const;

    bool isStatic( const QString &name ) const;

    QString description( const QString &name ) const;

    int variableCount() const { return mVariables.count(); }

    bool hasFunction( const QString &name ) const;

    QgsExpressionFunction *function( const QString &name ) const;

    QStringList functionNames() const;

    void addFunction( const QString &name, QgsScopedExpressionFunction *function SIP_TRANSFER );

    bool hasFeature() const { return mHasFeature; }

    QgsFeature feature() const { return mFeature; }

    void setFeature( const QgsFeature &feature ) { mHasFeature = true; mFeature = feature; }

    void removeFeature() { mHasFeature = false; mFeature = QgsFeature(); }

    void setFields( const QgsFields &fields );

  private:
    QString mName;
    QHash<QString, StaticVariable> mVariables;
    QHash<QString, QgsScopedExpressionFunction * > mFunctions;
    bool mHasFeature = false;
    QgsFeature mFeature;

    bool variableNameSort( const QString &a, const QString &b );
};

class CORE_EXPORT QgsExpressionContext
{
  public:

    QgsExpressionContext() = default;

    explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );

    QgsExpressionContext( const QgsExpressionContext &other );

    QgsExpressionContext &operator=( const QgsExpressionContext &other ) SIP_SKIP;

    QgsExpressionContext &operator=( QgsExpressionContext &&other ) noexcept SIP_SKIP;

    ~QgsExpressionContext();

    bool hasVariable( const QString &name ) const;

    QVariant variable( const QString &name ) const;

    QVariantMap variablesToMap() const;

    bool isHighlightedVariable( const QString &name ) const;

    void setHighlightedVariables( const QStringList &variableNames );

    QgsExpressionContextScope *activeScopeForVariable( const QString &name );

    const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;

    QgsExpressionContextScope *scope( int index );

    QgsExpressionContextScope *lastScope();

    QList< QgsExpressionContextScope * > scopes() { return mStack; }

    int indexOfScope( QgsExpressionContextScope *scope ) const;

    int indexOfScope( const QString &scopeName ) const;

    QStringList variableNames() const;

    QStringList filteredVariableNames() const;

    bool isReadOnly( const QString &name ) const;

    QString description( const QString &name ) const;

    bool hasFunction( const QString &name ) const;

    QStringList functionNames() const;

    QgsExpressionFunction *function( const QString &name ) const;

    int scopeCount() const;

    void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );

    void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );

    QgsExpressionContextScope *popScope();

    QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;

    QgsExpressionContext &operator<< ( QgsExpressionContextScope *scope SIP_TRANSFER );

    void setFeature( const QgsFeature &feature );

    bool hasFeature() const;

    QgsFeature feature() const;

    void setFields( const QgsFields &fields );

    QgsFields fields() const;

    void setOriginalValueVariable( const QVariant &value );

    void setCachedValue( const QString &key, const QVariant &value ) const;

    bool hasCachedValue( const QString &key ) const;

    QVariant cachedValue( const QString &key ) const;

    void clearCachedValues() const;

    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_POINT_COUNT;
    static const QString EXPR_GEOMETRY_POINT_NUM;
    static const QString EXPR_CLUSTER_SIZE;
    static const QString EXPR_CLUSTER_COLOR;

  private:

    QList< QgsExpressionContextScope * > mStack;
    QStringList mHighlightedVariables;

    // Cache is mutable because we want to be able to add cached values to const contexts
    mutable QMap< QString, QVariant > mCachedValues;

};

class CORE_EXPORT QgsExpressionContextUtils
{
  public:

    static QgsExpressionContextScope *globalScope() SIP_FACTORY;

    static QgsExpressionContextScope *formScope( const QgsFeature &formFeature = QgsFeature( ) ) SIP_FACTORY;

    static void setGlobalVariable( const QString &name, const QVariant &value );

    static void setGlobalVariables( const QVariantMap &variables );

    static void removeGlobalVariable( const QString &name );

    static QgsExpressionContextScope *projectScope( const QgsProject *project ) SIP_FACTORY;

    static void setProjectVariable( QgsProject *project, const QString &name, const QVariant &value );

    static void setProjectVariables( QgsProject *project, const QVariantMap &variables );

    static void removeProjectVariable( QgsProject *project, const QString &name );

    static QgsExpressionContextScope *layerScope( const QgsMapLayer *layer ) SIP_FACTORY;

    static QList<QgsExpressionContextScope *> globalProjectLayerScopes( const QgsMapLayer *layer ) SIP_FACTORY;

    static void setLayerVariable( QgsMapLayer *layer, const QString &name, const QVariant &value );

    static void setLayerVariables( QgsMapLayer *layer, const QVariantMap &variables );

    static QgsExpressionContextScope *mapSettingsScope( const QgsMapSettings &mapSettings ) SIP_FACTORY;

    static QgsExpressionContextScope *mapToolCaptureScope( const QList<QgsPointLocator::Match> &matches ) SIP_FACTORY;

    static QgsExpressionContextScope *updateSymbolScope( const QgsSymbol *symbol, QgsExpressionContextScope *symbolScope = nullptr );

    static QgsExpressionContextScope *layoutScope( const QgsLayout *layout ) SIP_FACTORY;

    static void setLayoutVariable( QgsLayout *layout, const QString &name, const QVariant &value );

    static void setLayoutVariables( QgsLayout *layout, const QVariantMap &variables );

    static QgsExpressionContextScope *atlasScope( QgsLayoutAtlas *atlas ) SIP_FACTORY;

    static QgsExpressionContextScope *layoutItemScope( const QgsLayoutItem *item ) SIP_FACTORY;

    static void setLayoutItemVariable( QgsLayoutItem *item, const QString &name, const QVariant &value );

    static void setLayoutItemVariables( QgsLayoutItem *item, const QVariantMap &variables );

    static QgsExpressionContext createFeatureBasedContext( const QgsFeature &feature, const QgsFields &fields );

    static QgsExpressionContextScope *processingAlgorithmScope( const QgsProcessingAlgorithm *algorithm, const QVariantMap &parameters, QgsProcessingContext &context ) SIP_FACTORY;

    static QgsExpressionContextScope *notificationScope( const QString &message = QString() ) SIP_FACTORY;

    static void registerContextFunctions();

};

#endif // QGSEXPRESSIONCONTEXT_H