QGIS API Documentation  3.14.0-Pi (9f7028fd23)
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
QgsExpressionContext
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
Definition: qgsexpressioncontext.h:369
QgsExpressionContext::scopes
QList< QgsExpressionContextScope * > scopes()
Returns a list of scopes contained within the stack.
Definition: qgsexpressioncontext.h:507
QgsExpressionContextScope::setFeature
void setFeature(const QgsFeature &feature)
Convenience function for setting a feature for the scope.
Definition: qgsexpressioncontext.h:317
QgsExpressionContextScope::feature
QgsFeature feature() const
Sets the feature associated with the scope.
Definition: qgsexpressioncontext.h:308
QgsReadWriteContext
Definition: qgsreadwritecontext.h:34
QgsExpressionContextScope::StaticVariable::StaticVariable
StaticVariable(const QString &name=QString(), const QVariant &value=QVariant(), bool readOnly=false, bool isStatic=false, const QString &description=QString())
Constructor for StaticVariable.
Definition: qgsexpressioncontext.h:129
QgsScopedExpressionFunction::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.
Definition: qgsexpressioncontext.h:65
QgsExpressionContextScope::StaticVariable::readOnly
bool readOnly
True if variable should not be editable by users.
Definition: qgsexpressioncontext.h:144
QgsExpressionFunction::func
virtual QVariant func(const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node)=0
Returns result of evaluating the function.
QgsExpressionContextScope::StaticVariable::value
QVariant value
Variable value.
Definition: qgsexpressioncontext.h:141
QgsFields
Definition: qgsfields.h:44
QgsExpressionContextScope::StaticVariable::description
QString description
Translated description of variable, for use within expression builder widgets.
Definition: qgsexpressioncontext.h:150
qgsfeature.h
QgsExpressionContextScope::StaticVariable::name
QString name
Variable name.
Definition: qgsexpressioncontext.h:138
SIP_FACTORY
#define SIP_FACTORY
Definition: qgis_sip.h:76
QgsExpressionContextScope::StaticVariable::isStatic
bool isStatic
A static variable can be cached for the lifetime of a context.
Definition: qgsexpressioncontext.h:147
QgsExpressionFunction::referencedColumns
virtual QSet< QString > referencedColumns(const QgsExpressionNodeFunction *node) const
Returns a set of field names which are required for this function.
Definition: qgsexpressionfunction.cpp:133
SIP_SKIP
#define SIP_SKIP
Definition: qgis_sip.h:126
QgsExpressionFunction::ParameterList
QList< QgsExpressionFunction::Parameter > ParameterList
List of parameters, used for function definition.
Definition: qgsexpressionfunction.h:104
qgis_sip.h
SIP_TRANSFER
#define SIP_TRANSFER
Definition: qgis_sip.h:36
QgsExpressionContextScope::hasFeature
bool hasFeature() const
Returns true if the scope has a feature associated with it.
Definition: qgsexpressioncontext.h:300
qgsexpressionfunction.h
QgsExpressionNodeFunction
An expression node for expression functions.
Definition: qgsexpressionnodeimpl.h:316
QgsExpressionContextScope
Single scope for storing variables and functions for use within a QgsExpressionContext....
Definition: qgsexpressioncontext.h:111
QgsExpressionFunction::usesGeometry
virtual bool usesGeometry(const QgsExpressionNodeFunction *node) const
Does this function use a geometry object.
Definition: qgsexpressionfunction.cpp:106
QgsExpressionFunction
Definition: qgsexpressionfunction.h:40
QgsFeature
Definition: qgsfeature.h:55
QgsExpressionFunction::isStatic
virtual bool isStatic(const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context) const
Will be called during prepare to determine if the function is static.
Definition: qgsexpressionfunction.cpp:117
QgsScopedExpressionFunction::QgsScopedExpressionFunction
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.
Definition: qgsexpressioncontext.h:46
QgsExpressionContextScope::StaticVariable
Single variable definition for use within a QgsExpressionContextScope.
Definition: qgsexpressioncontext.h:118
QgsExpression
Definition: qgsexpression.h:113
QgsExpressionContextScope::removeFeature
void removeFeature()
Removes any feature associated with the scope.
Definition: qgsexpressioncontext.h:325
QgsScopedExpressionFunction
Expression function for use within a QgsExpressionContextScope. This differs from a standard QgsExpre...
Definition: qgsexpressioncontext.h:37
QgsExpressionContextScope::name
QString name() const
Returns the friendly display name of the context scope.
Definition: qgsexpressioncontext.h:171
QgsExpressionContextScope::variableCount
int variableCount() const
Returns the count of variables contained within the scope.
Definition: qgsexpressioncontext.h:259