QGIS API Documentation  3.9.0-Master (224899f119)
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 
38 {
39  public:
40 
46  QgsScopedExpressionFunction( const QString &fnname,
47  int params,
48  const QString &group,
49  const QString &helpText = QString(),
50  bool usesGeometry = false,
51  const QSet<QString> &referencedColumns = QSet<QString>(),
52  bool lazyEval = false,
53  bool handlesNull = false,
54  bool isContextual = true )
55  : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
56  , mUsesGeometry( usesGeometry )
57  , mReferencedColumns( referencedColumns )
58  {}
59 
65  QgsScopedExpressionFunction( const QString &fnname,
67  const QString &group,
68  const QString &helpText = QString(),
69  bool usesGeometry = false,
70  const QSet<QString> &referencedColumns = QSet<QString>(),
71  bool lazyEval = false,
72  bool handlesNull = false,
73  bool isContextual = true )
74  : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
75  , mUsesGeometry( usesGeometry )
76  , mReferencedColumns( referencedColumns )
77  {}
78 
79  QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override = 0;
80 
84  virtual QgsScopedExpressionFunction *clone() const = 0 SIP_FACTORY;
85 
86  bool usesGeometry( const QgsExpressionNodeFunction *node ) const override;
87 
88  QSet<QString> referencedColumns( const QgsExpressionNodeFunction *node ) const override;
89 
90  bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
91 
92  private:
93  bool mUsesGeometry;
94  QSet<QString> mReferencedColumns;
95 };
96 
97 
111 class CORE_EXPORT QgsExpressionContextScope
112 {
113  public:
114 
119  {
120 
129  StaticVariable( const QString &name = QString(), const QVariant &value = QVariant(), bool readOnly = false, bool isStatic = false, const QString &description = QString() )
130  : name( name )
131  , value( value )
132  , readOnly( readOnly )
133  , isStatic( isStatic )
134  , description( description )
135  {}
136 
138  QString name;
139 
141  QVariant value;
142 
144  bool readOnly;
145 
147  bool isStatic;
148 
150  QString description;
151  };
152 
157  QgsExpressionContextScope( const QString &name = QString() );
158 
163 
164  QgsExpressionContextScope &operator=( const QgsExpressionContextScope &other );
165 
167 
171  QString name() const { return mName; }
172 
180  void setVariable( const QString &name, const QVariant &value, bool isStatic = false );
181 
189  void addVariable( const QgsExpressionContextScope::StaticVariable &variable );
190 
197  bool removeVariable( const QString &name );
198 
206  bool hasVariable( const QString &name ) const;
207 
215  QVariant variable( const QString &name ) const;
216 
222  QStringList variableNames() const;
223 
230  QStringList filteredVariableNames() const;
231 
238  bool isReadOnly( const QString &name ) const;
239 
246  bool isStatic( const QString &name ) const;
247 
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 
300  bool hasFeature() const { return mHasFeature; }
301 
308  QgsFeature feature() const { return mFeature; }
309 
317  void setFeature( const QgsFeature &feature ) { mHasFeature = true; mFeature = feature; }
318 
325  void removeFeature() { mHasFeature = false; mFeature = QgsFeature(); }
326 
332  void setFields( const QgsFields &fields );
333 
339  void readXml( const QDomElement &element, const QgsReadWriteContext &context );
340 
346  bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
347 
348  private:
349  QString mName;
350  QHash<QString, StaticVariable> mVariables;
351  QHash<QString, QgsScopedExpressionFunction * > mFunctions;
352  bool mHasFeature = false;
353  QgsFeature mFeature;
354 
355  bool variableNameSort( const QString &a, const QString &b );
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 
721  static const QString EXPR_FIELDS;
723  static const QString EXPR_ORIGINAL_VALUE;
725  static const QString EXPR_SYMBOL_COLOR;
727  static const QString EXPR_SYMBOL_ANGLE;
729  static const QString EXPR_GEOMETRY_PART_COUNT;
731  static const QString EXPR_GEOMETRY_PART_NUM;
733  static const QString EXPR_GEOMETRY_POINT_COUNT;
735  static const QString EXPR_GEOMETRY_POINT_NUM;
737  static const QString EXPR_CLUSTER_SIZE;
739  static const QString EXPR_CLUSTER_COLOR;
740 
741  private:
742 
743  QList< QgsExpressionContextScope * > mStack;
744  QStringList mHighlightedVariables;
745  QStringList mHighlightedFunctions;
746 
747  // Cache is mutable because we want to be able to add cached values to const contexts
748  mutable QMap< QString, QVariant > mCachedValues;
749 
750 };
751 
752 #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").
The class is used as a container of context for various read/write operations on other objects...
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.
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:55
QList< QgsExpressionFunction::Parameter > ParameterList
List of parameters, used for function definition.
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:126
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...
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.
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:76
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.
virtual bool usesGeometry(const QgsExpressionNodeFunction *node) const
Does this function use a geometry object.
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.
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.