QGIS API Documentation  3.21.0-Master (5b68dc587e)
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  void setFields( const QgsFields &fields );
335 
341  void readXml( const QDomElement &element, const QgsReadWriteContext &context );
342 
348  bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
349 
350  private:
351  QString mName;
352  QHash<QString, StaticVariable> mVariables;
353  QHash<QString, QgsScopedExpressionFunction * > mFunctions;
354  bool mHasFeature = false;
355  QgsFeature mFeature;
356 };
357 
371 class CORE_EXPORT QgsExpressionContext
372 {
373  public:
374 
376  QgsExpressionContext() = default;
377 
383  explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
384 
389 
390  QgsExpressionContext &operator=( const QgsExpressionContext &other ) SIP_SKIP;
391 
392  QgsExpressionContext &operator=( QgsExpressionContext &&other ) noexcept SIP_SKIP;
393 
395 
403  bool hasVariable( const QString &name ) const;
404 
414  QVariant variable( const QString &name ) const;
415 
421  QVariantMap variablesToMap() const;
422 
430  bool isHighlightedVariable( const QString &name ) const;
431 
438  QStringList highlightedVariables() const;
439 
447  void setHighlightedVariables( const QStringList &variableNames );
448 
457  bool isHighlightedFunction( const QString &name ) const;
458 
470  void setHighlightedFunctions( const QStringList &names );
471 
479  QgsExpressionContextScope *activeScopeForVariable( const QString &name );
480 
489  const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
490 
497  QgsExpressionContextScope *scope( int index );
498 
503  QgsExpressionContextScope *lastScope();
504 
509  QList< QgsExpressionContextScope * > scopes() { return mStack; }
510 
516  int indexOfScope( QgsExpressionContextScope *scope ) const;
517 
524  int indexOfScope( const QString &scopeName ) const;
525 
534  QStringList variableNames() const;
535 
542  QStringList filteredVariableNames() const;
543 
550  bool isReadOnly( const QString &name ) const;
551 
560  QString description( const QString &name ) const;
561 
568  bool hasFunction( const QString &name ) const;
569 
575  QStringList functionNames() const;
576 
585  QgsExpressionFunction *function( const QString &name ) const;
586 
590  int scopeCount() const;
591 
598  void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
599 
607  void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
608 
612  QgsExpressionContextScope *popScope();
613 
622  QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
623 
630 
638  void setFeature( const QgsFeature &feature );
639 
645  bool hasFeature() const;
646 
651  QgsFeature feature() const;
652 
660  void setFields( const QgsFields &fields );
661 
666  QgsFields fields() const;
667 
674  void setOriginalValueVariable( const QVariant &value );
675 
687  void setCachedValue( const QString &key, const QVariant &value ) const;
688 
697  bool hasCachedValue( const QString &key ) const;
698 
709  QVariant cachedValue( const QString &key ) const;
710 
718  void clearCachedValues() const;
719 
731  void setFeedback( QgsFeedback *feedback );
732 
741  QgsFeedback *feedback() const;
742 
744  static const QString EXPR_FIELDS;
746  static const QString EXPR_ORIGINAL_VALUE;
748  static const QString EXPR_SYMBOL_COLOR;
750  static const QString EXPR_SYMBOL_ANGLE;
752  static const QString EXPR_GEOMETRY_PART_COUNT;
754  static const QString EXPR_GEOMETRY_PART_NUM;
755 
760  static const QString EXPR_GEOMETRY_RING_NUM;
762  static const QString EXPR_GEOMETRY_POINT_COUNT;
764  static const QString EXPR_GEOMETRY_POINT_NUM;
766  static const QString EXPR_CLUSTER_SIZE;
768  static const QString EXPR_CLUSTER_COLOR;
769 
770  private:
771 
772  QList< QgsExpressionContextScope * > mStack;
773  QStringList mHighlightedVariables;
774  QStringList mHighlightedFunctions;
775 
776  QgsFeedback *mFeedback = nullptr;
777 
778  // Cache is mutable because we want to be able to add cached values to const contexts
779  mutable QMap< QString, QVariant > mCachedValues;
780 
781 };
782 
783 #endif // QGSEXPRESSIONCONTEXT_H
Single scope for storing variables and functions for use within a QgsExpressionContext.
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.
QString name() const
Returns the friendly display name of the context scope.
int variableCount() const
Returns the count of variables contained within 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
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.