QGIS API Documentation  3.5.0-Master (e5a416e)
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 
439  void setHighlightedVariables( const QStringList &variableNames );
440 
449  bool isHighlightedFunction( const QString &name ) const;
450 
462  void setHighlightedFunctions( const QStringList &names );
463 
471  QgsExpressionContextScope *activeScopeForVariable( const QString &name );
472 
481  const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
482 
489  QgsExpressionContextScope *scope( int index );
490 
495  QgsExpressionContextScope *lastScope();
496 
501  QList< QgsExpressionContextScope * > scopes() { return mStack; }
502 
508  int indexOfScope( QgsExpressionContextScope *scope ) const;
509 
516  int indexOfScope( const QString &scopeName ) const;
517 
526  QStringList variableNames() const;
527 
534  QStringList filteredVariableNames() const;
535 
542  bool isReadOnly( const QString &name ) const;
543 
552  QString description( const QString &name ) const;
553 
560  bool hasFunction( const QString &name ) const;
561 
567  QStringList functionNames() const;
568 
577  QgsExpressionFunction *function( const QString &name ) const;
578 
582  int scopeCount() const;
583 
590  void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
591 
599  void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
600 
604  QgsExpressionContextScope *popScope();
605 
614  QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
615 
622 
630  void setFeature( const QgsFeature &feature );
631 
637  bool hasFeature() const;
638 
643  QgsFeature feature() const;
644 
652  void setFields( const QgsFields &fields );
653 
658  QgsFields fields() const;
659 
666  void setOriginalValueVariable( const QVariant &value );
667 
679  void setCachedValue( const QString &key, const QVariant &value ) const;
680 
689  bool hasCachedValue( const QString &key ) const;
690 
701  QVariant cachedValue( const QString &key ) const;
702 
710  void clearCachedValues() const;
711 
713  static const QString EXPR_FIELDS;
715  static const QString EXPR_ORIGINAL_VALUE;
717  static const QString EXPR_SYMBOL_COLOR;
719  static const QString EXPR_SYMBOL_ANGLE;
721  static const QString EXPR_GEOMETRY_PART_COUNT;
723  static const QString EXPR_GEOMETRY_PART_NUM;
725  static const QString EXPR_GEOMETRY_POINT_COUNT;
727  static const QString EXPR_GEOMETRY_POINT_NUM;
729  static const QString EXPR_CLUSTER_SIZE;
731  static const QString EXPR_CLUSTER_COLOR;
732 
733  private:
734 
735  QList< QgsExpressionContextScope * > mStack;
736  QStringList mHighlightedVariables;
737  QStringList mHighlightedFunctions;
738 
739  // Cache is mutable because we want to be able to add cached values to const contexts
740  mutable QMap< QString, QVariant > mCachedValues;
741 
742 };
743 
744 #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:119
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:69
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.