QGIS API Documentation  3.0.2-Girona (307d082)
qgsexpressioncontext.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgsexpressioncontext.h
3  ----------------------
4  Date : April 2015
5  Copyright : (C) 2015 by Nyall Dawson
6  Email : nyall dot dawson at gmail dot com
7  ***************************************************************************
8  * *
9  * This program is free software; you can redistribute it and/or modify *
10  * it under the terms of the GNU General Public License as published by *
11  * the Free Software Foundation; either version 2 of the License, or *
12  * (at your option) any later version. *
13  * *
14  ***************************************************************************/
15 #ifndef QGSEXPRESSIONCONTEXT_H
16 #define QGSEXPRESSIONCONTEXT_H
17 
18 #include "qgis_core.h"
19 #include "qgis_sip.h"
20 #include "qgis.h"
21 #include <QVariant>
22 #include <QHash>
23 #include <QString>
24 #include <QStringList>
25 #include <QSet>
26 #include "qgsfeature.h"
27 #include "qgsexpression.h"
28 #include "qgsexpressionfunction.h"
29 #include "qgspointlocator.h"
30 
31 class QgsExpression;
32 class QgsExpressionNodeFunction;
33 class QgsMapLayer;
34 class QgsLayout;
35 class QgsComposition;
36 class QgsComposerItem;
37 class QgsAtlasComposition;
38 class QgsMapSettings;
39 class QgsProject;
40 class QgsSymbol;
43 class QgsLayoutAtlas;
44 class QgsLayoutItem;
45 
55 class CORE_EXPORT QgsScopedExpressionFunction : public QgsExpressionFunction
56 {
57  public:
58 
64  QgsScopedExpressionFunction( const QString &fnname,
65  int params,
66  const QString &group,
67  const QString &helpText = QString(),
68  bool usesGeometry = false,
69  const QSet<QString> &referencedColumns = QSet<QString>(),
70  bool lazyEval = false,
71  bool handlesNull = false,
72  bool isContextual = true )
73  : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
74  , mUsesGeometry( usesGeometry )
75  , mReferencedColumns( referencedColumns )
76  {}
77 
83  QgsScopedExpressionFunction( const QString &fnname,
84  const QgsExpressionFunction::ParameterList &params,
85  const QString &group,
86  const QString &helpText = QString(),
87  bool usesGeometry = false,
88  const QSet<QString> &referencedColumns = QSet<QString>(),
89  bool lazyEval = false,
90  bool handlesNull = false,
91  bool isContextual = true )
92  : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
93  , mUsesGeometry( usesGeometry )
94  , mReferencedColumns( referencedColumns )
95  {}
96 
97  QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override = 0;
98 
102  virtual QgsScopedExpressionFunction *clone() const = 0 SIP_FACTORY;
103 
104  bool usesGeometry( const QgsExpressionNodeFunction *node ) const override;
105 
106  QSet<QString> referencedColumns( const QgsExpressionNodeFunction *node ) const override;
107 
108  bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
109 
110  private:
111  bool mUsesGeometry;
112  QSet<QString> mReferencedColumns;
113 };
114 
115 
129 class CORE_EXPORT QgsExpressionContextScope
130 {
131  public:
132 
137  {
138 
147  StaticVariable( const QString &name = QString(), const QVariant &value = QVariant(), bool readOnly = false, bool isStatic = false, const QString &description = QString() )
148  : name( name )
149  , value( value )
150  , readOnly( readOnly )
151  , isStatic( isStatic )
152  , description( description )
153  {}
154 
156  QString name;
157 
159  QVariant value;
160 
162  bool readOnly;
163 
165  bool isStatic;
166 
168  QString description;
169  };
170 
175  QgsExpressionContextScope( const QString &name = QString() );
176 
181 
182  QgsExpressionContextScope &operator=( const QgsExpressionContextScope &other );
183 
185 
189  QString name() const { return mName; }
190 
198  void setVariable( const QString &name, const QVariant &value, bool isStatic = false );
199 
207  void addVariable( const QgsExpressionContextScope::StaticVariable &variable );
208 
215  bool removeVariable( const QString &name );
216 
224  bool hasVariable( const QString &name ) const;
225 
233  QVariant variable( const QString &name ) const;
234 
240  QStringList variableNames() const;
241 
248  QStringList filteredVariableNames() const;
249 
256  bool isReadOnly( const QString &name ) const;
257 
264  bool isStatic( const QString &name ) const;
265 
272  QString description( const QString &name ) const;
273 
277  int variableCount() const { return mVariables.count(); }
278 
286  bool hasFunction( const QString &name ) const;
287 
296  QgsExpressionFunction *function( const QString &name ) const;
297 
303  QStringList functionNames() const;
304 
311  void addFunction( const QString &name, QgsScopedExpressionFunction *function SIP_TRANSFER );
312 
318  bool hasFeature() const { return mHasFeature; }
319 
326  QgsFeature feature() const { return mFeature; }
327 
335  void setFeature( const QgsFeature &feature ) { mHasFeature = true; mFeature = feature; }
336 
343  void removeFeature() { mHasFeature = false; mFeature = QgsFeature(); }
344 
350  void setFields( const QgsFields &fields );
351 
352  private:
353  QString mName;
354  QHash<QString, StaticVariable> mVariables;
355  QHash<QString, QgsScopedExpressionFunction * > mFunctions;
356  bool mHasFeature = false;
357  QgsFeature mFeature;
358 
359  bool variableNameSort( const QString &a, const QString &b );
360 };
361 
375 class CORE_EXPORT QgsExpressionContext
376 {
377  public:
378 
380  QgsExpressionContext() = default;
381 
387  explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
388 
393 
394  QgsExpressionContext &operator=( const QgsExpressionContext &other ) SIP_SKIP;
395 
396  QgsExpressionContext &operator=( QgsExpressionContext &&other ) noexcept SIP_SKIP;
397 
399 
407  bool hasVariable( const QString &name ) const;
408 
418  QVariant variable( const QString &name ) const;
419 
425  QVariantMap variablesToMap() const;
426 
434  bool isHighlightedVariable( const QString &name ) const;
435 
442  void setHighlightedVariables( const QStringList &variableNames );
443 
451  QgsExpressionContextScope *activeScopeForVariable( const QString &name );
452 
461  const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
462 
469  QgsExpressionContextScope *scope( int index );
470 
475  QgsExpressionContextScope *lastScope();
476 
481  QList< QgsExpressionContextScope * > scopes() { return mStack; }
482 
488  int indexOfScope( QgsExpressionContextScope *scope ) const;
489 
496  int indexOfScope( const QString &scopeName ) const;
497 
506  QStringList variableNames() const;
507 
514  QStringList filteredVariableNames() const;
515 
522  bool isReadOnly( const QString &name ) const;
523 
532  QString description( const QString &name ) const;
533 
540  bool hasFunction( const QString &name ) const;
541 
547  QStringList functionNames() const;
548 
557  QgsExpressionFunction *function( const QString &name ) const;
558 
562  int scopeCount() const;
563 
570  void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
571 
579  void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
580 
584  QgsExpressionContextScope *popScope();
585 
594  QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
595 
602 
610  void setFeature( const QgsFeature &feature );
611 
617  bool hasFeature() const;
618 
623  QgsFeature feature() const;
624 
632  void setFields( const QgsFields &fields );
633 
638  QgsFields fields() const;
639 
646  void setOriginalValueVariable( const QVariant &value );
647 
659  void setCachedValue( const QString &key, const QVariant &value ) const;
660 
669  bool hasCachedValue( const QString &key ) const;
670 
681  QVariant cachedValue( const QString &key ) const;
682 
690  void clearCachedValues() const;
691 
693  static const QString EXPR_FIELDS;
695  static const QString EXPR_ORIGINAL_VALUE;
697  static const QString EXPR_SYMBOL_COLOR;
699  static const QString EXPR_SYMBOL_ANGLE;
701  static const QString EXPR_GEOMETRY_PART_COUNT;
703  static const QString EXPR_GEOMETRY_PART_NUM;
705  static const QString EXPR_GEOMETRY_POINT_COUNT;
707  static const QString EXPR_GEOMETRY_POINT_NUM;
709  static const QString EXPR_CLUSTER_SIZE;
711  static const QString EXPR_CLUSTER_COLOR;
712 
713  private:
714 
715  QList< QgsExpressionContextScope * > mStack;
716  QStringList mHighlightedVariables;
717 
718  // Cache is mutable because we want to be able to add cached values to const contexts
719  mutable QMap< QString, QVariant > mCachedValues;
720 
721 };
722 
731 class CORE_EXPORT QgsExpressionContextUtils
732 {
733  public:
734 
740  static QgsExpressionContextScope *globalScope() SIP_FACTORY;
741 
751  static void setGlobalVariable( const QString &name, const QVariant &value );
752 
761  static void setGlobalVariables( const QVariantMap &variables );
762 
770  static void removeGlobalVariable( const QString &name );
771 
778  static QgsExpressionContextScope *projectScope( const QgsProject *project ) SIP_FACTORY;
779 
790  static void setProjectVariable( QgsProject *project, const QString &name, const QVariant &value );
791 
801  static void setProjectVariables( QgsProject *project, const QVariantMap &variables );
802 
811  static void removeProjectVariable( QgsProject *project, const QString &name );
812 
817  static QgsExpressionContextScope *layerScope( const QgsMapLayer *layer ) SIP_FACTORY;
818 
823  static QList<QgsExpressionContextScope *> globalProjectLayerScopes( const QgsMapLayer *layer ) SIP_FACTORY;
824 
834  static void setLayerVariable( QgsMapLayer *layer, const QString &name, const QVariant &value );
835 
844  static void setLayerVariables( QgsMapLayer *layer, const QVariantMap &variables );
845 
850  static QgsExpressionContextScope *mapSettingsScope( const QgsMapSettings &mapSettings ) SIP_FACTORY;
851 
858  static QgsExpressionContextScope *mapToolCaptureScope( const QList<QgsPointLocator::Match> &matches ) SIP_FACTORY;
859 
866  static QgsExpressionContextScope *updateSymbolScope( const QgsSymbol *symbol, QgsExpressionContextScope *symbolScope = nullptr );
867 
873  static QgsExpressionContextScope *layoutScope( const QgsLayout *layout ) SIP_FACTORY;
874 
885  static void setLayoutVariable( QgsLayout *layout, const QString &name, const QVariant &value );
886 
896  static void setLayoutVariables( QgsLayout *layout, const QVariantMap &variables );
897 
903  static QgsExpressionContextScope *atlasScope( QgsLayoutAtlas *atlas ) SIP_FACTORY;
904 
912  static QgsExpressionContextScope *layoutItemScope( const QgsLayoutItem *item ) SIP_FACTORY;
913 
922  static void setLayoutItemVariable( QgsLayoutItem *item, const QString &name, const QVariant &value );
923 
931  static void setLayoutItemVariables( QgsLayoutItem *item, const QVariantMap &variables );
932 
938  static QgsExpressionContext createFeatureBasedContext( const QgsFeature &feature, const QgsFields &fields );
939 
945  static QgsExpressionContextScope *processingAlgorithmScope( const QgsProcessingAlgorithm *algorithm, const QVariantMap &parameters, QgsProcessingContext &context ) SIP_FACTORY;
946 
951  static QgsExpressionContextScope *notificationScope( const QString &message = QString() ) SIP_FACTORY;
952 
956  static void registerContextFunctions();
957 
958 };
959 
960 #endif // QGSEXPRESSIONCONTEXT_H
static const QString EXPR_ORIGINAL_VALUE
Inbuilt variable name for value original value variable.
static const QString EXPR_CLUSTER_COLOR
Inbuilt variable name for cluster color variable.
Single variable definition for use within a QgsExpressionContextScope.
Base class for all map layer types.
Definition: qgsmaplayer.h:56
Base class for graphical items within a QgsLayout.
static const QString EXPR_GEOMETRY_POINT_COUNT
Inbuilt variable name for point count variable.
Container of fields for a vector layer.
Definition: qgsfields.h:42
The feature class encapsulates a single feature including its id, geometry and a list of field/values...
Definition: qgsfeature.h:62
Abstract base class for processing algorithms.
The QgsMapSettings class contains configuration for rendering of the map.
int variableCount() const
Returns the count of variables contained within the scope.
static const QString EXPR_SYMBOL_ANGLE
Inbuilt variable name for symbol angle variable.
#define SIP_SKIP
Definition: qgis_sip.h:119
QString description
Translated description of variable, for use within expression builder widgets.
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
Class used to render an Atlas, iterating over geometry features.
bool readOnly
True if variable should not be editable by users.
#define SIP_TRANSFER
Definition: qgis_sip.h:36
static const QString EXPR_SYMBOL_COLOR
Inbuilt variable name for symbol color variable.
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)
Create a new QgsScopedExpressionFunction using named parameters.
Reads and writes project states.
Definition: qgsproject.h:82
std::ostream & operator<<(std::ostream &os, const QgsCoordinateReferenceSystem &r)
Output stream operator.
#define SIP_FACTORY
Definition: qgis_sip.h:69
static const QString EXPR_FIELDS
Inbuilt variable name for fields storage.
Single scope for storing variables and functions for use within a QgsExpressionContext.
void setFeature(const QgsFeature &feature)
Convenience function for setting a feature for the scope.
Base class for layouts, which can contain items such as maps, labels, scalebars, etc.
Definition: qgslayout.h:49
Contains utilities for working with QgsExpressionContext objects, including methods for creating scop...
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)
Create a new QgsScopedExpressionFunction.
StaticVariable(const QString &name=QString(), const QVariant &value=QVariant(), bool readOnly=false, bool isStatic=false, const QString &description=QString())
Constructor for StaticVariable.
static const QString EXPR_CLUSTER_SIZE
Inbuilt variable name for cluster size variable.
bool hasFeature() const
Returns true if the scope has a feature associated with it.
static const QString EXPR_GEOMETRY_POINT_NUM
Inbuilt variable name for point number variable.
QString name() const
Returns the friendly display name of the context scope.
void removeFeature()
Removes any feature associated with the scope.
static const QString EXPR_GEOMETRY_PART_NUM
Inbuilt variable name for geometry part number variable.
bool isStatic
A static variable can be cached for the lifetime of a context.
static const QString EXPR_GEOMETRY_PART_COUNT
Inbuilt variable name for geometry part count variable.
Contains information about the context in which a processing algorithm is executed.
QList< QgsExpressionContextScope *> scopes()
Returns a list of scopes contained within the stack.
Expression function for use within a QgsExpressionContextScope.
QgsFeature feature() const
Sets the feature associated with the scope.