QGIS API Documentation 3.29.0-Master (006c3c0232)
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
392 QStringList hiddenVariables() const;
393
404 void setHiddenVariables( const QStringList &hiddenVariables );
405
406
417 void addHiddenVariable( const QString &hiddenVariable );
418
428 void removeHiddenVariable( const QString &hiddenVariable );
429
430 private:
431 QString mName;
432 QHash<QString, StaticVariable> mVariables;
433 QHash<QString, QgsScopedExpressionFunction * > mFunctions;
434 bool mHasFeature = false;
435 QgsFeature mFeature;
436 bool mHasGeometry = false;
437 QgsGeometry mGeometry;
438 QStringList mHiddenVariables;
439};
440
454class CORE_EXPORT QgsExpressionContext
455{
456 public:
457
460
466 explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
467
472
473 QgsExpressionContext &operator=( const QgsExpressionContext &other ) SIP_SKIP;
474
475 QgsExpressionContext &operator=( QgsExpressionContext &&other ) noexcept SIP_SKIP;
476
478
486 bool hasVariable( const QString &name ) const;
487
497 QVariant variable( const QString &name ) const;
498
504 QVariantMap variablesToMap() const;
505
513 bool isHighlightedVariable( const QString &name ) const;
514
521 QStringList highlightedVariables() const;
522
530 void setHighlightedVariables( const QStringList &variableNames );
531
540 bool isHighlightedFunction( const QString &name ) const;
541
553 void setHighlightedFunctions( const QStringList &names );
554
562 QgsExpressionContextScope *activeScopeForVariable( const QString &name );
563
572 const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
573
580 QgsExpressionContextScope *scope( int index );
581
586 QgsExpressionContextScope *lastScope();
587
592 QList< QgsExpressionContextScope * > scopes() { return mStack; }
593
599 int indexOfScope( QgsExpressionContextScope *scope ) const;
600
607 int indexOfScope( const QString &scopeName ) const;
608
617 QStringList variableNames() const;
618
625 QStringList filteredVariableNames() const;
626
633 bool isReadOnly( const QString &name ) const;
634
643 QString description( const QString &name ) const;
644
651 bool hasFunction( const QString &name ) const;
652
658 QStringList functionNames() const;
659
668 QgsExpressionFunction *function( const QString &name ) const;
669
673 int scopeCount() const;
674
681 void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
682
690 void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
691
695 QgsExpressionContextScope *popScope();
696
705 QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
706
713
721 void setFeature( const QgsFeature &feature );
722
728 bool hasFeature() const;
729
734 QgsFeature feature() const;
735
744 void setGeometry( const QgsGeometry &geometry );
745
751 bool hasGeometry() const;
752
758 QgsGeometry geometry() const;
759
767 void setFields( const QgsFields &fields );
768
773 QgsFields fields() const;
774
781 void setOriginalValueVariable( const QVariant &value );
782
794 void setCachedValue( const QString &key, const QVariant &value ) const;
795
804 bool hasCachedValue( const QString &key ) const;
805
816 QVariant cachedValue( const QString &key ) const;
817
825 void clearCachedValues() const;
826
838 void setFeedback( QgsFeedback *feedback );
839
848 QgsFeedback *feedback() const;
849
851 static const QString EXPR_FIELDS;
853 static const QString EXPR_ORIGINAL_VALUE;
855 static const QString EXPR_SYMBOL_COLOR;
857 static const QString EXPR_SYMBOL_ANGLE;
859 static const QString EXPR_GEOMETRY_PART_COUNT;
861 static const QString EXPR_GEOMETRY_PART_NUM;
862
867 static const QString EXPR_GEOMETRY_RING_NUM;
869 static const QString EXPR_GEOMETRY_POINT_COUNT;
871 static const QString EXPR_GEOMETRY_POINT_NUM;
873 static const QString EXPR_CLUSTER_SIZE;
875 static const QString EXPR_CLUSTER_COLOR;
876
877 private:
878
879 QList< QgsExpressionContextScope * > mStack;
880 QStringList mHighlightedVariables;
881 QStringList mHighlightedFunctions;
882
883 QgsFeedback *mFeedback = nullptr;
884
885 // Cache is mutable because we want to be able to add cached values to const contexts
886 mutable QMap< QString, QVariant > mCachedValues;
887
888};
889
890#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:164
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.