QGIS API Documentation  2.18.21-Las Palmas (9fba24a)
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 <QVariant>
19 #include <QHash>
20 #include <QString>
21 #include <QStringList>
22 #include <QSet>
23 #include "qgsexpression.h"
24 
25 class QgsExpression;
26 class QgsMapLayer;
27 class QgsComposition;
28 class QgsComposerItem;
30 class QgsMapSettings;
31 class QgsSymbolV2;
32 
42 {
43  public:
45  int params,
46  const QString& group,
47  const QString& helpText = QString(),
48  bool usesGeometry = false,
49  const QStringList& referencedColumns = QStringList(),
50  bool lazyEval = false,
51  bool handlesNull = false,
52  bool isContextual = true )
53  : QgsExpression::Function( fnname, params, group, helpText, usesGeometry, referencedColumns, lazyEval, handlesNull, isContextual )
54  {}
55 
57 
58  virtual QVariant func( const QVariantList& values, const QgsExpressionContext* context, QgsExpression* parent ) override = 0;
59 
62  virtual QgsScopedExpressionFunction* clone() const = 0;
63 
64 };
65 
66 
79 class CORE_EXPORT QgsExpressionContextScope
80 {
81  public:
82 
86  {
92  StaticVariable( const QString& name = QString(), const QVariant& value = QVariant(), bool readOnly = false )
93  : name( name )
94  , value( value )
95  , readOnly( readOnly )
96  {}
97 
100 
103 
105  bool readOnly;
106  };
107 
111  QgsExpressionContextScope( const QString& name = QString() );
112 
116 
117  QgsExpressionContextScope& operator=( const QgsExpressionContextScope& other );
118 
120 
123  QString name() const { return mName; }
124 
131  void setVariable( const QString& name, const QVariant& value );
132 
139  void addVariable( const QgsExpressionContextScope::StaticVariable& variable );
140 
146  bool removeVariable( const QString& name );
147 
154  bool hasVariable( const QString& name ) const;
155 
162  QVariant variable( const QString& name ) const;
163 
168  QStringList variableNames() const;
169 
175  QStringList filteredVariableNames() const;
176 
182  bool isReadOnly( const QString& name ) const;
183 
186  int variableCount() const { return mVariables.count(); }
187 
194  bool hasFunction( const QString &name ) const;
195 
203  QgsExpression::Function* function( const QString &name ) const;
204 
209  QStringList functionNames() const;
210 
216  void addFunction( const QString& name, QgsScopedExpressionFunction* function );
217 
222  void setFeature( const QgsFeature& feature );
223 
228  void setFields( const QgsFields& fields );
229 
230  private:
231  QString mName;
234 
235  bool variableNameSort( const QString &a, const QString &b );
236 };
237 
250 class CORE_EXPORT QgsExpressionContext
251 {
252  public:
253 
255 
259 
260  QgsExpressionContext& operator=( const QgsExpressionContext& other );
261 
263 
270  bool hasVariable( const QString& name ) const;
271 
280  QVariant variable( const QString& name ) const;
281 
288  bool isHighlightedVariable( const QString& name ) const;
289 
295  void setHighlightedVariables( const QStringList& variableNames );
296 
303  QgsExpressionContextScope* activeScopeForVariable( const QString& name );
304 
312  const QgsExpressionContextScope* activeScopeForVariable( const QString& name ) const;
313 
319  QgsExpressionContextScope* scope( int index );
320 
324  QgsExpressionContextScope* lastScope();
325 
330 
335  int indexOfScope( QgsExpressionContextScope* scope ) const;
336 
342  int indexOfScope( const QString& scopeName ) const;
343 
351  QStringList variableNames() const;
352 
358  QStringList filteredVariableNames() const;
359 
365  bool isReadOnly( const QString& name ) const;
366 
372  bool hasFunction( const QString& name ) const;
373 
378  QStringList functionNames() const;
379 
387  QgsExpression::Function* function( const QString& name ) const;
388 
391  int scopeCount() const;
392 
398  void appendScope( QgsExpressionContextScope* scope );
399 
403  QgsExpressionContextScope* popScope();
404 
410 
417  void setFeature( const QgsFeature& feature );
418 
422  QgsFeature feature() const;
423 
430  void setFields( const QgsFields& fields );
431 
435  QgsFields fields() const;
436 
442  void setOriginalValueVariable( const QVariant& value );
443 
454  void setCachedValue( const QString& key, const QVariant& value ) const;
455 
463  bool hasCachedValue( const QString& key ) const;
464 
474  QVariant cachedValue( const QString& key ) const;
475 
482  void clearCachedValues() const;
483 
485  static const QString EXPR_FIELDS;
487  static const QString EXPR_FEATURE;
502 
503  private:
504 
506  QStringList mHighlightedVariables;
507 
508  // Cache is mutable because we want to be able to add cached values to const contexts
509  mutable QMap< QString, QVariant > mCachedValues;
510 
511 };
512 
520 class CORE_EXPORT QgsExpressionContextUtils
521 {
522  public:
523 
528  static QgsExpressionContextScope* globalScope();
529 
537  static void setGlobalVariable( const QString& name, const QVariant& value );
538 
545  static void setGlobalVariables( const QgsStringMap& variables );
546 
551  static QgsExpressionContextScope* projectScope();
552 
560  static void setProjectVariable( const QString& name, const QVariant& value );
561 
568  static void setProjectVariables( const QgsStringMap& variables );
569 
573  static QgsExpressionContextScope* layerScope( const QgsMapLayer *layer );
574 
583  static void setLayerVariable( QgsMapLayer* layer, const QString& name, const QVariant& value );
584 
592  static void setLayerVariables( QgsMapLayer* layer, const QgsStringMap& variables );
593 
597  static QgsExpressionContextScope* mapSettingsScope( const QgsMapSettings &mapSettings );
598 
605  static QgsExpressionContextScope* updateSymbolScope( const QgsSymbolV2* symbol, QgsExpressionContextScope* symbolScope = nullptr );
606 
611  static QgsExpressionContextScope* compositionScope( const QgsComposition *composition );
612 
621  static void setCompositionVariable( QgsComposition* composition, const QString& name, const QVariant& value );
622 
630  static void setCompositionVariables( QgsComposition* composition, const QgsStringMap& variables );
631 
636  static QgsExpressionContextScope* atlasScope( const QgsAtlasComposition* atlas );
637 
642  static QgsExpressionContextScope* composerItemScope( const QgsComposerItem *composerItem );
643 
652  static void setComposerItemVariable( QgsComposerItem* composerItem, const QString& name, const QVariant& value );
653 
661  static void setComposerItemVariables( QgsComposerItem* composerItem, const QgsStringMap& variables );
662 
667  static QgsExpressionContext createFeatureBasedContext( const QgsFeature& feature, const QgsFields& fields );
668 
671  static void registerContextFunctions();
672 
673 };
674 
675 #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").
Single variable definition for use within a QgsExpressionContextScope.
static unsigned index
Base class for all map layer types.
Definition: qgsmaplayer.h:49
static const QString EXPR_GEOMETRY_POINT_COUNT
Inbuilt variable name for point count variable.
A abstract base class for defining QgsExpression functions.
QList< QgsExpressionContextScope *> scopes()
Returns a list of scopes contained within the stack.
A item that forms part of a map composition.
QgsScopedExpressionFunction(const QString &fnname, int params, const QString &group, const QString &helpText=QString(), bool usesGeometry=false, const QStringList &referencedColumns=QStringList(), bool lazyEval=false, bool handlesNull=false, bool isContextual=true)
Container of fields for a vector layer.
Definition: qgsfield.h:252
The feature class encapsulates a single feature including its id, geometry and a list of field/values...
Definition: qgsfeature.h:187
The QgsMapSettings class contains configuration for rendering of the map.
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.
virtual Q_DECL_DEPRECATED QVariant func(const QVariantList &, const QgsFeature *, QgsExpression *)
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.
static const QString EXPR_SYMBOL_COLOR
Inbuilt variable name for symbol color variable.
std::ostream & operator<<(std::ostream &os, const QgsCoordinateReferenceSystem &r)
Output stream operator.
static const QString EXPR_FIELDS
Inbuilt variable name for fields storage.
Single scope for storing variables and functions for use within a QgsExpressionContext.
Graphics scene for map printing.
Contains utilities for working with QgsExpressionContext objects, including methods for creating scop...
static const QString EXPR_FEATURE
Inbuilt variable name for feature storage.
StaticVariable(const QString &name=QString(), const QVariant &value=QVariant(), bool readOnly=false)
Constructor for StaticVariable.
static const QString EXPR_GEOMETRY_POINT_NUM
Inbuilt variable name for point number variable.
Class used to render an Atlas, iterating over geometry features.
QString name() const
Returns the friendly display name of the context scope.
static const QString EXPR_GEOMETRY_PART_NUM
Inbuilt variable name for geometry part number variable.
static const QString EXPR_GEOMETRY_PART_COUNT
Inbuilt variable name for geometry part count variable.
Expression function for use within a QgsExpressionContextScope.