QGIS API Documentation 3.27.0-Master (0a97e3138f)
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>
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
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
147
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 bool hasGeometry() const { return mHasGeometry; }
335
342 QgsGeometry geometry() const { return mGeometry; }
343
352 void setGeometry( const QgsGeometry &geometry ) { mHasGeometry = true; mGeometry = geometry; }
353
360 void removeGeometry() { mHasGeometry = false; mGeometry = QgsGeometry(); }
361
367 void setFields( const QgsFields &fields );
368
374 void readXml( const QDomElement &element, const QgsReadWriteContext &context );
375
381 bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
382
383 private:
384 QString mName;
385 QHash<QString, StaticVariable> mVariables;
386 QHash<QString, QgsScopedExpressionFunction * > mFunctions;
387 bool mHasFeature = false;
388 QgsFeature mFeature;
389 bool mHasGeometry = false;
390 QgsGeometry mGeometry;
391};
392
406class CORE_EXPORT QgsExpressionContext
407{
408 public:
409
412
418 explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
419
424
425 QgsExpressionContext &operator=( const QgsExpressionContext &other ) SIP_SKIP;
426
427 QgsExpressionContext &operator=( QgsExpressionContext &&other ) noexcept SIP_SKIP;
428
430
438 bool hasVariable( const QString &name ) const;
439
449 QVariant variable( const QString &name ) const;
450
456 QVariantMap variablesToMap() const;
457
465 bool isHighlightedVariable( const QString &name ) const;
466
473 QStringList highlightedVariables() const;
474
482 void setHighlightedVariables( const QStringList &variableNames );
483
492 bool isHighlightedFunction( const QString &name ) const;
493
505 void setHighlightedFunctions( const QStringList &names );
506
514 QgsExpressionContextScope *activeScopeForVariable( const QString &name );
515
524 const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
525
532 QgsExpressionContextScope *scope( int index );
533
538 QgsExpressionContextScope *lastScope();
539
544 QList< QgsExpressionContextScope * > scopes() { return mStack; }
545
551 int indexOfScope( QgsExpressionContextScope *scope ) const;
552
559 int indexOfScope( const QString &scopeName ) const;
560
569 QStringList variableNames() const;
570
577 QStringList filteredVariableNames() const;
578
585 bool isReadOnly( const QString &name ) const;
586
595 QString description( const QString &name ) const;
596
603 bool hasFunction( const QString &name ) const;
604
610 QStringList functionNames() const;
611
620 QgsExpressionFunction *function( const QString &name ) const;
621
625 int scopeCount() const;
626
633 void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
634
642 void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
643
647 QgsExpressionContextScope *popScope();
648
657 QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
658
665
673 void setFeature( const QgsFeature &feature );
674
680 bool hasFeature() const;
681
686 QgsFeature feature() const;
687
696 void setGeometry( const QgsGeometry &geometry );
697
703 bool hasGeometry() const;
704
710 QgsGeometry geometry() const;
711
719 void setFields( const QgsFields &fields );
720
725 QgsFields fields() const;
726
733 void setOriginalValueVariable( const QVariant &value );
734
746 void setCachedValue( const QString &key, const QVariant &value ) const;
747
756 bool hasCachedValue( const QString &key ) const;
757
768 QVariant cachedValue( const QString &key ) const;
769
777 void clearCachedValues() const;
778
790 void setFeedback( QgsFeedback *feedback );
791
800 QgsFeedback *feedback() const;
801
803 static const QString EXPR_FIELDS;
805 static const QString EXPR_ORIGINAL_VALUE;
807 static const QString EXPR_SYMBOL_COLOR;
809 static const QString EXPR_SYMBOL_ANGLE;
811 static const QString EXPR_GEOMETRY_PART_COUNT;
813 static const QString EXPR_GEOMETRY_PART_NUM;
814
819 static const QString EXPR_GEOMETRY_RING_NUM;
821 static const QString EXPR_GEOMETRY_POINT_COUNT;
823 static const QString EXPR_GEOMETRY_POINT_NUM;
825 static const QString EXPR_CLUSTER_SIZE;
827 static const QString EXPR_CLUSTER_COLOR;
828
829 private:
830
831 QList< QgsExpressionContextScope * > mStack;
832 QStringList mHighlightedVariables;
833 QStringList mHighlightedFunctions;
834
835 QgsFeedback *mFeedback = nullptr;
836
837 // Cache is mutable because we want to be able to add cached values to const contexts
838 mutable QMap< QString, QVariant > mCachedValues;
839
840};
841
842#endif // QGSEXPRESSIONCONTEXT_H
Single scope for storing variables and functions for use within a QgsExpressionContext.
void removeGeometry()
Removes any geometry associated with the scope.
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.
QgsGeometry geometry() const
Sets the geometry associated with the scope.
QString name() const
Returns the friendly display name of the context scope.
int variableCount() const
Returns the count of variables contained within the scope.
bool hasGeometry() const
Returns true if the scope has a geometry associated with it.
void setGeometry(const QgsGeometry &geometry)
Convenience function for setting a geometry for 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.
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
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:125
The class is used as a container of context for various read/write operations on other objects.
Expression function for use within a QgsExpressionContextScope.
virtual QgsScopedExpressionFunction * clone() const =0
Returns a clone of the function.
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.
#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.