QGIS API Documentation  3.3.0-Master (208571a)
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;
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 
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,
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 
443  void setHighlightedVariables( const QStringList &variableNames );
444 
453  bool isHighlightedFunction( const QString &name ) const;
454 
466  void setHighlightedFunctions( const QStringList &names );
467 
475  QgsExpressionContextScope *activeScopeForVariable( const QString &name );
476 
485  const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
486 
493  QgsExpressionContextScope *scope( int index );
494 
499  QgsExpressionContextScope *lastScope();
500 
505  QList< QgsExpressionContextScope * > scopes() { return mStack; }
506 
512  int indexOfScope( QgsExpressionContextScope *scope ) const;
513 
520  int indexOfScope( const QString &scopeName ) const;
521 
530  QStringList variableNames() const;
531 
538  QStringList filteredVariableNames() const;
539 
546  bool isReadOnly( const QString &name ) const;
547 
556  QString description( const QString &name ) const;
557 
564  bool hasFunction( const QString &name ) const;
565 
571  QStringList functionNames() const;
572 
581  QgsExpressionFunction *function( const QString &name ) const;
582 
586  int scopeCount() const;
587 
594  void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
595 
603  void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
604 
608  QgsExpressionContextScope *popScope();
609 
618  QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
619 
626 
634  void setFeature( const QgsFeature &feature );
635 
641  bool hasFeature() const;
642 
647  QgsFeature feature() const;
648 
656  void setFields( const QgsFields &fields );
657 
662  QgsFields fields() const;
663 
670  void setOriginalValueVariable( const QVariant &value );
671 
683  void setCachedValue( const QString &key, const QVariant &value ) const;
684 
693  bool hasCachedValue( const QString &key ) const;
694 
705  QVariant cachedValue( const QString &key ) const;
706 
714  void clearCachedValues() const;
715 
717  static const QString EXPR_FIELDS;
719  static const QString EXPR_ORIGINAL_VALUE;
721  static const QString EXPR_SYMBOL_COLOR;
723  static const QString EXPR_SYMBOL_ANGLE;
725  static const QString EXPR_GEOMETRY_PART_COUNT;
727  static const QString EXPR_GEOMETRY_PART_NUM;
729  static const QString EXPR_GEOMETRY_POINT_COUNT;
731  static const QString EXPR_GEOMETRY_POINT_NUM;
733  static const QString EXPR_CLUSTER_SIZE;
735  static const QString EXPR_CLUSTER_COLOR;
736 
737  private:
738 
739  QList< QgsExpressionContextScope * > mStack;
740  QStringList mHighlightedVariables;
741  QStringList mHighlightedFunctions;
742 
743  // Cache is mutable because we want to be able to add cached values to const contexts
744  mutable QMap< QString, QVariant > mCachedValues;
745 
746 };
747 
756 class CORE_EXPORT QgsExpressionContextUtils
757 {
758  public:
759 
765  static QgsExpressionContextScope *globalScope() SIP_FACTORY;
766 
773  static QgsExpressionContextScope *formScope( const QgsFeature &formFeature = QgsFeature( ), const QString &formMode = QString() ) SIP_FACTORY;
774 
784  static void setGlobalVariable( const QString &name, const QVariant &value );
785 
794  static void setGlobalVariables( const QVariantMap &variables );
795 
803  static void removeGlobalVariable( const QString &name );
804 
811  static QgsExpressionContextScope *projectScope( const QgsProject *project ) SIP_FACTORY;
812 
823  static void setProjectVariable( QgsProject *project, const QString &name, const QVariant &value );
824 
834  static void setProjectVariables( QgsProject *project, const QVariantMap &variables );
835 
844  static void removeProjectVariable( QgsProject *project, const QString &name );
845 
850  static QgsExpressionContextScope *layerScope( const QgsMapLayer *layer ) SIP_FACTORY;
851 
856  static QList<QgsExpressionContextScope *> globalProjectLayerScopes( const QgsMapLayer *layer ) SIP_FACTORY;
857 
867  static void setLayerVariable( QgsMapLayer *layer, const QString &name, const QVariant &value );
868 
877  static void setLayerVariables( QgsMapLayer *layer, const QVariantMap &variables );
878 
883  static QgsExpressionContextScope *mapSettingsScope( const QgsMapSettings &mapSettings ) SIP_FACTORY;
884 
891  static QgsExpressionContextScope *mapToolCaptureScope( const QList<QgsPointLocator::Match> &matches ) SIP_FACTORY;
892 
899  static QgsExpressionContextScope *updateSymbolScope( const QgsSymbol *symbol, QgsExpressionContextScope *symbolScope = nullptr );
900 
906  static QgsExpressionContextScope *layoutScope( const QgsLayout *layout ) SIP_FACTORY;
907 
918  static void setLayoutVariable( QgsLayout *layout, const QString &name, const QVariant &value );
919 
929  static void setLayoutVariables( QgsLayout *layout, const QVariantMap &variables );
930 
936  static QgsExpressionContextScope *atlasScope( QgsLayoutAtlas *atlas ) SIP_FACTORY;
937 
945  static QgsExpressionContextScope *layoutItemScope( const QgsLayoutItem *item ) SIP_FACTORY;
946 
955  static void setLayoutItemVariable( QgsLayoutItem *item, const QString &name, const QVariant &value );
956 
964  static void setLayoutItemVariables( QgsLayoutItem *item, const QVariantMap &variables );
965 
971  static QgsExpressionContext createFeatureBasedContext( const QgsFeature &feature, const QgsFields &fields );
972 
978  static QgsExpressionContextScope *processingAlgorithmScope( const QgsProcessingAlgorithm *algorithm, const QVariantMap &parameters, QgsProcessingContext &context ) SIP_FACTORY;
979 
984  static QgsExpressionContextScope *notificationScope( const QString &message = QString() ) SIP_FACTORY;
985 
989  static void registerContextFunctions();
990 
991 };
992 
993 #endif // QGSEXPRESSIONCONTEXT_H
static const QString EXPR_ORIGINAL_VALUE
Inbuilt variable name for value original value variable.
Class for parsing and evaluation of expressions (formerly called "search strings").
static const QString EXPR_CLUSTER_COLOR
Inbuilt variable name for cluster color variable.
virtual QVariant func(const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node)=0
Returns result of evaluating the function.
Single variable definition for use within a QgsExpressionContextScope.
Base class for all map layer types.
Definition: qgsmaplayer.h:63
Base class for graphical items within a QgsLayout.
static const QString EXPR_GEOMETRY_POINT_COUNT
Inbuilt variable name for point count variable.
Abstract base class for all rendered symbols.
Definition: qgssymbol.h:63
virtual QSet< QString > referencedColumns(const QgsExpressionNodeFunction *node) const
Returns a set of field names which are required for this function.
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:54
Abstract base class for processing algorithms.
QList< QgsExpressionFunction::Parameter > ParameterList
List of parameters, used for function definition.
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 QgsLayout as an atlas, by iterating over the features from an associated vector ...
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:89
virtual bool isStatic(const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context) const
Will be called during prepare to determine if the function is static.
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.
An expression node for expression functions.
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
As part of the API refactoring and improvements which landed in the Processing API was substantially reworked from the x version This was done in order to allow much of the underlying Processing framework to be ported into allowing algorithms to be written in pure substantial changes are required in order to port existing x Processing algorithms for QGIS x The most significant changes are outlined not GeoAlgorithm For algorithms which operate on features one by consider subclassing the QgsProcessingFeatureBasedAlgorithm class This class allows much of the boilerplate code for looping over features from a vector layer to be bypassed and instead requires implementation of a processFeature method Ensure that your algorithm(or algorithm 's parent class) implements the new pure virtual createInstance(self) call
virtual bool usesGeometry(const QgsExpressionNodeFunction *node) const
Does this function use a geometry object.
Contains utilities for working with QgsExpressionContext objects, including methods for creating scop...
A abstract base class for defining QgsExpression functions.
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.