Branch data Line data Source code
1 : : /***************************************************************************
2 : : qgsexpressioncontextutils.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 QGSEXPRESSIONCONTEXTUTILS_H
16 : : #define QGSEXPRESSIONCONTEXTUTILS_H
17 : :
18 : : #include "qgis_core.h"
19 : : #include "qgis_sip.h"
20 : : #include "qgsfeature.h"
21 : : #include "qgspointlocator.h"
22 : : #include "qgsexpressioncontext.h"
23 : : #include <QString>
24 : : #include <QVariantMap>
25 : :
26 : : class QgsExpressionContextScope;
27 : : class QgsProject;
28 : : class QgsLayout;
29 : : class QgsSymbol;
30 : : class QgsLayoutAtlas;
31 : : class QgsLayoutItem;
32 : : class QgsProcessingAlgorithm;
33 : : class QgsProcessingModelAlgorithm;
34 : : class QgsProcessingContext;
35 : : class QgsLayoutMultiFrame;
36 : :
37 : : /**
38 : : * \ingroup core
39 : : * \class QgsExpressionContextUtils
40 : : * \brief Contains utilities for working with QgsExpressionContext objects, including methods
41 : : * for creating scopes for specific uses (e.g., project scopes, layer scopes).
42 : : * \since QGIS 2.12
43 : : */
44 : :
45 : : class CORE_EXPORT QgsExpressionContextUtils
46 : : {
47 : : public:
48 : :
49 : : /**
50 : : * Creates a new scope which contains variables and functions relating to the global QGIS context.
51 : : * For instance, QGIS version numbers and variables specified through QGIS options.
52 : : * \see setGlobalVariable()
53 : : */
54 : : static QgsExpressionContextScope *globalScope() SIP_FACTORY;
55 : :
56 : : /**
57 : : * Creates a new scope which contains functions and variables from the current attribute form/table \a formFeature.
58 : : * The variables and values in this scope will reflect the current state of the form/row being edited.
59 : : * The \a formMode (SingleEditMode etc.) is passed as text
60 : : * \since QGIS 3.2
61 : : */
62 : : static QgsExpressionContextScope *formScope( const QgsFeature &formFeature = QgsFeature( ), const QString &formMode = QString() ) SIP_FACTORY;
63 : :
64 : : /**
65 : : * Creates a new scope which contains functions and variables from the current parent attribute form/table \a formFeature.
66 : : * The variables and values in this scope will reflect the current state of the parent form/row being edited.
67 : : * The \a formMode (SingleEditMode etc.) is passed as text
68 : : * \since QGIS 3.14
69 : : */
70 : : static QgsExpressionContextScope *parentFormScope( const QgsFeature &formFeature = QgsFeature( ), const QString &formMode = QString() ) SIP_FACTORY;
71 : :
72 : : /**
73 : : * Sets a global context variable. This variable will be contained within scopes retrieved via
74 : : * globalScope().
75 : : * \param name variable name
76 : : * \param value variable value
77 : : * \see setGlobalVariable()
78 : : * \see globalScope()
79 : : * \see removeGlobalVariable()
80 : : */
81 : : static void setGlobalVariable( const QString &name, const QVariant &value );
82 : :
83 : : /**
84 : : * Sets all global context variables. Existing global variables will be removed and replaced
85 : : * with the variables specified.
86 : : * \param variables new set of global variables
87 : : * \see setGlobalVariable()
88 : : * \see globalScope()
89 : : * \see removeGlobalVariable()
90 : : */
91 : : static void setGlobalVariables( const QVariantMap &variables );
92 : :
93 : : /**
94 : : * Remove a global context variable.
95 : : * \param name variable name
96 : : * \see setGlobalVariable()
97 : : * \see setGlobalVariables()
98 : : * \see globalScope()
99 : : */
100 : : static void removeGlobalVariable( const QString &name );
101 : :
102 : : /**
103 : : * Creates a new scope which contains variables and functions relating to a QGIS project.
104 : : * For instance, project path and title, and variables specified through the project properties.
105 : : * \param project What project to use
106 : : * \see setProjectVariable()
107 : : */
108 : : static QgsExpressionContextScope *projectScope( const QgsProject *project ) SIP_FACTORY;
109 : :
110 : : /**
111 : : * Sets a project context variable. This variable will be contained within scopes retrieved via
112 : : * projectScope().
113 : : * \param project Project to apply changes to
114 : : * \param name variable name
115 : : * \param value variable value
116 : : * \see setProjectVariables()
117 : : * \see removeProjectVariable()
118 : : * \see projectScope()
119 : : */
120 : : static void setProjectVariable( QgsProject *project, const QString &name, const QVariant &value );
121 : :
122 : : /**
123 : : * Sets all project context variables. Existing project variables will be removed and replaced
124 : : * with the variables specified.
125 : : * \param project Project to apply changes to
126 : : * \param variables new set of project variables
127 : : * \see setProjectVariable()
128 : : * \see removeProjectVariable()
129 : : * \see projectScope()
130 : : */
131 : : static void setProjectVariables( QgsProject *project, const QVariantMap &variables );
132 : :
133 : : /**
134 : : * Remove project context variable.
135 : : * \param project Project to apply changes to
136 : : * \param name variable name
137 : : * \see setProjectVariable()
138 : : * \see setProjectVariables()
139 : : * \see projectScope()
140 : : */
141 : : static void removeProjectVariable( QgsProject *project, const QString &name );
142 : :
143 : : /**
144 : : * Creates a new scope which contains variables and functions relating to a QgsMapLayer.
145 : : * For instance, layer name, id and fields.
146 : : */
147 : : static QgsExpressionContextScope *layerScope( const QgsMapLayer *layer ) SIP_FACTORY;
148 : :
149 : : /**
150 : : * Creates a list of three scopes: global, layer's project and layer.
151 : : * \since QGIS 3.0
152 : : */
153 : : static QList<QgsExpressionContextScope *> globalProjectLayerScopes( const QgsMapLayer *layer ) SIP_FACTORY;
154 : :
155 : : /**
156 : : * Sets a layer context variable. This variable will be contained within scopes retrieved via
157 : : * layerScope().
158 : : * \param layer map layer
159 : : * \param name variable name
160 : : * \param value variable value
161 : : * \see setLayerVariables()
162 : : * \see layerScope()
163 : : */
164 : : static void setLayerVariable( QgsMapLayer *layer, const QString &name, const QVariant &value );
165 : :
166 : : /**
167 : : * Sets all layer context variables. Existing layer variables will be removed and replaced
168 : : * with the variables specified.
169 : : * \param layer map layer
170 : : * \param variables new set of layer variables
171 : : * \see setLayerVariable()
172 : : * \see layerScope()
173 : : */
174 : : static void setLayerVariables( QgsMapLayer *layer, const QVariantMap &variables );
175 : :
176 : : /**
177 : : * Creates a new scope which contains variables and functions relating to a QgsMapSettings object.
178 : : * For instance, map scale and rotation.
179 : : */
180 : : static QgsExpressionContextScope *mapSettingsScope( const QgsMapSettings &mapSettings ) SIP_FACTORY;
181 : :
182 : : /**
183 : : * Sets the expression context variables which are available for expressions triggered by
184 : : * a map tool capture like add feature.
185 : : *
186 : : * \since QGIS 3.0
187 : : */
188 : : static QgsExpressionContextScope *mapToolCaptureScope( const QList<QgsPointLocator::Match> &matches ) SIP_FACTORY;
189 : :
190 : : /**
191 : : * Updates a symbol scope related to a QgsSymbol to an expression context.
192 : : * \param symbol symbol to extract properties from
193 : : * \param symbolScope pointer to an existing scope to update
194 : : * \since QGIS 2.14
195 : : */
196 : : static QgsExpressionContextScope *updateSymbolScope( const QgsSymbol *symbol, QgsExpressionContextScope *symbolScope = nullptr );
197 : :
198 : : /**
199 : : * Creates a new scope which contains variables and functions relating to a QgsLayout \a layout.
200 : : * For instance, number of pages and page sizes.
201 : : * \since QGIS 3.0
202 : : */
203 : : static QgsExpressionContextScope *layoutScope( const QgsLayout *layout ) SIP_FACTORY;
204 : :
205 : : /**
206 : : * Sets a layout context variable. This variable will be contained within scopes retrieved via
207 : : * layoutScope().
208 : : * \param layout target layout
209 : : * \param name variable name
210 : : * \param value variable value
211 : : * \see setLayoutVariables()
212 : : * \see layoutScope()
213 : : * \since QGIS 3.0
214 : : */
215 : : static void setLayoutVariable( QgsLayout *layout, const QString &name, const QVariant &value );
216 : :
217 : : /**
218 : : * Sets all layout context variables. Existing layout variables will be removed and replaced
219 : : * with the variables specified.
220 : : * \param layout target layout
221 : : * \param variables new set of layer variables
222 : : * \see setLayoutVariable()
223 : : * \see layoutScope()
224 : : * \since QGIS 3.0
225 : : */
226 : : static void setLayoutVariables( QgsLayout *layout, const QVariantMap &variables );
227 : :
228 : : /**
229 : : * Creates a new scope which contains variables and functions relating to a QgsLayoutAtlas.
230 : : * For instance, current page name and number.
231 : : * \param atlas source atlas. If NULLPTR, a set of default atlas variables will be added to the scope.
232 : : */
233 : : static QgsExpressionContextScope *atlasScope( const QgsLayoutAtlas *atlas ) SIP_FACTORY;
234 : :
235 : : /**
236 : : * Creates a new scope which contains variables and functions relating to a QgsLayoutItem.
237 : : * For instance, item size and position.
238 : : * \see setLayoutItemVariable()
239 : : * \see setLayoutItemVariables()
240 : : * \since QGIS 3.0
241 : : */
242 : : static QgsExpressionContextScope *layoutItemScope( const QgsLayoutItem *item ) SIP_FACTORY;
243 : :
244 : : /**
245 : : * Sets a layout \a item context variable, with the given \a name and \a value.
246 : : * This variable will be contained within scopes retrieved via
247 : : * layoutItemScope().
248 : : * \see setLayoutItemVariables()
249 : : * \see layoutItemScope()
250 : : * \since QGIS 3.0
251 : : */
252 : : static void setLayoutItemVariable( QgsLayoutItem *item, const QString &name, const QVariant &value );
253 : :
254 : : /**
255 : : * Sets all layout item context variables for an \a item. Existing variables will be removed and replaced
256 : : * with the \a variables specified.
257 : : * \see setLayoutItemVariable()
258 : : * \see layoutItemScope()
259 : : * \since QGIS 3.0
260 : : */
261 : : static void setLayoutItemVariables( QgsLayoutItem *item, const QVariantMap &variables );
262 : :
263 : : /**
264 : : * Creates a new scope which contains variables and functions relating to a QgsLayoutMultiFrame.
265 : : * \see setLayoutMultiFrameVariable()
266 : : * \see setLayoutMultiFrameVariables()
267 : : * \since QGIS 3.10
268 : : */
269 : : static QgsExpressionContextScope *multiFrameScope( const QgsLayoutMultiFrame *frame ) SIP_FACTORY;
270 : :
271 : : /**
272 : : * Sets a layout multi \a frame context variable, with the given \a name and \a value.
273 : : * This variable will be contained within scopes retrieved via
274 : : * multiFrameScope().
275 : : * \see setLayoutItemVariables()
276 : : * \see multiFrameScope()
277 : : * \since QGIS 3.10
278 : : */
279 : : static void setLayoutMultiFrameVariable( QgsLayoutMultiFrame *frame, const QString &name, const QVariant &value );
280 : :
281 : : /**
282 : : * Sets all layout multiframe context variables for an \a frame. Existing variables will be removed and replaced
283 : : * with the \a variables specified.
284 : : * \see setLayoutMultiFrameVariable()
285 : : * \see multiFrameScope()
286 : : * \since QGIS 3.10
287 : : */
288 : : static void setLayoutMultiFrameVariables( QgsLayoutMultiFrame *frame, const QVariantMap &variables );
289 : :
290 : : /**
291 : : * Helper function for creating an expression context which contains just a feature and fields
292 : : * collection. Generally this method should not be used as the created context does not include
293 : : * standard scopes such as the global and project scopes.
294 : : */
295 : : static QgsExpressionContext createFeatureBasedContext( const QgsFeature &feature, const QgsFields &fields );
296 : :
297 : : /**
298 : : * Creates a new scope which contains variables and functions relating to a processing \a algorithm,
299 : : * when used with the specified \a parameters and \a context.
300 : : * For instance, algorithm name and parameter functions.
301 : : * \see processingModelAlgorithmScope()
302 : : */
303 : : static QgsExpressionContextScope *processingAlgorithmScope( const QgsProcessingAlgorithm *algorithm, const QVariantMap ¶meters, QgsProcessingContext &context ) SIP_FACTORY;
304 : :
305 : : /**
306 : : * Creates a new scope which contains variables and functions relating to a processing \a model algorithm,
307 : : * when used with the specified \a parameters and \a context.
308 : : * For instance, model name and path variables.
309 : : * \since QGIS 3.6
310 : : */
311 : : static QgsExpressionContextScope *processingModelAlgorithmScope( const QgsProcessingModelAlgorithm *model, const QVariantMap ¶meters, QgsProcessingContext &context ) SIP_FACTORY;
312 : :
313 : : /**
314 : : * Creates a new scope which contains variables and functions relating to provider notifications
315 : : * \param message the notification message
316 : : */
317 : : static QgsExpressionContextScope *notificationScope( const QString &message = QString() ) SIP_FACTORY;
318 : :
319 : : /**
320 : : * Registers all known core functions provided by QgsExpressionContextScope objects.
321 : : */
322 : : static void registerContextFunctions();
323 : :
324 : : private:
325 : :
326 : 0 : class GetLayerVisibility : public QgsScopedExpressionFunction
327 : : {
328 : : public:
329 : : GetLayerVisibility( const QList<QgsMapLayer *> &layers, double scale = 0 );
330 : : QVariant func( const QVariantList &values, const QgsExpressionContext *, QgsExpression *, const QgsExpressionNodeFunction * ) override;
331 : : QgsScopedExpressionFunction *clone() const override;
332 : :
333 : : private:
334 : : GetLayerVisibility();
335 : :
336 : : QList< QPointer< QgsMapLayer > > mLayers;
337 : : QMap< QPointer< QgsMapLayer >, QPair< double, double > > mScaleBasedVisibilityDetails;
338 : : double mScale = 0.0;
339 : :
340 : : };
341 : :
342 : : friend class QgsLayoutItemMap; // needs access to GetLayerVisibility
343 : :
344 : : };
345 : :
346 : : #ifndef SIP_RUN
347 : :
348 : : /**
349 : : * \class QgsExpressionContextScopePopper
350 : : * \brief RAII class to pop scope from an expression context on destruction
351 : : * \ingroup core
352 : : * \since QGIS 3.10
353 : : */
354 : : class QgsExpressionContextScopePopper
355 : : {
356 : : public:
357 : :
358 : : /**
359 : : * Constructor for QgsExpressionContextScopePopper. Appends the specified \a scope to the
360 : : * end of \a context. \a scope will be automatically popped and deleted when this QgsExpressionContextScopePopper
361 : : * is destroyed.
362 : : *
363 : : * Ownership of \a scope is transferred to the popper, but it is guaranteed to exist of the lifetime
364 : : * of the popper.
365 : : */
366 : 0 : QgsExpressionContextScopePopper( QgsExpressionContext &context, QgsExpressionContextScope *scope )
367 : 0 : : mContext( context )
368 : : {
369 : 0 : mContext.appendScope( scope );
370 : 0 : }
371 : :
372 : 0 : ~QgsExpressionContextScopePopper()
373 : : {
374 : 0 : delete mContext.popScope();
375 : 0 : }
376 : :
377 : : private:
378 : : QgsExpressionContext &mContext;
379 : : };
380 : : #endif
381 : :
382 : : #endif // QGSEXPRESSIONCONTEXTUTILS_H
|
