QGIS API Documentation 4.3.0-Master (91d4a333d5d)
Loading...
Searching...
No Matches
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"
21#include "qgsfeature.h"
22
23#include <QHash>
24#include <QPointer>
25#include <QSet>
26#include <QString>
27#include <QStringList>
28#include <QVariant>
29
32class LoadLayerFunction;
33
42
44{
45 public:
51 const QString &fnname,
52 int params,
53 const QString &group,
54 const QString &helpText = QString(),
55 bool usesGeometry = false,
56 const QSet<QString> &referencedColumns = QSet<QString>(),
57 bool lazyEval = false,
58 bool handlesNull = false,
59 bool isContextual = true
60 )
62 , mUsesGeometry( usesGeometry )
63 , mReferencedColumns( referencedColumns )
64 {}
65
71 const QString &fnname,
73 const QString &group,
74 const QString &helpText = QString(),
75 bool usesGeometry = false,
76 const QSet<QString> &referencedColumns = QSet<QString>(),
77 bool lazyEval = false,
78 bool handlesNull = false,
79 bool isContextual = true
80 )
82 , mUsesGeometry( usesGeometry )
83 , mReferencedColumns( referencedColumns )
84 {}
85
86 QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override = 0;
87
92
93 bool usesGeometry( const QgsExpressionNodeFunction *node ) const override;
94
95 QSet<QString> referencedColumns( const QgsExpressionNodeFunction *node ) const override;
96
97 bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
98
99 private:
100 bool mUsesGeometry;
101 QSet<QString> mReferencedColumns;
102};
103
104
117
119{
120 public:
125 {
134 StaticVariable( const QString &name = QString(), const QVariant &value = QVariant(), bool readOnly = false, bool isStatic = false, const QString &description = QString() )
135 : name( name )
136 , value( value )
137 , readOnly( readOnly )
138 , isStatic( isStatic )
140 {}
141
143 QString name;
144
146 QVariant value;
147
150
153
155 QString description;
156 };
157
162 QgsExpressionContextScope( const QString &name = QString() );
163
166
169
171
175 QString name() const { return mName; }
176
184 void setVariable( const QString &name, const QVariant &value, bool isStatic = false );
185
193 void addVariable( const QgsExpressionContextScope::StaticVariable &variable );
194
201 bool removeVariable( const QString &name );
202
210 bool hasVariable( const QString &name ) const;
211
219 QVariant variable( const QString &name ) const;
220
226 QStringList variableNames() const;
227
234 QStringList filteredVariableNames() const;
235
242 bool isReadOnly( const QString &name ) const;
243
249 bool isStatic( const QString &name ) const;
250
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
301 bool hasFeature() const { return mHasFeature; }
302
308 QgsFeature feature() const { return mFeature; }
309
318 {
319 mHasFeature = true;
320 mFeature = feature;
321 }
322
329 {
330 mHasFeature = false;
331 mFeature = QgsFeature();
332 }
333
339 bool hasGeometry() const { return mHasGeometry; }
340
347 QgsGeometry geometry() const { return mGeometry; }
348
358 {
359 mHasGeometry = true;
360 mGeometry = geometry;
361 }
362
370 {
371 mHasGeometry = false;
372 mGeometry = QgsGeometry();
373 }
374
380 void setFields( const QgsFields &fields );
381
387 void readXml( const QDomElement &element, const QgsReadWriteContext &context );
388
394 bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
395
396
405 QStringList hiddenVariables() const;
406
417 void setHiddenVariables( const QStringList &hiddenVariables );
418
419
430 void addHiddenVariable( const QString &hiddenVariable );
431
441 void removeHiddenVariable( const QString &hiddenVariable );
442
453 void addLayerStore( QgsMapLayerStore *store );
454
461 QList< QgsMapLayerStore * > layerStores() const;
462
463 private:
464 QString mName;
465 QHash<QString, StaticVariable> mVariables;
466 QHash<QString, QgsScopedExpressionFunction * > mFunctions;
467 bool mHasFeature = false;
468 QgsFeature mFeature;
469 bool mHasGeometry = false;
470 QgsGeometry mGeometry;
471 QStringList mHiddenVariables;
472
473 QList< QPointer< QgsMapLayerStore > > mLayerStores;
474};
475
490class CORE_EXPORT QgsExpressionContext
491{
492 public:
494
499 explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
500
507 explicit QgsExpressionContext( std::vector<std::unique_ptr<QgsExpressionContextScope>> scopes ) SIP_SKIP;
508
515 explicit QgsExpressionContext( std::unique_ptr<QgsExpressionContextScope> scope ) SIP_SKIP;
516
519
521
523
525
533 bool hasVariable( const QString &name ) const;
534
544 QVariant variable( const QString &name ) const;
545
550 QVariantMap variablesToMap() const;
551
559 bool isHighlightedVariable( const QString &name ) const;
560
567 QStringList highlightedVariables() const;
568
576 void setHighlightedVariables( const QStringList &variableNames );
577
586 bool isHighlightedFunction( const QString &name ) const;
587
599 void setHighlightedFunctions( const QStringList &names );
600
609
618 const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
619
626 QgsExpressionContextScope *scope( int index );
627
633
638 QList< QgsExpressionContextScope * > scopes() { return mStack; }
639
645 int indexOfScope( QgsExpressionContextScope *scope ) const;
646
652 int indexOfScope( const QString &scopeName ) const;
653
662 QStringList variableNames() const;
663
670 QStringList filteredVariableNames() const;
671
678 bool isReadOnly( const QString &name ) const;
679
687 QString description( const QString &name ) const;
688
695 bool hasFunction( const QString &name ) const;
696
702 QStringList functionNames() const;
703
712 QgsExpressionFunction *function( const QString &name ) const;
713
717 int scopeCount() const;
718
725 void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
726
735 void appendScope( std::unique_ptr<QgsExpressionContextScope> scope ) SIP_SKIP;
736
743 void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
744
753 void appendScopes( std::vector<std::unique_ptr<QgsExpressionContextScope>> scopes ) SIP_SKIP;
754
758 QgsExpressionContextScope *popScope();
759
767 QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
768
775
783 QgsExpressionContext &operator<<( std::unique_ptr<QgsExpressionContextScope> scope ) SIP_SKIP;
784
792 void setFeature( const QgsFeature &feature );
793
798 bool hasFeature() const;
799
804 QgsFeature feature() const;
805
814 void setGeometry( const QgsGeometry &geometry );
815
821 bool hasGeometry() const;
822
828 QgsGeometry geometry() const;
829
837 void setFields( const QgsFields &fields );
838
843 QgsFields fields() const;
844
850 void setOriginalValueVariable( const QVariant &value );
851
862 void setCachedValue( const QString &key, const QVariant &value ) const;
863
871 bool hasCachedValue( const QString &key ) const;
872
882 QVariant cachedValue( const QString &key ) const;
883
890 void clearCachedValues() const;
891
897 QList< QgsMapLayerStore * > layerStores() const;
898
910 void setLoadedLayerStore( QgsMapLayerStore *store );
911
919 QgsMapLayerStore *loadedLayerStore() const;
920
932 void setFeedback( QgsFeedback *feedback );
933
942 QgsFeedback *feedback() const;
943
954 QString uniqueHash( bool &ok SIP_OUT, const QSet<QString> &variables = QSet<QString>() ) const;
955
957 static const QString EXPR_FIELDS;
959 static const QString EXPR_ORIGINAL_VALUE;
961 static const QString EXPR_SYMBOL_COLOR;
963 static const QString EXPR_SYMBOL_ANGLE;
965 static const QString EXPR_GEOMETRY_PART_COUNT;
967 static const QString EXPR_GEOMETRY_PART_NUM;
968
973 static const QString EXPR_GEOMETRY_RING_NUM;
975 static const QString EXPR_GEOMETRY_POINT_COUNT;
977 static const QString EXPR_GEOMETRY_POINT_NUM;
979 static const QString EXPR_CLUSTER_SIZE;
981 static const QString EXPR_CLUSTER_COLOR;
982
983 private:
984 QList< QgsExpressionContextScope * > mStack;
985 QStringList mHighlightedVariables;
986 QStringList mHighlightedFunctions;
987
988 QgsFeedback *mFeedback = nullptr;
989
990 std::unique_ptr< LoadLayerFunction > mLoadLayerFunction;
991 QPointer< QgsMapLayerStore > mDestinationStore;
992
993 // Cache is mutable because we want to be able to add cached values to const contexts
994 mutable QMap< QString, QVariant > mCachedValues;
995};
996
997#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.
QgsExpressionContextScope & operator=(const QgsExpressionContextScope &other)
QgsExpressionContextScope(const QString &name=QString())
Constructor for QgsExpressionContextScope.
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
static const QString EXPR_GEOMETRY_PART_COUNT
Inbuilt variable name for geometry part count variable.
static const QString EXPR_GEOMETRY_POINT_COUNT
Inbuilt variable name for point count variable.
QStringList highlightedVariables() const
Returns the current list of variables highlighted within the context.
static const QString EXPR_CLUSTER_SIZE
Inbuilt variable name for cluster size variable.
static const QString EXPR_GEOMETRY_POINT_NUM
Inbuilt variable name for point number variable.
void setHighlightedFunctions(const QStringList &names)
Sets the list of function names intended to be highlighted to the user.
bool isHighlightedFunction(const QString &name) const
Returns true if the specified function name is intended to be highlighted to the user.
QgsExpressionContext & operator=(const QgsExpressionContext &other)
static const QString EXPR_FIELDS
Inbuilt variable name for fields storage.
static const QString EXPR_GEOMETRY_RING_NUM
Inbuilt variable name for geometry ring number variable.
bool isHighlightedVariable(const QString &name) const
Returns true if the specified variable name is intended to be highlighted to the user.
QgsExpressionContextScope * activeScopeForVariable(const QString &name)
Returns the currently active scope from the context for a specified variable name.
static const QString EXPR_GEOMETRY_PART_NUM
Inbuilt variable name for geometry part number variable.
static const QString EXPR_SYMBOL_COLOR
Inbuilt variable name for symbol color variable.
QgsExpressionContextScope * lastScope()
Returns the last scope added to the context.
QList< QgsExpressionContextScope * > scopes()
Returns a list of scopes contained within the stack.
bool hasVariable(const QString &name) const
Check whether a variable is specified by any scope within the context.
void setHighlightedVariables(const QStringList &variableNames)
Sets the list of variable names within the context intended to be highlighted to the user.
static const QString EXPR_SYMBOL_ANGLE
Inbuilt variable name for symbol angle variable.
QVariantMap variablesToMap() const
Returns a map of variable name to value representing all the expression variables contained by the co...
static const QString EXPR_ORIGINAL_VALUE
Inbuilt variable name for value original value variable.
static const QString EXPR_CLUSTER_COLOR
Inbuilt variable name for cluster color variable.
QStringList variableNames() const
Returns a list of variables names set by all scopes in the context.
QVariant variable(const QString &name) const
Fetches a matching variable from the context.
QgsExpressionContextScope * scope(int index)
Returns the scope at the specified index within the context.
An abstract base class for defining QgsExpression functions.
QList< QgsExpressionFunction::Parameter > ParameterList
List of parameters, used for function definition.
bool isContextual() const
Returns whether the function is only available if provided by a QgsExpressionContext object.
int params() const
The number of parameters this function takes.
QgsExpressionFunction(const QString &fnname, int params, const QString &group, const QString &helpText=QString(), bool lazyEval=false, bool handlesNull=false, bool isContextual=false)
Constructor for function which uses unnamed 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.
bool lazyEval() const
true if this function should use lazy evaluation.
QString group() const
Returns the first group which the function belongs to.
virtual QSet< QString > referencedColumns(const QgsExpressionNodeFunction *node) const
Returns a set of field names which are required for this function.
virtual bool handlesNull() const
Returns true if the function handles NULL values in arguments by itself, and the default NULL value h...
const QString helpText() const
The help text for the function.
virtual bool usesGeometry(const QgsExpressionNodeFunction *node) const
Does this function use a geometry object.
An expression node for expression functions.
Handles 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:60
Base class for feedback objects to be used for cancellation of something running in a worker thread.
Definition qgsfeedback.h:44
Container of fields for a vector layer.
Definition qgsfields.h:45
A geometry is the spatial representation of a feature.
A storage object for map layers, in which the layers are owned by the store and have their lifetime b...
A container for the context for various read/write operations on objects.
Expression function for use within a QgsExpressionContextScope.
QSet< QString > referencedColumns(const QgsExpressionNodeFunction *node) const override
Returns a set of field names which are required for this function.
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.
bool usesGeometry(const QgsExpressionNodeFunction *node) const override
Does this function use a geometry object.
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:138
#define SIP_TRANSFER
Definition qgis_sip.h:35
#define SIP_OUT
Definition qgis_sip.h:57
#define SIP_FACTORY
Definition qgis_sip.h:83
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.