Branch data Line data Source code
1 : : /***************************************************************************
2 : : qgslayoutitemmapitem.h
3 : : -------------------
4 : : begin : October 2017
5 : : copyright : (C) 2017 by Nyall Dawson
6 : : email : nyall dot dawson at gmail dot com
7 : : ***************************************************************************/
8 : :
9 : : /***************************************************************************
10 : : * *
11 : : * This program is free software; you can redistribute it and/or modify *
12 : : * it under the terms of the GNU General Public License as published by *
13 : : * the Free Software Foundation; either version 2 of the License, or *
14 : : * (at your option) any later version. *
15 : : * *
16 : : ***************************************************************************/
17 : : #ifndef QGSLAYOUTITEMMAPITEM_H
18 : : #define QGSLAYOUTITEMMAPITEM_H
19 : :
20 : : #include "qgis_core.h"
21 : : #include "qgis_sip.h"
22 : : #include "qgslayoutobject.h"
23 : : #include "qgsmaplayerref.h"
24 : :
25 : : class QgsLayoutItemMap;
26 : :
27 : : /**
28 : : * \ingroup core
29 : : * \class QgsLayoutItemMapItem
30 : : * \brief An item which is drawn inside a QgsLayoutItemMap, e.g., a grid or map overview.
31 : : * \since QGIS 3.0
32 : : */
33 : 0 : class CORE_EXPORT QgsLayoutItemMapItem : public QgsLayoutObject
34 : : {
35 : : Q_OBJECT
36 : :
37 : : public:
38 : :
39 : : //! Item stacking position, specifies where the in the map's stack the item should be rendered
40 : : enum StackingPosition
41 : : {
42 : : StackBelowMap, //!< Render below all map layers
43 : : StackBelowMapLayer, //!< Render below a specific map layer (see stackingLayer())
44 : : StackAboveMapLayer, //!< Render above a specific map layer (see stackingLayer())
45 : : StackBelowMapLabels, //!< Render above all map layers, but below map labels
46 : : StackAboveMapLabels, //!< Render above all map layers and labels
47 : : };
48 : :
49 : : /**
50 : : * Constructor for QgsLayoutItemMapItem, attached to the specified \a map.
51 : : *
52 : : * The \a name argument gives a friendly display name for the item.
53 : : */
54 : : QgsLayoutItemMapItem( const QString &name, QgsLayoutItemMap *map );
55 : :
56 : : /**
57 : : * Draws the item on to a destination \a painter.
58 : : */
59 : : virtual void draw( QPainter *painter ) = 0;
60 : :
61 : : /**
62 : : * Stores map item state in a DOM element, where \a element is the DOM element
63 : : * corresponding to a 'LayoutMap' tag.
64 : : * \see readXml()
65 : : */
66 : : virtual bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
67 : :
68 : : /**
69 : : * Sets the map item state from a DOM document, where \a element is the DOM
70 : : * node corresponding to a 'LayoutMapGrid' tag.
71 : : * \see writeXml()
72 : : */
73 : : virtual bool readXml( const QDomElement &element, const QDomDocument &doc, const QgsReadWriteContext &context );
74 : :
75 : : /**
76 : : * Called after all pending items have been restored from XML. Map items can use
77 : : * this method to run steps which must take place after all items have been restored to the layout,
78 : : * such as connecting to signals emitted by other items, which may not have existed in the layout
79 : : * at the time readXml() was called. E.g. an overview can use this to connect to its linked
80 : : * map item after restoration from XML.
81 : : * \see readXml()
82 : : */
83 : : virtual void finalizeRestoreFromXml();
84 : :
85 : : /**
86 : : * Sets the corresponding layout \a map for the item.
87 : : * \see map()
88 : : */
89 : : void setMap( QgsLayoutItemMap *map );
90 : :
91 : : /**
92 : : * Returns the layout item map for the item.
93 : : * \see setMap()
94 : : */
95 : : const QgsLayoutItemMap *map() const;
96 : :
97 : : /**
98 : : * Returns the unique id for the map item.
99 : : */
100 : 0 : QString id() const { return mUuid; }
101 : :
102 : : /**
103 : : * Sets the friendly display \a name for the item.
104 : : * \see name()
105 : : */
106 : : void setName( const QString &name );
107 : :
108 : : /**
109 : : * Returns the friendly display name for the item.
110 : : * \see setName()
111 : : */
112 : : QString name() const;
113 : :
114 : : /**
115 : : * Controls whether the item will be drawn. Set \a enabled to TRUE to enable drawing of the item.
116 : : * \see enabled()
117 : : */
118 : : virtual void setEnabled( bool enabled );
119 : :
120 : : /**
121 : : * Returns whether the item will be drawn.
122 : : * \see setEnabled()
123 : : */
124 : : bool enabled() const;
125 : :
126 : : /**
127 : : * Returns TRUE if the item is drawn using advanced effects, such as blend modes.
128 : : */
129 : : virtual bool usesAdvancedEffects() const;
130 : :
131 : : /**
132 : : * Returns the item's stacking position, which specifies where the in the map's
133 : : * stack the item should be rendered.
134 : : *
135 : : * \see setStackingPosition()
136 : : * \see stackingLayer()
137 : : *
138 : : * \since QGIS 3.6
139 : : */
140 : 0 : StackingPosition stackingPosition() const { return mStackingPosition; }
141 : :
142 : : /**
143 : : * Sets the item's stacking \a position, which specifies where the in the map's
144 : : * stack the item should be rendered.
145 : : *
146 : : * \see stackingPosition()
147 : : * \see setStackingLayer()
148 : : *
149 : : * \since QGIS 3.6
150 : : */
151 : : void setStackingPosition( StackingPosition position ) { mStackingPosition = position; }
152 : :
153 : : /**
154 : : * Returns the item's stacking layer, which specifies where the in the map's
155 : : * stack the item should be rendered.
156 : : *
157 : : * This setting is only used when stackingPosition() is StackBelowMapLayer or
158 : : * StackAboveMapLayer.
159 : : *
160 : : * \see setStackingLayer()
161 : : * \see stackingPosition()
162 : : *
163 : : * \since QGIS 3.6
164 : : */
165 : : QgsMapLayer *stackingLayer() const;
166 : :
167 : : /**
168 : : * Sets the item's stacking \a layer, which specifies where the in the map's
169 : : * stack the item should be rendered.
170 : : *
171 : : * This setting is only used when stackingPosition() is StackBelowMapLayer or
172 : : * StackAboveMapLayer.
173 : : *
174 : : * \see stackingLayer()
175 : : * \see setStackingPosition
176 : : *
177 : : * \since QGIS 3.6
178 : : */
179 : : void setStackingLayer( QgsMapLayer *layer );
180 : :
181 : : /**
182 : : * Accepts the specified style entity \a visitor, causing it to visit all style entities associated
183 : : * with the map item.
184 : : *
185 : : * Returns TRUE if the visitor should continue visiting other objects, or FALSE if visiting
186 : : * should be canceled.
187 : : *
188 : : * \since QGIS 3.10
189 : : */
190 : : virtual bool accept( QgsStyleEntityVisitorInterface *visitor ) const;
191 : :
192 : : /**
193 : : * Returns the internal map layer used by this item, if available.
194 : : *
195 : : * \since QGIS 3.10.1
196 : : */
197 : : virtual QgsMapLayer *mapLayer();
198 : :
199 : : QgsExpressionContext createExpressionContext() const override;
200 : :
201 : : protected:
202 : :
203 : : //! Friendly display name
204 : : QString mName;
205 : :
206 : : //! Associated map
207 : : QgsLayoutItemMap *mMap = nullptr;
208 : :
209 : : //! Unique id
210 : : QString mUuid;
211 : :
212 : : //! True if item is to be displayed on map
213 : : bool mEnabled;
214 : :
215 : : StackingPosition mStackingPosition = StackBelowMapLabels;
216 : :
217 : : QgsMapLayerRef mStackingLayer;
218 : :
219 : : };
220 : :
221 : : /**
222 : : * \ingroup core
223 : : * \class QgsLayoutItemMapItemStack
224 : : * \brief A collection of map items which are drawn above the map content in a
225 : : * QgsLayoutItemMap. The item stack controls which items are drawn and the
226 : : * order they are drawn in.
227 : : * \see QgsLayoutItemMapItem
228 : : * \since QGIS 3.0
229 : : */
230 : : class CORE_EXPORT QgsLayoutItemMapItemStack
231 : : {
232 : : public:
233 : :
234 : : /**
235 : : * Constructor for QgsLayoutItemMapItemStack, attached to the
236 : : * specified \a map.
237 : : */
238 : : QgsLayoutItemMapItemStack( QgsLayoutItemMap *map );
239 : :
240 : : virtual ~QgsLayoutItemMapItemStack();
241 : :
242 : : /**
243 : : * Returns the number of items in the stack.
244 : : */
245 : 0 : int size() const { return mItems.size(); }
246 : :
247 : : /**
248 : : * Stores the state of the item stack in a DOM node, where \a element is the DOM element corresponding to a 'LayoutMap' tag.
249 : : * Returns TRUE if write was successful.
250 : : * \see readXml()
251 : : */
252 : : virtual bool writeXml( QDomElement &element, QDomDocument &doc, const QgsReadWriteContext &context ) const;
253 : :
254 : : /**
255 : : * Sets the item stack's state from a DOM document, where \a element is a DOM node corresponding to a 'LayoutMap' tag.
256 : : * Returns TRUE if read was successful.
257 : : * \see writeXml()
258 : : */
259 : : virtual bool readXml( const QDomElement &element, const QDomDocument &doc, const QgsReadWriteContext &context ) = 0;
260 : :
261 : : /**
262 : : * Called after all pending items have been restored from XML. Map item stacks can use
263 : : * this method to run steps which must take place after all items have been restored to the layout,
264 : : * such as connecting to signals emitted by other items, which may not have existed in the layout
265 : : * at the time readXml() was called. E.g. an overview can use this to connect to its linked
266 : : * map item after restoration from XML.
267 : : * \see readXml()
268 : : */
269 : : virtual void finalizeRestoreFromXml();
270 : :
271 : : /**
272 : : * Draws the items from the stack on a specified \a painter.
273 : : *
274 : : * If \a ignoreStacking is TRUE, then all items will be drawn, regardless
275 : : * of their actual stacking position settings. If it is FALSE, only items
276 : : * which are set to stack above the map item will be drawn.
277 : : */
278 : : void drawItems( QPainter *painter, bool ignoreStacking = true );
279 : :
280 : : /**
281 : : * Returns whether any items within the stack contain advanced effects,
282 : : * such as blending modes.
283 : : */
284 : : bool containsAdvancedEffects() const;
285 : :
286 : : /**
287 : : * Returns TRUE if the stack has any currently enabled items.
288 : : *
289 : : * \since QGIS 3.10
290 : : */
291 : : bool hasEnabledItems() const;
292 : :
293 : : /**
294 : : * Returns a reference to the item at the specified \a index within the stack.
295 : : */
296 : : QgsLayoutItemMapItem *item( int index ) const;
297 : :
298 : : protected:
299 : :
300 : : /**
301 : : * Adds a new map item to the stack and takes ownership of the item.
302 : : * The item will be added to the end of the stack, and rendered
303 : : * above any existing map items already present in the stack.
304 : : * \note After adding an item to the stack update()
305 : : * should be called for the QgsLayoutItemMap to prevent rendering artifacts.
306 : : * \see removeItem()
307 : : */
308 : : void addItem( QgsLayoutItemMapItem *item SIP_TRANSFER );
309 : :
310 : : /**
311 : : * Removes an item which matching \a itemId from the stack and deletes the corresponding QgsLayoutItemMapItem
312 : : * \note After removing an item from the stack, update()
313 : : * should be called for the QgsLayoutItemMap to prevent rendering artifacts.
314 : : * \see addItem()
315 : : */
316 : : void removeItem( const QString &itemId );
317 : :
318 : : /**
319 : : * Moves an item which matching \a itemId up the stack, causing it to be rendered above other items.
320 : : * \note After moving an item within the stack, update() should be
321 : : * called for the QgsLayoutItemMap to redraw the map with the new item stack order.
322 : : * \see moveItemDown()
323 : : */
324 : : void moveItemUp( const QString &itemId );
325 : :
326 : : /**
327 : : * Moves an item which matching \a itemId up the stack, causing it to be rendered above other items.
328 : : * \note After moving an item within the stack, update() should be
329 : : * called for the QgsLayoutItemMap to redraw the map with the new item stack order.
330 : : * \see moveItemUp()
331 : : */
332 : : void moveItemDown( const QString &itemId );
333 : :
334 : : /**
335 : : * Returns a reference to an item which matching \a itemId within the stack.
336 : : */
337 : : QgsLayoutItemMapItem *item( const QString &itemId ) const;
338 : :
339 : : /**
340 : : * Returns a reference to an item at the specified \a index within the stack.
341 : : * \see item()
342 : : * \note not available in Python bindings
343 : : */
344 : : QgsLayoutItemMapItem &operator[]( int index ) SIP_SKIP;
345 : :
346 : : /**
347 : : * Returns a list of QgsLayoutItemMapItems contained by the stack.
348 : : */
349 : : QList< QgsLayoutItemMapItem * > asList() const;
350 : :
351 : : protected:
352 : :
353 : : QList< QgsLayoutItemMapItem * > mItems;
354 : :
355 : : QgsLayoutItemMap *mMap = nullptr;
356 : :
357 : : /**
358 : : * Clears the item stack and deletes all QgsLayoutItemMapItems contained
359 : : * by the stack
360 : : */
361 : : void removeItems();
362 : : };
363 : :
364 : : #endif //QGSLAYOUTITEMMAPITEM_H
365 : :
|
