QGIS API Documentation  3.27.0-Master (0e23467727)
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 "qgsexpressionfunction.h"
26 #include "qgsfeature.h"
27 
29 
40 {
41  public:
42 
48  QgsScopedExpressionFunction( const QString &fnname,
49  int params,
50  const QString &group,
51  const QString &helpText = QString(),
52  bool usesGeometry = false,
53  const QSet<QString> &referencedColumns = QSet<QString>(),
54  bool lazyEval = false,
55  bool handlesNull = false,
56  bool isContextual = true )
57  : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
58  , mUsesGeometry( usesGeometry )
59  , mReferencedColumns( referencedColumns )
60  {}
61 
67  QgsScopedExpressionFunction( const QString &fnname,
69  const QString &group,
70  const QString &helpText = QString(),
71  bool usesGeometry = false,
72  const QSet<QString> &referencedColumns = QSet<QString>(),
73  bool lazyEval = false,
74  bool handlesNull = false,
75  bool isContextual = true )
76  : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
77  , mUsesGeometry( usesGeometry )
78  , mReferencedColumns( referencedColumns )
79  {}
80 
81  QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override = 0;
82 
87 
88  bool usesGeometry( const QgsExpressionNodeFunction *node ) const override;
89 
90  QSet<QString> referencedColumns( const QgsExpressionNodeFunction *node ) const override;
91 
92  bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
93 
94  private:
95  bool mUsesGeometry;
96  QSet<QString> mReferencedColumns;
97 };
98 
99 
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 
248  bool isStatic( const QString &name ) const;
249 
256  QString description( const QString &name ) const;
257 
261  int variableCount() const { return mVariables.count(); }
262 
270  bool hasFunction( const QString &name ) const;
271 
280  QgsExpressionFunction *function( const QString &name ) const;
281 
287  QStringList functionNames() const;
288 
295  void addFunction( const QString &name, QgsScopedExpressionFunction *function SIP_TRANSFER );
296 
302  bool hasFeature() const { return mHasFeature; }
303 
310  QgsFeature feature() const { return mFeature; }
311 
319  void setFeature( const QgsFeature &feature ) { mHasFeature = true; mFeature = feature; }
320 
327  void removeFeature() { mHasFeature = false; mFeature = QgsFeature(); }
328 
334  bool hasGeometry() const { return mHasGeometry; }
335 
342  QgsGeometry geometry() const { return mGeometry; }
343 
352  void setGeometry( const QgsGeometry &geometry ) { mHasGeometry = true; mGeometry = geometry; }
353 
360  void removeGeometry() { mHasGeometry = false; mGeometry = QgsGeometry(); }
361 
367  void setFields( const QgsFields &fields );
368 
374  void readXml( const QDomElement &element, const QgsReadWriteContext &context );
375 
381  bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
382 
383  private:
384  QString mName;
385  QHash<QString, StaticVariable> mVariables;
386  QHash<QString, QgsScopedExpressionFunction * > mFunctions;
387  bool mHasFeature = false;
388  QgsFeature mFeature;
389  bool mHasGeometry = false;
390  QgsGeometry mGeometry;
391 };
392 
406 class CORE_EXPORT QgsExpressionContext
407 {
408  public:
409 
411  QgsExpressionContext() = default;
412 
418  explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
419 
424 
425  QgsExpressionContext &operator=( const QgsExpressionContext &other ) SIP_SKIP;
426 
427  QgsExpressionContext &operator=( QgsExpressionContext &&other ) noexcept SIP_SKIP;
428 
430 
438  bool hasVariable( const QString &name ) const;
439 
449  QVariant variable( const QString &name ) const;
450 
456  QVariantMap variablesToMap() const;
457 
465  bool isHighlightedVariable( const QString &name ) const;
466 
473  QStringList highlightedVariables() const;
474 
482  void setHighlightedVariables( const QStringList &variableNames );
483 
492  bool isHighlightedFunction( const QString &name ) const;
493 
505  void setHighlightedFunctions( const QStringList &names );
506 
514  QgsExpressionContextScope *activeScopeForVariable( const QString &name );
515 
524  const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
525 
532  QgsExpressionContextScope *scope( int index );
533 
538  QgsExpressionContextScope *lastScope();
539 
544  QList< QgsExpressionContextScope * > scopes() { return mStack; }
545 
551  int indexOfScope( QgsExpressionContextScope *scope ) const;
552 
559  int indexOfScope( const QString &scopeName ) const;
560 
569  QStringList variableNames() const;
570 
577  QStringList filteredVariableNames() const;
578 
585  bool isReadOnly( const QString &name ) const;
586 
595  QString description( const QString &name ) const;
596 
603  bool hasFunction( const QString &name ) const;
604 
610  QStringList functionNames() const;
611 
620  QgsExpressionFunction *function( const QString &name ) const;
621 
625  int scopeCount() const;
626 
633  void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
634 
642  void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
643 
647  QgsExpressionContextScope *popScope();
648 
657  QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
658 
665 
673  void setFeature( const QgsFeature &feature );
674 
680  bool hasFeature() const;
681 
686  QgsFeature feature() const;
687 
696  void setGeometry( const QgsGeometry &geometry );
697 
703  bool hasGeometry() const;
704 
710  QgsGeometry geometry() const;
711 
719  void setFields( const QgsFields &fields );
720 
725  QgsFields fields() const;
726 
733  void setOriginalValueVariable( const QVariant &value );
734 
746  void setCachedValue( const QString &key, const QVariant &value ) const;
747 
756  bool hasCachedValue( const QString &key ) const;
757 
768  QVariant cachedValue( const QString &key ) const;
769 
777  void clearCachedValues() const;
778 
790  void setFeedback( QgsFeedback *feedback );
791 
800  QgsFeedback *feedback() const;
801 
803  static const QString EXPR_FIELDS;
805  static const QString EXPR_ORIGINAL_VALUE;
807  static const QString EXPR_SYMBOL_COLOR;
809  static const QString EXPR_SYMBOL_ANGLE;
811  static const QString EXPR_GEOMETRY_PART_COUNT;
813  static const QString EXPR_GEOMETRY_PART_NUM;
814 
819  static const QString EXPR_GEOMETRY_RING_NUM;
821  static const QString EXPR_GEOMETRY_POINT_COUNT;
823  static const QString EXPR_GEOMETRY_POINT_NUM;
825  static const QString EXPR_CLUSTER_SIZE;
827  static const QString EXPR_CLUSTER_COLOR;
828 
829  private:
830 
831  QList< QgsExpressionContextScope * > mStack;
832  QStringList mHighlightedVariables;
833  QStringList mHighlightedFunctions;
834 
835  QgsFeedback *mFeedback = nullptr;
836 
837  // Cache is mutable because we want to be able to add cached values to const contexts
838  mutable QMap< QString, QVariant > mCachedValues;
839 
840 };
841 
842 #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...
QgsExpressionContext()=default
Constructor for QgsExpressionContext.
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:45
Container of fields for a vector layer.
Definition: qgsfields.h:45
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:125
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.
#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.