Branch data Line data Source code
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 : :
28 : : /**
29 : : * \ingroup core
30 : : * \class QgsScopedExpressionFunction
31 : : * \brief Expression function for use within a QgsExpressionContextScope. This differs from a
32 : : * standard QgsExpression::Function in that it requires an implemented
33 : : * clone() method.
34 : : * \since QGIS 2.12
35 : : */
36 : :
37 : 2 : class CORE_EXPORT QgsScopedExpressionFunction : public QgsExpressionFunction
38 : : {
39 : : public:
40 : :
41 : : /**
42 : : * Create a new QgsScopedExpressionFunction
43 : : *
44 : : * \since QGIS 2.12
45 : : */
46 : 2 : 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 : 2 : : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
56 : 2 : , mUsesGeometry( usesGeometry )
57 : 2 : , mReferencedColumns( referencedColumns )
58 : 4 : {}
59 : :
60 : : /**
61 : : * Create a new QgsScopedExpressionFunction using named parameters.
62 : : *
63 : : * \since QGIS 3.0
64 : : */
65 : 0 : QgsScopedExpressionFunction( const QString &fnname,
66 : : const QgsExpressionFunction::ParameterList ¶ms,
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 : 0 : : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, isContextual )
75 : 0 : , mUsesGeometry( usesGeometry )
76 : 0 : , mReferencedColumns( referencedColumns )
77 : 0 : {}
78 : :
79 : : QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override = 0;
80 : :
81 : : /**
82 : : * Returns a clone of the function.
83 : : */
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 : :
98 : : /**
99 : : * \ingroup core
100 : : * \class QgsExpressionContextScope
101 : : * \brief Single scope for storing variables and functions for use within a QgsExpressionContext.
102 : : * Examples include a project's scope, which could contain information about the current project such as
103 : : * the project file's location. QgsExpressionContextScope can encapsulate both variables (static values)
104 : : * and functions(which are calculated only when an expression is evaluated).
105 : : *
106 : : * See QgsExpressionContextUtils for helper methods for working with QgsExpressionContextScope objects.
107 : : *
108 : : * \since QGIS 2.12
109 : : */
110 : :
111 : : class CORE_EXPORT QgsExpressionContextScope
112 : : {
113 : : public:
114 : :
115 : : /**
116 : : * Single variable definition for use within a QgsExpressionContextScope.
117 : : */
118 : 3810 : struct StaticVariable
119 : : {
120 : :
121 : : /**
122 : : * Constructor for StaticVariable.
123 : : * \param name variable name (should be unique within the QgsExpressionContextScope)
124 : : * \param value initial variable value
125 : : * \param readOnly TRUE if variable should not be editable by users
126 : : * \param isStatic TRUE if the variable will not change during the lifteime of an iterator.
127 : : * \param description optional translated description of variable, for use in expression builder widgets
128 : : */
129 : 1260 : StaticVariable( const QString &name = QString(), const QVariant &value = QVariant(), bool readOnly = false, bool isStatic = false, const QString &description = QString() )
130 : 1260 : : name( name )
131 : 1260 : , value( value )
132 : 1260 : , readOnly( readOnly )
133 : 1260 : , isStatic( isStatic )
134 : 1260 : , description( description )
135 : 1260 : {}
136 : :
137 : : //! Variable name
138 : : QString name;
139 : :
140 : : //! Variable value
141 : : QVariant value;
142 : :
143 : : //! True if variable should not be editable by users
144 : : bool readOnly;
145 : :
146 : : //! A static variable can be cached for the lifetime of a context
147 : : bool isStatic;
148 : :
149 : : //! Translated description of variable, for use within expression builder widgets.
150 : : QString description;
151 : : };
152 : :
153 : : /**
154 : : * Constructor for QgsExpressionContextScope
155 : : * \param name friendly display name for the context scope
156 : : */
157 : : QgsExpressionContextScope( const QString &name = QString() );
158 : :
159 : : /**
160 : : * Copy constructor
161 : : */
162 : : QgsExpressionContextScope( const QgsExpressionContextScope &other );
163 : :
164 : : QgsExpressionContextScope &operator=( const QgsExpressionContextScope &other );
165 : :
166 : : ~QgsExpressionContextScope();
167 : :
168 : : /**
169 : : * Returns the friendly display name of the context scope.
170 : : */
171 : 0 : QString name() const { return mName; }
172 : :
173 : : /**
174 : : * Convenience method for setting a variable in the context scope by \a name name and \a value. If a variable
175 : : * with the same name is already set then its value is overwritten, otherwise a new variable is added to the scope.
176 : : * If the \a isStatic parameter is set to TRUE, this variable can be cached during the execution
177 : : * of QgsExpression::prepare().
178 : : * \see addVariable()
179 : : */
180 : : void setVariable( const QString &name, const QVariant &value, bool isStatic = false );
181 : :
182 : : /**
183 : : * Adds a variable into the context scope. If a variable with the same name is already set then its
184 : : * value is overwritten, otherwise a new variable is added to the scope.
185 : : * \param variable definition of variable to insert
186 : : * \see setVariable()
187 : : * \see addFunction()
188 : : */
189 : : void addVariable( const QgsExpressionContextScope::StaticVariable &variable );
190 : :
191 : : /**
192 : : * Removes a variable from the context scope, if found.
193 : : * \param name name of variable to remove
194 : : * \returns TRUE if variable was removed from the scope, FALSE if matching variable was not
195 : : * found within the scope
196 : : */
197 : : bool removeVariable( const QString &name );
198 : :
199 : : /**
200 : : * Tests whether a variable with the specified name exists in the scope.
201 : : * \param name variable name
202 : : * \returns TRUE if matching variable was found in the scope
203 : : * \see variable()
204 : : * \see hasFunction()
205 : : */
206 : : bool hasVariable( const QString &name ) const;
207 : :
208 : : /**
209 : : * Retrieves a variable's value from the scope.
210 : : * \param name variable name
211 : : * \returns variable value, or invalid QVariant if matching variable could not be found
212 : : * \see hasVariable()
213 : : * \see function()
214 : : */
215 : : QVariant variable( const QString &name ) const;
216 : :
217 : : /**
218 : : * Returns a list of variable names contained within the scope.
219 : : * \see functionNames()
220 : : * \see filteredVariableNames()
221 : : */
222 : : QStringList variableNames() const;
223 : :
224 : : /**
225 : : * Returns a filtered and sorted list of variable names contained within the scope.
226 : : * Hidden variable names will be excluded, and the list will be sorted so that
227 : : * read only variables are listed first.
228 : : * \see variableNames()
229 : : */
230 : : QStringList filteredVariableNames() const;
231 : :
232 : : /**
233 : : * Tests whether the specified variable is read only and should not be editable
234 : : * by users.
235 : : * \param name variable name
236 : : * \returns TRUE if variable is read only
237 : : */
238 : : bool isReadOnly( const QString &name ) const;
239 : :
240 : : /**
241 : : * Tests whether the variable with the specified \a name is static and can
242 : : * be cached.
243 : : *
244 : : * \since QGIS 3.0
245 : : */
246 : : bool isStatic( const QString &name ) const;
247 : :
248 : : /**
249 : : * Returns the translated description for the variable with the specified \a name
250 : : * (if set).
251 : : *
252 : : * \since QGIS 3.0
253 : : */
254 : : QString description( const QString &name ) const;
255 : :
256 : : /**
257 : : * Returns the count of variables contained within the scope.
258 : : */
259 : : int variableCount() const { return mVariables.count(); }
260 : :
261 : : /**
262 : : * Tests whether a function with the specified name exists in the scope.
263 : : * \param name function name
264 : : * \returns TRUE if matching function was found in the scope
265 : : * \see function()
266 : : * \see hasFunction()
267 : : */
268 : : bool hasFunction( const QString &name ) const;
269 : :
270 : : /**
271 : : * Retrieves a function from the scope.
272 : : * \param name function name
273 : : * \returns function, or NULLPTR if matching function could not be found
274 : : * \see hasFunction()
275 : : * \see functionNames()
276 : : * \see variable()
277 : : */
278 : : QgsExpressionFunction *function( const QString &name ) const;
279 : :
280 : : /**
281 : : * Retrieves a list of names of functions contained in the scope.
282 : : * \see function()
283 : : * \see variableNames()
284 : : */
285 : : QStringList functionNames() const;
286 : :
287 : : /**
288 : : * Adds a function to the scope.
289 : : * \param name function name
290 : : * \param function function to insert. Ownership is transferred to the scope.
291 : : * \see addVariable()
292 : : */
293 : : void addFunction( const QString &name, QgsScopedExpressionFunction *function SIP_TRANSFER );
294 : :
295 : : /**
296 : : * Returns TRUE if the scope has a feature associated with it.
297 : : * \see feature()
298 : : * \since QGIS 3.0
299 : : */
300 : 0 : bool hasFeature() const { return mHasFeature; }
301 : :
302 : : /**
303 : : * Sets the feature associated with the scope.
304 : : * \see setFeature()
305 : : * \see hasFeature()
306 : : * \since QGIS 3.0
307 : : */
308 : 0 : QgsFeature feature() const { return mFeature; }
309 : :
310 : : /**
311 : : * Convenience function for setting a feature for the scope. Any existing
312 : : * feature set by the scope will be overwritten.
313 : : * \param feature feature for scope
314 : : * \see removeFeature()
315 : : * \see feature()
316 : : */
317 : 0 : void setFeature( const QgsFeature &feature ) { mHasFeature = true; mFeature = feature; }
318 : :
319 : : /**
320 : : * Removes any feature associated with the scope.
321 : : * \see setFeature()
322 : : * \see hasFeature()
323 : : * \since QGIS 3.0
324 : : */
325 : : void removeFeature() { mHasFeature = false; mFeature = QgsFeature(); }
326 : :
327 : : /**
328 : : * Convenience function for setting a fields for the scope. Any existing
329 : : * fields set by the scope will be overwritten.
330 : : * \param fields fields for scope
331 : : */
332 : : void setFields( const QgsFields &fields );
333 : :
334 : : /**
335 : : * Reads scope variables from an XML element.
336 : : * \see writeXml()
337 : : * \since QGIS 3.6
338 : : */
339 : : void readXml( const QDomElement &element, const QgsReadWriteContext &context );
340 : :
341 : : /**
342 : : * Writes scope variables to an XML \a element.
343 : : * \see readXml()
344 : : * \since QGIS 3.6
345 : : */
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 : :
356 : : /**
357 : : * \ingroup core
358 : : * \class QgsExpressionContext
359 : : * \brief Expression contexts are used to encapsulate the parameters around which a QgsExpression should
360 : : * be evaluated. QgsExpressions can then utilize the information stored within a context to contextualise
361 : : * their evaluated result. A QgsExpressionContext consists of a stack of QgsExpressionContextScope objects,
362 : : * where scopes added later to the stack will override conflicting variables and functions from scopes
363 : : * lower in the stack.
364 : : *
365 : : * See QgsExpressionContextUtils for helper methods for working with QgsExpressionContext objects.
366 : : *
367 : : * \since QGIS 2.12
368 : : */
369 : : class CORE_EXPORT QgsExpressionContext
370 : : {
371 : : public:
372 : :
373 : : //! Constructor for QgsExpressionContext
374 : 852 : QgsExpressionContext() = default;
375 : :
376 : : /**
377 : : * Initializes the context with given list of scopes.
378 : : * Ownership of the scopes is transferred to the stack.
379 : : * \since QGIS 3.0
380 : : */
381 : : explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
382 : :
383 : : /**
384 : : * Copy constructor
385 : : */
386 : : QgsExpressionContext( const QgsExpressionContext &other );
387 : :
388 : : QgsExpressionContext &operator=( const QgsExpressionContext &other ) SIP_SKIP;
389 : :
390 : : QgsExpressionContext &operator=( QgsExpressionContext &&other ) noexcept SIP_SKIP;
391 : :
392 : : ~QgsExpressionContext();
393 : :
394 : : /**
395 : : * Check whether a variable is specified by any scope within the context.
396 : : * \param name variable name
397 : : * \returns TRUE if variable is set
398 : : * \see variable()
399 : : * \see variableNames()
400 : : */
401 : : bool hasVariable( const QString &name ) const;
402 : :
403 : : /**
404 : : * Fetches a matching variable from the context. The variable will be fetched
405 : : * from the last scope contained within the context which has a matching
406 : : * variable set.
407 : : * \param name variable name
408 : : * \returns variable value if matching variable exists in the context, otherwise an invalid QVariant
409 : : * \see hasVariable()
410 : : * \see variableNames()
411 : : */
412 : : QVariant variable( const QString &name ) const;
413 : :
414 : : /**
415 : : * Returns a map of variable name to value representing all the expression variables
416 : : * contained by the context.
417 : : * \since QGIS 3.0
418 : : */
419 : : QVariantMap variablesToMap() const;
420 : :
421 : : /**
422 : : * Returns TRUE if the specified variable \a name is intended to be highlighted to the
423 : : * user. This is used by the expression builder to more prominently display the
424 : : * variable.
425 : : * \see setHighlightedVariables()
426 : : * \see isHighlightedFunction()
427 : : */
428 : : bool isHighlightedVariable( const QString &name ) const;
429 : :
430 : : /**
431 : : * Returns the current list of variables highlighted within the context.
432 : : *
433 : : * \see setHighlightedVariables()
434 : : * \since QGIS 3.8
435 : : */
436 : : QStringList highlightedVariables() const;
437 : :
438 : : /**
439 : : * Sets the list of variable names within the context intended to be highlighted to the user. This
440 : : * is used by the expression builder to more prominently display these variables.
441 : : * \param variableNames variable names to highlight
442 : : * \see isHighlightedVariable()
443 : : * \see setHighlightedFunctions()
444 : : */
445 : : void setHighlightedVariables( const QStringList &variableNames );
446 : :
447 : : /**
448 : : * Returns TRUE if the specified function \a name is intended to be highlighted to the
449 : : * user. This is used by the expression builder to more prominently display the
450 : : * function.
451 : : * \see setHighlightedFunctions()
452 : : * \see isHighlightedVariable()
453 : : * \since QGIS 3.4
454 : : */
455 : : bool isHighlightedFunction( const QString &name ) const;
456 : :
457 : : /**
458 : : * Sets the list of function \a names intended to be highlighted to the user. This
459 : : * is used by the expression builder to more prominently display these functions.
460 : : *
461 : : * Note that these function names may include standard functions which are not functions
462 : : * specific to this context, and these standard functions will also be highlighted to users.
463 : : *
464 : : * \see isHighlightedFunction()
465 : : * \see setHighlightedVariables()
466 : : * \since QGIS 3.4
467 : : */
468 : : void setHighlightedFunctions( const QStringList &names );
469 : :
470 : : /**
471 : : * Returns the currently active scope from the context for a specified variable name.
472 : : * As scopes later in the stack override earlier contexts, this will be the last matching
473 : : * scope which contains a matching variable.
474 : : * \param name variable name
475 : : * \returns matching scope containing variable, or NULLPTR if none found
476 : : */
477 : : QgsExpressionContextScope *activeScopeForVariable( const QString &name );
478 : :
479 : : /**
480 : : * Returns the currently active scope from the context for a specified variable name.
481 : : * As scopes later in the stack override earlier contexts, this will be the last matching
482 : : * scope which contains a matching variable.
483 : : * \param name variable name
484 : : * \returns matching scope containing variable, or NULLPTR if none found
485 : : * \note not available in Python bindings
486 : : */
487 : : const QgsExpressionContextScope *activeScopeForVariable( const QString &name ) const SIP_SKIP;
488 : :
489 : : /**
490 : : * Returns the scope at the specified index within the context.
491 : : * \param index index of scope
492 : : * \returns matching scope, or NULLPTR if none found
493 : : * \see lastScope()
494 : : */
495 : : QgsExpressionContextScope *scope( int index );
496 : :
497 : : /**
498 : : * Returns the last scope added to the context.
499 : : * \see scope()
500 : : */
501 : : QgsExpressionContextScope *lastScope();
502 : :
503 : : /**
504 : : * Returns a list of scopes contained within the stack.
505 : : * \returns list of pointers to scopes
506 : : */
507 : 0 : QList< QgsExpressionContextScope * > scopes() { return mStack; }
508 : :
509 : : /**
510 : : * Returns the index of the specified scope if it exists within the context.
511 : : * \param scope scope to find
512 : : * \returns index of scope, or -1 if scope was not found within the context.
513 : : */
514 : : int indexOfScope( QgsExpressionContextScope *scope ) const;
515 : :
516 : : /**
517 : : * Returns the index of the first scope with a matching name within the context.
518 : : * \param scopeName name of scope to find
519 : : * \returns index of scope, or -1 if scope was not found within the context.
520 : : * \since QGIS 3.0
521 : : */
522 : : int indexOfScope( const QString &scopeName ) const;
523 : :
524 : : /**
525 : : * Returns a list of variables names set by all scopes in the context.
526 : : * \returns list of unique variable names
527 : : * \see filteredVariableNames
528 : : * \see functionNames
529 : : * \see hasVariable
530 : : * \see variable
531 : : */
532 : : QStringList variableNames() const;
533 : :
534 : : /**
535 : : * Returns a filtered list of variables names set by all scopes in the context. The included
536 : : * variables are those which should be seen by users.
537 : : * \returns filtered list of unique variable names
538 : : * \see variableNames
539 : : */
540 : : QStringList filteredVariableNames() const;
541 : :
542 : : /**
543 : : * Returns whether a variable is read only, and should not be modifiable by users.
544 : : * \param name variable name
545 : : * \returns TRUE if variable is read only. Read only status will be taken from last
546 : : * matching scope which contains a matching variable.
547 : : */
548 : : bool isReadOnly( const QString &name ) const;
549 : :
550 : : /**
551 : : * Returns a translated description string for the variable with specified \a name.
552 : : *
553 : : * If no specific description has been provided for the variable, the value from
554 : : * QgsExpression::variableHelpText() will be returned.
555 : : *
556 : : * \since QGIS 3.0
557 : : */
558 : : QString description( const QString &name ) const;
559 : :
560 : : /**
561 : : * Checks whether a specified function is contained in the context.
562 : : * \param name function name
563 : : * \returns TRUE if context provides a matching function
564 : : * \see function
565 : : */
566 : : bool hasFunction( const QString &name ) const;
567 : :
568 : : /**
569 : : * Retrieves a list of function names contained in the context.
570 : : * \see function()
571 : : * \see variableNames()
572 : : */
573 : : QStringList functionNames() const;
574 : :
575 : : /**
576 : : * Fetches a matching function from the context. The function will be fetched
577 : : * from the last scope contained within the context which has a matching
578 : : * function set.
579 : : * \param name function name
580 : : * \returns function if contained by the context, otherwise NULLPTR.
581 : : * \see hasFunction
582 : : */
583 : : QgsExpressionFunction *function( const QString &name ) const;
584 : :
585 : : /**
586 : : * Returns the number of scopes contained in the context.
587 : : */
588 : : int scopeCount() const;
589 : :
590 : : /**
591 : : * Appends a scope to the end of the context. This scope will override
592 : : * any matching variables or functions provided by existing scopes within the
593 : : * context. Ownership of the scope is transferred to the stack.
594 : : * \param scope expression context to append to context
595 : : */
596 : : void appendScope( QgsExpressionContextScope *scope SIP_TRANSFER );
597 : :
598 : : /**
599 : : * Appends a list of scopes to the end of the context. This scopes will override
600 : : * any matching variables or functions provided by existing scopes within the
601 : : * context. Ownership of the scopes is transferred to the stack.
602 : : * \param scopes scopes to append to context
603 : : * \since QGIS 3.0
604 : : */
605 : : void appendScopes( const QList<QgsExpressionContextScope *> &scopes SIP_TRANSFER );
606 : :
607 : : /**
608 : : * Removes the last scope from the expression context and return it.
609 : : */
610 : : QgsExpressionContextScope *popScope();
611 : :
612 : : /**
613 : : * Returns all scopes from this context and remove them, leaving this context without
614 : : * any context.
615 : : * Ownership is transferred to the caller.
616 : : *
617 : : * \note Not available in Python
618 : : * \since QGIS 3.0
619 : : */
620 : : QList<QgsExpressionContextScope *> takeScopes() SIP_SKIP;
621 : :
622 : : /**
623 : : * Appends a scope to the end of the context. This scope will override
624 : : * any matching variables or functions provided by existing scopes within the
625 : : * context. Ownership of the scope is transferred to the stack.
626 : : */
627 : : QgsExpressionContext &operator<< ( QgsExpressionContextScope *scope SIP_TRANSFER );
628 : :
629 : : /**
630 : : * Convenience function for setting a feature for the context. The feature
631 : : * will be set within the last scope of the context, so will override any
632 : : * existing features within the context.
633 : : * \param feature feature for context
634 : : * \see feature()
635 : : */
636 : : void setFeature( const QgsFeature &feature );
637 : :
638 : : /**
639 : : * Returns TRUE if the context has a feature associated with it.
640 : : * \see feature()
641 : : * \since QGIS 3.0
642 : : */
643 : : bool hasFeature() const;
644 : :
645 : : /**
646 : : * Convenience function for retrieving the feature for the context, if set.
647 : : * \see setFeature
648 : : */
649 : : QgsFeature feature() const;
650 : :
651 : : /**
652 : : * Convenience function for setting a fields for the context. The fields
653 : : * will be set within the last scope of the context, so will override any
654 : : * existing fields within the context.
655 : : * \param fields fields for context
656 : : * \see fields()
657 : : */
658 : : void setFields( const QgsFields &fields );
659 : :
660 : : /**
661 : : * Convenience function for retrieving the fields for the context, if set.
662 : : * \see setFields
663 : : */
664 : : QgsFields fields() const;
665 : :
666 : : /**
667 : : * Sets the original value variable value for the context.
668 : : * \param value value for original value variable. This usually represents an original widget
669 : : * value before any data defined overrides have been applied.
670 : : * \since QGIS 2.12
671 : : */
672 : : void setOriginalValueVariable( const QVariant &value );
673 : :
674 : : /**
675 : : * Sets a value to cache within the expression context. This can be used to cache the results
676 : : * of expensive expression sub-calculations, to speed up future evaluations using the same
677 : : * expression context.
678 : : * \param key unique key for retrieving cached value
679 : : * \param value value to cache
680 : : * \see hasCachedValue()
681 : : * \see cachedValue()
682 : : * \see clearCachedValues()
683 : : * \since QGIS 2.16
684 : : */
685 : : void setCachedValue( const QString &key, const QVariant &value ) const;
686 : :
687 : : /**
688 : : * Returns TRUE if the expression context contains a cached value with a matching key.
689 : : * \param key unique key used to store cached value
690 : : * \see setCachedValue()
691 : : * \see cachedValue()
692 : : * \see clearCachedValues()
693 : : * \since QGIS 2.16
694 : : */
695 : : bool hasCachedValue( const QString &key ) const;
696 : :
697 : : /**
698 : : * Returns the matching cached value, if set. This can be used to retrieve the previously stored results
699 : : * of an expensive expression sub-calculation.
700 : : * \param key unique key used to store cached value
701 : : * \returns matching cached value, or invalid QVariant if not set
702 : : * \see setCachedValue()
703 : : * \see hasCachedValue()
704 : : * \see clearCachedValues()
705 : : * \since QGIS 2.16
706 : : */
707 : : QVariant cachedValue( const QString &key ) const;
708 : :
709 : : /**
710 : : * Clears all cached values from the context.
711 : : * \see setCachedValue()
712 : : * \see hasCachedValue()
713 : : * \see cachedValue()
714 : : * \since QGIS 2.16
715 : : */
716 : : void clearCachedValues() const;
717 : :
718 : : //! Inbuilt variable name for fields storage
719 : : static const QString EXPR_FIELDS;
720 : : //! Inbuilt variable name for value original value variable
721 : : static const QString EXPR_ORIGINAL_VALUE;
722 : : //! Inbuilt variable name for symbol color variable
723 : : static const QString EXPR_SYMBOL_COLOR;
724 : : //! Inbuilt variable name for symbol angle variable
725 : : static const QString EXPR_SYMBOL_ANGLE;
726 : : //! Inbuilt variable name for geometry part count variable
727 : : static const QString EXPR_GEOMETRY_PART_COUNT;
728 : : //! Inbuilt variable name for geometry part number variable
729 : : static const QString EXPR_GEOMETRY_PART_NUM;
730 : : //! Inbuilt variable name for point count variable
731 : : static const QString EXPR_GEOMETRY_POINT_COUNT;
732 : : //! Inbuilt variable name for point number variable
733 : : static const QString EXPR_GEOMETRY_POINT_NUM;
734 : : //! Inbuilt variable name for cluster size variable
735 : : static const QString EXPR_CLUSTER_SIZE;
736 : : //! Inbuilt variable name for cluster color variable
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
|
