QGIS API Documentation  3.3.0-Master (77eafc0)
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 
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 
747  static QgsExpressionContextScope *formScope( const QgsFeature &formFeature = QgsFeature( ) ) SIP_FACTORY;
748 
758  static void setGlobalVariable( const QString &name, const QVariant &value );
759 
768  static void setGlobalVariables( const QVariantMap &variables );
769 
777  static void removeGlobalVariable( const QString &name );
778 
785  static QgsExpressionContextScope *projectScope( const QgsProject *project ) SIP_FACTORY;
786 
797  static void setProjectVariable( QgsProject *project, const QString &name, const QVariant &value );
798 
808  static void setProjectVariables( QgsProject *project, const QVariantMap &variables );
809 
818  static void removeProjectVariable( QgsProject *project, const QString &name );
819 
824  static QgsExpressionContextScope *layerScope( const QgsMapLayer *layer ) SIP_FACTORY;
825 
830  static QList<QgsExpressionContextScope *> globalProjectLayerScopes( const QgsMapLayer *layer ) SIP_FACTORY;
831 
841  static void setLayerVariable( QgsMapLayer *layer, const QString &name, const QVariant &value );
842 
851  static void setLayerVariables( QgsMapLayer *layer, const QVariantMap &variables );
852 
857  static QgsExpressionContextScope *mapSettingsScope( const QgsMapSettings &mapSettings ) SIP_FACTORY;
858 
865  static QgsExpressionContextScope *mapToolCaptureScope( const QList<QgsPointLocator::Match> &matches ) SIP_FACTORY;
866 
873  static QgsExpressionContextScope *updateSymbolScope( const QgsSymbol *symbol, QgsExpressionContextScope *symbolScope = nullptr );
874 
880  static QgsExpressionContextScope *layoutScope( const QgsLayout *layout ) SIP_FACTORY;
881 
892  static void setLayoutVariable( QgsLayout *layout, const QString &name, const QVariant &value );
893 
903  static void setLayoutVariables( QgsLayout *layout, const QVariantMap &variables );
904 
910  static QgsExpressionContextScope *atlasScope( QgsLayoutAtlas *atlas ) SIP_FACTORY;
911 
919  static QgsExpressionContextScope *layoutItemScope( const QgsLayoutItem *item ) SIP_FACTORY;
920 
929  static void setLayoutItemVariable( QgsLayoutItem *item, const QString &name, const QVariant &value );
930 
938  static void setLayoutItemVariables( QgsLayoutItem *item, const QVariantMap &variables );
939 
945  static QgsExpressionContext createFeatureBasedContext( const QgsFeature &feature, const QgsFields &fields );
946 
952  static QgsExpressionContextScope *processingAlgorithmScope( const QgsProcessingAlgorithm *algorithm, const QVariantMap &parameters, QgsProcessingContext &context ) SIP_FACTORY;
953 
958  static QgsExpressionContextScope *notificationScope( const QString &message = QString() ) SIP_FACTORY;
959 
963  static void registerContextFunctions();
964 
965 };
966 
967 #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:61
Base class for graphical items within a QgsLayout.
static const QString EXPR_GEOMETRY_POINT_COUNT
Inbuilt variable name for point count variable.
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:62
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:85
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.