-
-
Notifications
You must be signed in to change notification settings - Fork 3k
/
qgsexpressioncontext.sip
484 lines (410 loc) · 18.4 KB
/
qgsexpressioncontext.sip
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
/** \ingroup core
* \class QgsScopedExpressionFunction
* \brief Expression function for use within a QgsExpressionContextScope. This differs from a
* standard QgsExpression::Function in that it requires an implemented
* clone() method.
* \note added in QGIS 2.12
*/
class QgsScopedExpressionFunction : QgsExpression::Function
{
%TypeHeaderCode
#include <qgsexpressioncontext.h>
%End
public:
QgsScopedExpressionFunction( QString fnname,
int params,
QString group,
QString helpText = QString(),
bool usesGeometry = false,
QStringList referencedColumns = QStringList(),
bool lazyEval = false,
bool handlesNull = false );
virtual ~QgsScopedExpressionFunction();
virtual QVariant func( const QVariantList& values, const QgsExpressionContext* context, QgsExpression* parent ) = 0;
/** Returns a clone of the function.
*/
virtual QgsScopedExpressionFunction* clone() const = 0 /Factory/;
};
/** \ingroup core
* \class QgsExpressionContextScope
* \brief Single scope for storing variables and functions for use within a QgsExpressionContext.
* Examples include a project's scope, which could contain information about the current project such as
* the project file's location. QgsExpressionContextScope can encapsulate both variables (static values)
* and functions(which are calculated only when an expression is evaluated).
* \note added in QGIS 2.12
*/
class QgsExpressionContextScope
{
%TypeHeaderCode
#include <qgsexpressioncontext.h>
%End
public:
/** Single variable definition for use within a QgsExpressionContextScope.
*/
struct StaticVariable
{
/** Constructor for StaticVariable.
* @param name variable name (should be unique within the QgsExpressionContextScope)
* @param value intial variable value
* @param readOnly true if variable should not be editable by users
*/
StaticVariable( const QString& name = QString(), const QVariant& value = QVariant(), bool readOnly = false );
/** Variable name */
QString name;
/** Variable value */
QVariant value;
/** True if variable should not be editable by users */
bool readOnly;
};
/** Constructor for QgsExpressionContextScope
* @param name friendly display name for the context scope
*/
QgsExpressionContextScope( const QString& name = QString() );
QgsExpressionContextScope( const QgsExpressionContextScope& other );
~QgsExpressionContextScope();
/** Returns the friendly display name of the context scope.
*/
QString name() const;
/** Convenience method for setting a variable in the context scope by name and value. If a variable
* with the same name is already set then its value is overwritten, otherwise a new variable is added to the scope.
* @param name variable name
* @param value variable value
* @see addVariable()
*/
void setVariable( const QString& name, const QVariant& value );
/** Adds a variable into the context scope. If a variable with the same name is already set then its
* value is overwritten, otherwise a new variable is added to the scope.
* @param variable definition of variable to insert
* @see setVariable()
* @see addFunction()
*/
void addVariable( const QgsExpressionContextScope::StaticVariable& variable );
/** Removes a variable from the context scope, if found.
* @param name name of variable to remove
* @returns true if variable was removed from the scope, false if matching variable was not
* found within the scope
*/
bool removeVariable( const QString& name );
/** Tests whether a variable with the specified name exists in the scope.
* @param name variable name
* @returns true if matching variable was found in the scope
* @see variable()
* @see hasFunction()
*/
bool hasVariable( const QString& name ) const;
/** Retrieves a variable's value from the scope.
* @param name variable name
* @returns variable value, or invalid QVariant if matching variable could not be found
* @see hasVariable()
* @see function()
*/
QVariant variable( const QString& name ) const;
/** Returns a list of variable names contained within the scope.
* @see functionNames()
*/
QStringList variableNames() const;
/** Tests whether the specified variable is read only and should not be editable
* by users.
* @param name variable name
* @returns true if variable is read only
*/
bool isReadOnly( const QString& name ) const;
/** Returns the count of variables contained within the scope.
*/
int variableCount() const;
/** Tests whether a function with the specified name exists in the scope.
* @param name function name
* @returns true if matching function was found in the scope
* @see function()
* @see hasFunction()
*/
bool hasFunction( const QString &name ) const;
/** Retrieves a function from the scope.
* @param name function name
* @returns function, or null if matching function could not be found
* @see hasFunction()
* @see functionNames()
* @see variable()
*/
QgsExpression::Function* function( const QString &name ) const;
/** Retrieves a list of names of functions contained in the scope.
* @see function()
* @see variableNames()
*/
QStringList functionNames() const;
/** Adds a function to the scope.
* @param name function name
* @param function function to insert. Ownership is transferred to the scope.
* @see addVariable()
*/
void addFunction( const QString& name, QgsScopedExpressionFunction* function /Transfer/ );
/** Convenience function for setting a feature for the scope. Any existing
* feature set by the scope will be overwritten.
* @param feature feature for scope
*/
void setFeature( const QgsFeature& feature );
/** Convenience function for setting a fields for the scope. Any existing
* fields set by the scope will be overwritten.
* @param fields fields for scope
*/
void setFields( const QgsFields& fields );
};
/** \ingroup core
* \class QgsExpressionContext
* \brief Expression contexts are used to encapsulate the parameters around which a QgsExpression should
* be evaluated. QgsExpressions can then utilise the information stored within a context to contextualise
* their evaluated result. A QgsExpressionContext consists of a stack of QgsExpressionContextScope objects,
* where scopes added later to the stack will override conflicting variables and functions from scopes
* lower in the stack.
* \note added in QGIS 2.12
*/
class QgsExpressionContext
{
%TypeHeaderCode
#include <qgsexpressioncontext.h>
%End
public:
QgsExpressionContext( );
QgsExpressionContext( const QgsExpressionContext& other );
~QgsExpressionContext();
/** Check whether a variable is specified by any scope within the context.
* @param name variable name
* @returns true if variable is set
* @see variable()
* @see variableNames()
*/
bool hasVariable( const QString& name ) const;
/** Fetches a matching variable from the context. The variable will be fetched
* from the last scope contained within the context which has a matching
* variable set.
* @param name variable name
* @returns variable value if matching variable exists in the context, otherwise an invalid QVariant
* @see hasVariable()
* @see variableNames()
*/
QVariant variable( const QString& name ) const;
/** Returns the currently active scope from the context for a specified variable name.
* As scopes later in the stack override earlier contexts, this will be the last matching
* scope which contains a matching variable.
* @param name variable name
* @returns matching scope containing variable, or null if none found
*/
QgsExpressionContextScope* activeScopeForVariable( const QString& name );
/** Returns the currently active scope from the context for a specified variable name.
* As scopes later in the stack override earlier contexts, this will be the last matching
* scope which contains a matching variable.
* @param name variable name
* @returns matching scope containing variable, or null if none found
*/
//const QgsExpressionContextScope* activeScopeForVariable( const QString& name ) const;
/** Returns the scope at the specified index within the context.
* @param index index of scope
* @returns matching scope, or null if none found
* @see lastScope()
*/
QgsExpressionContextScope* scope( int index );
/** Returns the last scope added to the context.
* @see scope()
*/
QgsExpressionContextScope* lastScope();
/** Returns a list of scopes contained within the stack.
* @returns list of pointers to scopes
*/
QList< QgsExpressionContextScope* > scopes();
/** Returns the index of the specified scope if it exists within the context.
* @param scope scope to find
* @returns index of scope, or -1 if scope was not found within the context.
*/
int indexOfScope( QgsExpressionContextScope* scope ) const;
/** Returns a list of variables names set by all scopes in the context.
* @returns list of unique variable names
* @see filteredVariableNames
* @see functionNames
* @see hasVariable
* @see variable
*/
QStringList variableNames() const;
/** Returns a filtered list of variables names set by all scopes in the context. The included
* variables are those which should be seen by users.
* @returns filtered list of unique variable names
* @see variableNames
*/
QStringList filteredVariableNames() const;
/** Returns whether a variable is read only, and should not be modifiable by users.
* @param name variable name
* @returns true if variable is read only. Read only status will be taken from last
* matching scope which contains a matching variable.
*/
bool isReadOnly( const QString& name ) const;
/** Checks whether a specified function is contained in the context.
* @param name function name
* @returns true if context provides a matching function
* @see function
*/
bool hasFunction( const QString& name ) const;
/** Retrieves a list of function names contained in the context.
* @see function()
* @see variableNames()
*/
QStringList functionNames() const;
/** Fetches a matching function from the context. The function will be fetched
* from the last scope contained within the context which has a matching
* function set.
* @param name function name
* @returns function if contained by the context, otherwise null.
* @see hasFunction
*/
QgsExpression::Function* function( const QString& name ) const;
/** Returns the number of scopes contained in the context.
*/
int scopeCount() const;
/** Appends a scope to the end of the context. This scope will override
* any matching variables or functions provided by existing scopes within the
* context. Ownership of the scope is transferred to the stack.
* @param scope expression context to append to context
*/
void appendScope( QgsExpressionContextScope* scope /Transfer/ );
/** Appends a scope to the end of the context. This scope will override
* any matching variables or functions provided by existing scopes within the
* context. Ownership of the scope is transferred to the stack.
*/
QgsExpressionContext& operator<< ( QgsExpressionContextScope* scope /Transfer/ );
/** Convenience function for setting a feature for the context. The feature
* will be set within the last scope of the context, so will override any
* existing features within the context.
* @param feature feature for context
*/
void setFeature( const QgsFeature& feature );
/** Convenience function for setting a fields for the context. The fields
* will be set within the last scope of the context, so will override any
* existing fields within the context.
* @param fields fields for context
*/
void setFields( const QgsFields& fields );
};
/** \ingroup core
* \class QgsExpressionContextUtils
* \brief Contains utilities for working with QgsExpressionContext objects, including methods
* for creating scopes for specific uses (eg project scopes, layer scopes).
* \note added in QGIS 2.12
*/
class QgsExpressionContextUtils
{
%TypeHeaderCode
#include <qgsexpressioncontext.h>
%End
public:
/** Creates a new scope which contains variables and functions relating to the global QGIS context.
* For instance, QGIS version numbers and variables specified through QGIS options.
* @see setGlobalVariable()
*/
static QgsExpressionContextScope* globalScope() /Factory/;
/** Sets a global context variable. This variable will be contained within scopes retrieved via
* globalScope().
* @param name variable name
* @param value variable value
* @see setGlobalVariable()
* @see globalScope()
*/
static void setGlobalVariable( const QString& name, const QVariant& value );
/** Sets all global context variables. Existing global variables will be removed and replaced
* with the variables specified.
* @param variables new set of global variables
* @see setGlobalVariable()
* @see globalScope()
*/
static void setGlobalVariables( const QgsStringMap& variables );
/** Creates a new scope which contains variables and functions relating to the current QGIS project.
* For instance, project path and title, and variables specified through the project properties.
* @see setProjectVariable()
*/
static QgsExpressionContextScope* projectScope() /Factory/;
/** Sets a project context variable. This variable will be contained within scopes retrieved via
* projectScope().
* @param name variable name
* @param value variable value
* @see setProjectVariables()
* @see projectScope()
*/
static void setProjectVariable( const QString& name, const QVariant& value );
/** Sets all project context variables. Existing project variables will be removed and replaced
* with the variables specified.
* @param variables new set of project variables
* @see setProjectVariable()
* @see projectScope()
*/
static void setProjectVariables( const QgsStringMap& variables );
/** Creates a new scope which contains variables and functions relating to a QgsMapLayer.
* For instance, layer name, id and fields.
*/
static QgsExpressionContextScope* layerScope( QgsMapLayer* layer ) /Factory/;
/** Helper function for creating an expression context which contains just a feature and fields
* collection. Generally this method should not be used as the created context does not include
* standard scopes such as the global and project scopes.
*/
static QgsExpressionContext createFeatureBasedContext( const QgsFeature& feature, const QgsFields& fields );
/** Sets a layer context variable. This variable will be contained within scopes retrieved via
* layerScope().
* @param layer map layer
* @param name variable name
* @param value variable value
* @see setLayerVariables()
* @see layerScope()
*/
static void setLayerVariable( QgsMapLayer* layer, const QString& name, const QVariant& value );
/** Sets all layer context variables. Existing layer variables will be removed and replaced
* with the variables specified.
* @param layer map layer
* @param variables new set of layer variables
* @see setLayerVariable()
* @see layerScope()
*/
static void setLayerVariables( QgsMapLayer* layer, const QgsStringMap variables );
/** Creates a new scope which contains variables and functions relating to a QgsComposition.
* For instance, number of pages and page sizes.
* @param composition source composition
*/
static QgsExpressionContextScope* compositionScope( const QgsComposition *composition ) /Factory/;
/** Sets a composition context variable. This variable will be contained within scopes retrieved via
* compositionScope().
* @param composition target composition
* @param name variable name
* @param value variable value
* @see setCompositionVariables()
* @see compositionScope()
*/
static void setCompositionVariable( QgsComposition* composition, const QString& name, const QVariant& value );
/** Sets all composition context variables. Existing composition variables will be removed and replaced
* with the variables specified.
* @param composition target composition
* @param variables new set of layer variables
* @see setCompositionVariable()
* @see compositionScope()
*/
static void setCompositionVariables( QgsComposition* composition, const QgsStringMap variables );
/** Creates a new scope which contains variables and functions relating to a QgsComposerItem.
* For instance, item size and position.
* @param composerItem source composer item
*/
static QgsExpressionContextScope* composerItemScope( const QgsComposerItem *composerItem ) /Factory/;
/** Sets a composer item context variable. This variable will be contained within scopes retrieved via
* composerItemScope().
* @param composerItem target composer item
* @param name variable name
* @param value variable value
* @see setComposerItemVariables()
* @see composerItemScope()
*/
static void setComposerItemVariable( QgsComposerItem* composerItem, const QString& name, const QVariant& value );
/** Sets all composition context variables. Existing compositoin variables will be removed and replaced
* with the variables specified.
* @param composerItem target composer item
* @param variables new set of layer variables
* @see setComposerItemVariable()
* @see composerItemScope()
*/
static void setComposerItemVariables( QgsComposerItem* composerItem, const QgsStringMap variables );
/** Registers all known core functions provided by QgsExpressionContextScope objects.
*/
static void registerContextFunctions();
};