QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
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 <QVariant>
21 #include <QHash>
22 #include <QString>
23 #include <QStringList>
24 #include <QSet>
25 #include <QPointer>
26 
27 #include "qgsexpressionfunction.h"
28 #include "qgsfeature.h"
29 
31 class QgsMapLayerStore;
32 class LoadLayerFunction;
33 
43 {
44  public:
45 
50  QgsScopedExpressionFunction( const QString &fnname,
51  int params,
52  const QString &group,
53  const QString &helpText = QString(),
54  bool usesGeometry = false,
55  const QSet<QString> &referencedColumns = QSet<QString>(),
56  bool lazyEval = false,
57  bool handlesNull = false,
58  bool isContextual = true )
59  : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
60  , mUsesGeometry( usesGeometry )
61  , mReferencedColumns( referencedColumns )
62  {}
63 
68  QgsScopedExpressionFunction( const QString &fnname,
70  const QString &group,
71  const QString &helpText = QString(),
72  bool usesGeometry = false,
73  const QSet<QString> &referencedColumns = QSet<QString>(),
74  bool lazyEval = false,
75  bool handlesNull = false,
76  bool isContextual = true )
77  : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
78  , mUsesGeometry( usesGeometry )
79  , mReferencedColumns( referencedColumns )
80  {}
81 
82  QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override = 0;
83 
88 
89  bool usesGeometry( const QgsExpressionNodeFunction *node ) const override;
90 
91  QSet<QString> referencedColumns( const QgsExpressionNodeFunction *node ) const override;
92 
93  bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
94 
95  private:
96  bool mUsesGeometry;
97  QSet<QString> mReferencedColumns;
98 };
99 
100 
113 class CORE_EXPORT QgsExpressionContextScope
114 {
115  public:
116 
121  {
122 
131  StaticVariable( const QString &name = QString(), const QVariant &value = QVariant(), bool readOnly = false, bool isStatic = false, const QString &description = QString() )
132  : name( name )
133  , value( value )
134  , readOnly( readOnly )
135  , isStatic( isStatic )
136  , description( description )
137  {}
138 
140  QString name;
141 
143  QVariant value;
144 
146  bool readOnly;
147 
149  bool isStatic;
150 
152  QString description;
153  };
154 
159  QgsExpressionContextScope( const QString &name = QString() );
160 
165 
166  QgsExpressionContextScope &operator=( const QgsExpressionContextScope &other );
167 
169 
173  QString name() const { return mName; }
174 
182  void setVariable( const QString &name, const QVariant &value, bool isStatic = false );
183 
191  void addVariable( const QgsExpressionContextScope::StaticVariable &variable );
192 
199  bool removeVariable( const QString &name );
200 
208  bool hasVariable( const QString &name ) const;
209 
217  QVariant variable( const QString &name ) const;
218 
224  QStringList variableNames() const;
225 
232  QStringList filteredVariableNames() const;
233 
240  bool isReadOnly( const QString &name ) const;
241 
247  bool isStatic( const QString &name ) const;
248 
254  QString description( const QString &name ) const;
255 
259  int variableCount() const { return mVariables.count(); }
260 
268  bool hasFunction( const QString &name ) const;
269 
278  QgsExpressionFunction *function( const QString &name ) const;
279 
285  QStringList functionNames() const;
286 
293  void addFunction( const QString &name, QgsScopedExpressionFunction *function SIP_TRANSFER );
294 
299  bool hasFeature() const { return mHasFeature; }
300 
306  QgsFeature feature() const { return mFeature; }
307 
315  void setFeature( const QgsFeature &feature ) { mHasFeature = true; mFeature = feature; }
316 
322  void removeFeature() { mHasFeature = false; mFeature = QgsFeature(); }
323 
329  bool hasGeometry() const { return mHasGeometry; }
330 
337  QgsGeometry geometry() const { return mGeometry; }
338 
347  void setGeometry( const QgsGeometry &geometry ) { mHasGeometry = true; mGeometry = geometry; }
348 
355  void removeGeometry() { mHasGeometry = false; mGeometry = QgsGeometry(); }
356 
362  void setFields( const QgsFields &fields );
363 
369  void readXml( const QDomElement &element, const QgsReadWriteContext &context );
370 
376  bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
377 
378 
387  QStringList hiddenVariables() const;
388 
399  void setHiddenVariables( const QStringList &hiddenVariables );
400 
401 
412  void addHiddenVariable( const QString &hiddenVariable );
413 
423  void removeHiddenVariable( const QString &hiddenVariable );
424 
435  void addLayerStore( QgsMapLayerStore *store );
436 
443  QList< QgsMapLayerStore * > layerStores() const;
444 
445  private:
446  QString mName;
447  QHash<QString, StaticVariable> mVariables;
448  QHash<QString, QgsScopedExpressionFunction * > mFunctions;
449  bool mHasFeature = false;
450  QgsFeature mFeature;
451  bool mHasGeometry = false;
452  QgsGeometry mGeometry;
453  QStringList mHiddenVariables;
454 
455  QList< QPointer< QgsMapLayerStore > > mLayerStores;
456 };
457 
470 class CORE_EXPORT QgsExpressionContext
471 {
472  public:
473 
476 
481  explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
482 
487 
488  QgsExpressionContext &operator=( const QgsExpressionContext &other ) SIP_SKIP;
489 
490  QgsExpressionContext &operator=( QgsExpressionContext &&other ) noexcept SIP_SKIP;
491 
493 
501  bool hasVariable( const QString &name ) const;
502 
512  QVariant variable( const QString &name ) const;
513 
518  QVariantMap variablesToMap() const;
519 
527  bool isHighlightedVariable( const QString &name ) const;
528 
535  QStringList highlightedVariables() const;
536 
544  void setHighlightedVariables( const QStringList &variableNames );
545 
554  bool isHighlightedFunction( const QString &name ) const;
555 
567  void setHighlightedFunctions( const QStringList &names );
568 
576  QgsExpressionContextScope *activeScopeForVariable( const QString &name );
577 
586  const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
587 
594  QgsExpressionContextScope *scope( int index );
595 
600  QgsExpressionContextScope *lastScope();
601 
606  QList< QgsExpressionContextScope * > scopes() { return mStack; }
607 
613  int indexOfScope( QgsExpressionContextScope *scope ) const;
614 
620  int indexOfScope( const QString &scopeName ) const;
621 
630  QStringList variableNames() const;
631 
638  QStringList filteredVariableNames() const;
639 
646  bool isReadOnly( const QString &name ) const;
647 
655  QString description( const QString &name ) const;
656 
663  bool hasFunction( const QString &name ) const;
664 
670  QStringList functionNames() const;
671 
680  QgsExpressionFunction *function( const QString &name ) const;
681 
685  int scopeCount() const;
686 
693  void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
694 
701  void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
702 
706  QgsExpressionContextScope *popScope();
707 
715  QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
716 
723 
731  void setFeature( const QgsFeature &feature );
732 
737  bool hasFeature() const;
738 
743  QgsFeature feature() const;
744 
753  void setGeometry( const QgsGeometry &geometry );
754 
760  bool hasGeometry() const;
761 
767  QgsGeometry geometry() const;
768 
776  void setFields( const QgsFields &fields );
777 
782  QgsFields fields() const;
783 
789  void setOriginalValueVariable( const QVariant &value );
790 
801  void setCachedValue( const QString &key, const QVariant &value ) const;
802 
810  bool hasCachedValue( const QString &key ) const;
811 
821  QVariant cachedValue( const QString &key ) const;
822 
829  void clearCachedValues() const;
830 
836  QList< QgsMapLayerStore * > layerStores() const;
837 
849  void setLoadedLayerStore( QgsMapLayerStore *store );
850 
858  QgsMapLayerStore *loadedLayerStore() const;
859 
871  void setFeedback( QgsFeedback *feedback );
872 
881  QgsFeedback *feedback() const;
882 
884  static const QString EXPR_FIELDS;
886  static const QString EXPR_ORIGINAL_VALUE;
888  static const QString EXPR_SYMBOL_COLOR;
890  static const QString EXPR_SYMBOL_ANGLE;
892  static const QString EXPR_GEOMETRY_PART_COUNT;
894  static const QString EXPR_GEOMETRY_PART_NUM;
895 
900  static const QString EXPR_GEOMETRY_RING_NUM;
902  static const QString EXPR_GEOMETRY_POINT_COUNT;
904  static const QString EXPR_GEOMETRY_POINT_NUM;
906  static const QString EXPR_CLUSTER_SIZE;
908  static const QString EXPR_CLUSTER_COLOR;
909 
910  private:
911 
912  QList< QgsExpressionContextScope * > mStack;
913  QStringList mHighlightedVariables;
914  QStringList mHighlightedFunctions;
915 
916  QgsFeedback *mFeedback = nullptr;
917 
918  std::unique_ptr< LoadLayerFunction > mLoadLayerFunction;
919  QPointer< QgsMapLayerStore > mDestinationStore;
920 
921  // Cache is mutable because we want to be able to add cached values to const contexts
922  mutable QMap< QString, QVariant > mCachedValues;
923 
924 };
925 
926 #endif // QGSEXPRESSIONCONTEXT_H
Single scope for storing variables and functions for use within a QgsExpressionContext.
void removeGeometry()
Removes any geometry associated with the scope.
void removeFeature()
Removes any feature associated with the scope.
void setFeature(const QgsFeature &feature)
Convenience function for setting a feature for the scope.
bool hasFeature() const
Returns true if the scope has a feature associated with it.
QgsGeometry geometry() const
Sets the geometry associated with the scope.
QString name() const
Returns the friendly display name of the context scope.
int variableCount() const
Returns the count of variables contained within the scope.
bool hasGeometry() const
Returns true if the scope has a geometry associated with it.
void setGeometry(const QgsGeometry &geometry)
Convenience function for setting a geometry for the scope.
QgsFeature feature() const
Sets the feature associated with the scope.
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
QList< QgsExpressionContextScope * > scopes()
Returns a list of scopes contained within the stack.
A abstract base class for defining QgsExpression functions.
QList< QgsExpressionFunction::Parameter > ParameterList
List of parameters, used for function definition.
virtual bool isStatic(const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context) const
Will be called during prepare to determine if the function is static.
QString name() const
The name of the function.
virtual QSet< QString > referencedColumns(const QgsExpressionNodeFunction *node) const
Returns a set of field names which are required for this function.
virtual bool usesGeometry(const QgsExpressionNodeFunction *node) const
Does this function use a geometry object.
An expression node for expression functions.
Class for parsing and evaluation of expressions (formerly called "search strings").
The feature class encapsulates a single feature including its unique ID, geometry and a list of field...
Definition: qgsfeature.h:56
Base class for feedback objects to be used for cancellation of something running in a worker thread.
Definition: qgsfeedback.h:44
Container of fields for a vector layer.
Definition: qgsfields.h:45
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:162
A storage object for map layers, in which the layers are owned by the store and have their lifetime b...
The class is used as a container of context for various read/write operations on other objects.
Expression function for use within a QgsExpressionContextScope.
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.
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.
QVariant func(const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node) override=0
Returns result of evaluating the function.
virtual QgsScopedExpressionFunction * clone() const =0
Returns a clone of the function.
std::unique_ptr< GEOSGeometry, GeosDeleter > unique_ptr
Scoped GEOS pointer.
Definition: qgsgeos.h:73
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_TRANSFER
Definition: qgis_sip.h:36
#define SIP_FACTORY
Definition: qgis_sip.h:76
Single variable definition for use within a QgsExpressionContextScope.
bool readOnly
True if variable should not be editable by users.
StaticVariable(const QString &name=QString(), const QVariant &value=QVariant(), bool readOnly=false, bool isStatic=false, const QString &description=QString())
Constructor for StaticVariable.
bool isStatic
A static variable can be cached for the lifetime of a context.
QString description
Translated description of variable, for use within expression builder widgets.