QGIS API Documentation  3.17.0-Master (7a14973234)
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 
369 class CORE_EXPORT QgsExpressionContext
370 {
371  public:
372 
374  QgsExpressionContext() = default;
375 
381  explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
382 
387 
388  QgsExpressionContext &operator=( const QgsExpressionContext &other ) SIP_SKIP;
389 
390  QgsExpressionContext &operator=( QgsExpressionContext &&other ) noexcept SIP_SKIP;
391 
393 
401  bool hasVariable( const QString &name ) const;
402 
412  QVariant variable( const QString &name ) const;
413 
419  QVariantMap variablesToMap() const;
420 
428  bool isHighlightedVariable( const QString &name ) const;
429 
436  QStringList highlightedVariables() const;
437 
445  void setHighlightedVariables( const QStringList &variableNames );
446 
455  bool isHighlightedFunction( const QString &name ) const;
456 
468  void setHighlightedFunctions( const QStringList &names );
469 
477  QgsExpressionContextScope *activeScopeForVariable( const QString &name );
478 
487  const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
488 
495  QgsExpressionContextScope *scope( int index );
496 
501  QgsExpressionContextScope *lastScope();
502 
507  QList< QgsExpressionContextScope * > scopes() { return mStack; }
508 
514  int indexOfScope( QgsExpressionContextScope *scope ) const;
515 
522  int indexOfScope( const QString &scopeName ) const;
523 
532  QStringList variableNames() const;
533 
540  QStringList filteredVariableNames() const;
541 
548  bool isReadOnly( const QString &name ) const;
549 
558  QString description( const QString &name ) const;
559 
566  bool hasFunction( const QString &name ) const;
567 
573  QStringList functionNames() const;
574 
583  QgsExpressionFunction *function( const QString &name ) const;
584 
588  int scopeCount() const;
589 
596  void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
597 
605  void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
606 
610  QgsExpressionContextScope *popScope();
611 
620  QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
621 
628 
636  void setFeature( const QgsFeature &feature );
637 
643  bool hasFeature() const;
644 
649  QgsFeature feature() const;
650 
658  void setFields( const QgsFields &fields );
659 
664  QgsFields fields() const;
665 
672  void setOriginalValueVariable( const QVariant &value );
673 
685  void setCachedValue( const QString &key, const QVariant &value ) const;
686 
695  bool hasCachedValue( const QString &key ) const;
696 
707  QVariant cachedValue( const QString &key ) const;
708 
716  void clearCachedValues() const;
717 
719  static const QString EXPR_FIELDS;
721  static const QString EXPR_ORIGINAL_VALUE;
723  static const QString EXPR_SYMBOL_COLOR;
725  static const QString EXPR_SYMBOL_ANGLE;
727  static const QString EXPR_GEOMETRY_PART_COUNT;
729  static const QString EXPR_GEOMETRY_PART_NUM;
731  static const QString EXPR_GEOMETRY_POINT_COUNT;
733  static const QString EXPR_GEOMETRY_POINT_NUM;
735  static const QString EXPR_CLUSTER_SIZE;
737  static const QString EXPR_CLUSTER_COLOR;
738 
739  private:
740 
741  QList< QgsExpressionContextScope * > mStack;
742  QStringList mHighlightedVariables;
743  QStringList mHighlightedFunctions;
744 
745  // Cache is mutable because we want to be able to add cached values to const contexts
746  mutable QMap< QString, QVariant > mCachedValues;
747 
748 };
749 
750 #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:44
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.