Branch data Line data Source code
1 : : /***************************************************************************
2 : : qgslayout.h
3 : : -------------------
4 : : begin : June 2017
5 : : copyright : (C) 2017 by Nyall Dawson
6 : : email : nyall dot dawson at gmail dot com
7 : : ***************************************************************************/
8 : : /***************************************************************************
9 : : * *
10 : : * This program is free software; you can redistribute it and/or modify *
11 : : * it under the terms of the GNU General Public License as published by *
12 : : * the Free Software Foundation; either version 2 of the License, or *
13 : : * (at your option) any later version. *
14 : : * *
15 : : ***************************************************************************/
16 : : #ifndef QGSLAYOUT_H
17 : : #define QGSLAYOUT_H
18 : :
19 : : #include "qgis_core.h"
20 : : #include <QGraphicsScene>
21 : : #include "qgslayoutsnapper.h"
22 : : #include "qgsexpressioncontextgenerator.h"
23 : : #include "qgslayoutgridsettings.h"
24 : : #include "qgslayoutguidecollection.h"
25 : : #include "qgslayoutexporter.h"
26 : : #include "qgsmasterlayoutinterface.h"
27 : :
28 : : class QgsLayoutItemMap;
29 : : class QgsLayoutModel;
30 : : class QgsLayoutMultiFrame;
31 : : class QgsLayoutPageCollection;
32 : : class QgsLayoutUndoStack;
33 : : class QgsLayoutRenderContext;
34 : : class QgsLayoutReportContext;
35 : :
36 : : /**
37 : : * \ingroup core
38 : : * \class QgsLayout
39 : : * \brief Base class for layouts, which can contain items such as maps, labels, scalebars, etc.
40 : : *
41 : : * While the raw QGraphicsScene API can be used to render the contents of a QgsLayout
42 : : * to a QPainter, it is recommended to instead use a QgsLayoutExporter to handle rendering
43 : : * layouts instead. QgsLayoutExporter automatically takes care of the intracacies of
44 : : * preparing the layout and paint devices for correct exports, respecting various
45 : : * user settings such as the layout context DPI.
46 : : *
47 : : * \since QGIS 3.0
48 : : */
49 : : class CORE_EXPORT QgsLayout : public QGraphicsScene, public QgsExpressionContextGenerator, public QgsLayoutUndoObjectInterface
50 : : {
51 : 0 : Q_OBJECT
52 : :
53 : : public:
54 : :
55 : : //! Preset item z-values, to ensure correct stacking
56 : : enum ZValues
57 : : {
58 : : ZPage = 0, //!< Z-value for page (paper) items
59 : : ZItem = 1, //!< Minimum z value for items
60 : : ZGrid = 9997, //!< Z-value for page grids
61 : : ZGuide = 9998, //!< Z-value for page guides
62 : : ZSmartGuide = 9999, //!< Z-value for smart (item bounds based) guides
63 : : ZMouseHandles = 10000, //!< Z-value for mouse handles
64 : : ZViewTool = 10001, //!< Z-value for temporary view tool items
65 : : ZSnapIndicator = 10002, //!< Z-value for snapping indicator
66 : : };
67 : :
68 : : //! Layout undo commands, used for collapsing undo commands
69 : : enum UndoCommand
70 : : {
71 : : UndoLayoutDpi, //!< Change layout default DPI
72 : : UndoNone = -1, //!< No command suppression
73 : : };
74 : :
75 : : /**
76 : : * Construct a new layout linked to the specified \a project.
77 : : *
78 : : * If the layout is a "new" layout (as opposed to a layout which will
79 : : * restore a previous state from XML) then initializeDefaults() should be
80 : : * called on the new layout.
81 : : */
82 : : QgsLayout( QgsProject *project );
83 : :
84 : : ~QgsLayout() override;
85 : :
86 : : /**
87 : : * Creates a clone of the layout. Ownership of the return layout
88 : : * is transferred to the caller.
89 : : */
90 : : QgsLayout *clone() const SIP_FACTORY;
91 : :
92 : : /**
93 : : * Initializes an empty layout, e.g. by adding a default page to the layout. This should be called after creating
94 : : * a new layout.
95 : : */
96 : : void initializeDefaults();
97 : :
98 : : /**
99 : : * Clears the layout.
100 : : *
101 : : * Calling this method removes all items and pages from the layout.
102 : : */
103 : : void clear();
104 : :
105 : : /**
106 : : * The project associated with the layout. Used to get access to layers, map themes,
107 : : * relations and various other bits. It is never NULLPTR.
108 : : *
109 : : */
110 : : QgsProject *project() const;
111 : :
112 : : /**
113 : : * Returns the items model attached to the layout.
114 : : */
115 : : QgsLayoutModel *itemsModel();
116 : :
117 : : /**
118 : : * Returns a list of layout items of a specific type.
119 : : * \note not available in Python bindings
120 : : */
121 : 0 : template<class T> void layoutItems( QList<T *> &itemList ) const SIP_SKIP
122 : : {
123 : 0 : itemList.clear();
124 : 0 : QList<QGraphicsItem *> graphicsItemList = items();
125 : 0 : QList<QGraphicsItem *>::iterator itemIt = graphicsItemList.begin();
126 : 0 : for ( ; itemIt != graphicsItemList.end(); ++itemIt )
127 : : {
128 : 0 : T *item = dynamic_cast<T *>( *itemIt );
129 : 0 : if ( item )
130 : : {
131 : 0 : itemList.push_back( item );
132 : 0 : }
133 : 0 : }
134 : 0 : }
135 : :
136 : : /**
137 : : * Returns a list of layout objects (items and multiframes) of a specific type.
138 : : * \note not available in Python bindings
139 : : */
140 : : template<class T> void layoutObjects( QList<T *> &objectList ) const SIP_SKIP
141 : : {
142 : : objectList.clear();
143 : : const QList<QGraphicsItem *> itemList( items() );
144 : : const QList<QgsLayoutMultiFrame *> frameList( multiFrames() );
145 : : for ( const auto &obj : itemList )
146 : : {
147 : : T *item = dynamic_cast<T *>( obj );
148 : : if ( item )
149 : : {
150 : : objectList.push_back( item );
151 : : }
152 : : }
153 : : for ( const auto &obj : frameList )
154 : : {
155 : : T *item = dynamic_cast<T *>( obj );
156 : : if ( item )
157 : : {
158 : : objectList.push_back( item );
159 : : }
160 : : }
161 : : }
162 : :
163 : : /**
164 : : * Returns list of selected layout items.
165 : : *
166 : : * If \a includeLockedItems is set to TRUE, then locked items will also be included
167 : : * in the returned list.
168 : : */
169 : : QList<QgsLayoutItem *> selectedLayoutItems( bool includeLockedItems = true );
170 : :
171 : : /**
172 : : * Clears any selected items and sets \a item as the current selection.
173 : : */
174 : : void setSelectedItem( QgsLayoutItem *item );
175 : :
176 : : /**
177 : : * Clears any selected items in the layout.
178 : : *
179 : : * Call this method rather than QGraphicsScene::clearSelection, as the latter does
180 : : * not correctly emit signals to allow the layout's model to update.
181 : : */
182 : : void deselectAll();
183 : :
184 : : /**
185 : : * Raises an \a item up the z-order.
186 : : * Returns TRUE if the item was successfully raised.
187 : : *
188 : : * If \a deferUpdate is TRUE, the scene will not be visibly updated
189 : : * to reflect the new stacking order. This allows multiple
190 : : * raiseItem() calls to be made in sequence without the cost of
191 : : * updating the scene for each one.
192 : : *
193 : : * \see lowerItem()
194 : : * \see updateZValues()
195 : : */
196 : : bool raiseItem( QgsLayoutItem *item, bool deferUpdate = false );
197 : :
198 : : /**
199 : : * Lowers an \a item down the z-order.
200 : : * Returns TRUE if the item was successfully lowered.
201 : : *
202 : : * If \a deferUpdate is TRUE, the scene will not be visibly updated
203 : : * to reflect the new stacking order. This allows multiple
204 : : * raiseItem() calls to be made in sequence without the cost of
205 : : * updating the scene for each one.
206 : : *
207 : : * \see raiseItem()
208 : : * \see updateZValues()
209 : : */
210 : : bool lowerItem( QgsLayoutItem *item, bool deferUpdate = false );
211 : :
212 : : /**
213 : : * Raises an \a item up to the top of the z-order.
214 : : * Returns TRUE if the item was successfully raised.
215 : : *
216 : : * If \a deferUpdate is TRUE, the scene will not be visibly updated
217 : : * to reflect the new stacking order. This allows multiple
218 : : * raiseItem() calls to be made in sequence without the cost of
219 : : * updating the scene for each one.
220 : : *
221 : : * \see moveItemToBottom()
222 : : * \see updateZValues()
223 : : */
224 : : bool moveItemToTop( QgsLayoutItem *item, bool deferUpdate = false );
225 : :
226 : : /**
227 : : * Lowers an \a item down to the bottom of the z-order.
228 : : * Returns TRUE if the item was successfully lowered.
229 : : * If \a deferUpdate is TRUE, the scene will not be visibly updated
230 : : * to reflect the new stacking order. This allows multiple
231 : : * raiseItem() calls to be made in sequence without the cost of
232 : : * updating the scene for each one.
233 : : *
234 : : * \see moveItemToTop()
235 : : * \see updateZValues()
236 : : */
237 : : bool moveItemToBottom( QgsLayoutItem *item, bool deferUpdate = false );
238 : :
239 : : /**
240 : : * Resets the z-values of items based on their position in the internal
241 : : * z order list. This should be called after any stacking changes
242 : : * which deferred z-order updates.
243 : : */
244 : : void updateZValues( bool addUndoCommands = true );
245 : :
246 : : /**
247 : : * Returns the layout item with matching \a uuid unique identifier, or NULLPTR
248 : : * if a matching item could not be found.
249 : : *
250 : : * If \a includeTemplateUuids is TRUE, then item's template UUID
251 : : * will also be tested when trying to match the uuid. This may differ from the item's UUID
252 : : * for items which have been added to an existing layout from a template. In this case
253 : : * the template UUID returns the original item UUID at the time the template was created,
254 : : * vs the item's uuid() which returns the current instance of the item's unique identifier.
255 : : * Note that template UUIDs are only available while a layout is being restored from XML.
256 : : *
257 : : * \see itemByTemplateUuid()
258 : : * \see multiFrameByUuid()
259 : : * \see itemById()
260 : : */
261 : : QgsLayoutItem *itemByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
262 : :
263 : : /**
264 : : * Returns the layout item with matching template \a uuid unique identifier, or NULLPTR
265 : : * if a matching item could not be found. Unlike itemByUuid(), this method ONLY checks
266 : : * template UUIDs for a match.
267 : : *
268 : : * Template UUIDs are valid only for items which have been added to an existing layout from a template. In this case
269 : : * the template UUID is the original item UUID at the time the template was created,
270 : : * vs the item's uuid() which returns the current instance of the item's unique identifier.
271 : : *
272 : : * Note that template UUIDs are only available while a layout is being restored from XML.
273 : : *
274 : : * \see itemByUuid()
275 : : * \see multiFrameByUuid()
276 : : * \see itemById()
277 : : */
278 : : QgsLayoutItem *itemByTemplateUuid( const QString &uuid ) const;
279 : :
280 : : /**
281 : : * Returns a layout item given its \a id.
282 : : * Since item IDs are not necessarely unique, this function returns the first matching
283 : : * item found.
284 : : * \see itemByUuid()
285 : : */
286 : : QgsLayoutItem *itemById( const QString &id ) const;
287 : :
288 : : /**
289 : : * Returns the layout multiframe with matching \a uuid unique identifier, or NULLPTR
290 : : * if a matching multiframe could not be found.
291 : : *
292 : : * If \a includeTemplateUuids is TRUE, then the multiframe's QgsLayoutMultiFrame::templateUuid()
293 : : * will also be tested when trying to match the uuid. Template UUIDs are valid only for items
294 : : * which have been added to an existing layout from a template. In this case
295 : : * the template UUID is the original item UUID at the time the template was created,
296 : : * vs the item's uuid() which returns the current instance of the item's unique identifier.
297 : : * Note that template UUIDs are only available while a layout is being restored from XML.
298 : : *
299 : : * \see itemByUuid()
300 : : */
301 : : QgsLayoutMultiFrame *multiFrameByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
302 : :
303 : : /**
304 : : * Returns the topmost layout item at a specified \a position. Ignores paper items.
305 : : * If \a ignoreLocked is set to TRUE any locked items will be ignored.
306 : : */
307 : : QgsLayoutItem *layoutItemAt( QPointF position, bool ignoreLocked = false ) const;
308 : :
309 : : /**
310 : : * Returns the topmost layout item at a specified \a position which is below a specified \a item. Ignores paper items.
311 : : * If \a ignoreLocked is set to TRUE any locked items will be ignored.
312 : : */
313 : : QgsLayoutItem *layoutItemAt( QPointF position, const QgsLayoutItem *belowItem, bool ignoreLocked = false ) const;
314 : :
315 : : /**
316 : : * Sets the native measurement \a units for the layout. These also form the default unit
317 : : * for measurements for the layout.
318 : : * \see units()
319 : : * \see convertToLayoutUnits()
320 : : */
321 : 0 : void setUnits( QgsUnitTypes::LayoutUnit units ) { mUnits = units; }
322 : :
323 : : /**
324 : : * Returns the native units for the layout.
325 : : * \see setUnits()
326 : : * \see convertToLayoutUnits()
327 : : */
328 : 0 : QgsUnitTypes::LayoutUnit units() const { return mUnits; }
329 : :
330 : : /**
331 : : * Converts a measurement into the layout's native units.
332 : : * \returns length of measurement in layout units
333 : : * \see convertFromLayoutUnits()
334 : : * \see units()
335 : : */
336 : : double convertToLayoutUnits( QgsLayoutMeasurement measurement ) const;
337 : :
338 : : /**
339 : : * Converts a size into the layout's native units.
340 : : * \returns size of measurement in layout units
341 : : * \see convertFromLayoutUnits()
342 : : * \see units()
343 : : */
344 : : QSizeF convertToLayoutUnits( const QgsLayoutSize &size ) const;
345 : :
346 : : /**
347 : : * Converts a \a point into the layout's native units.
348 : : * \returns point in layout units
349 : : * \see convertFromLayoutUnits()
350 : : * \see units()
351 : : */
352 : : QPointF convertToLayoutUnits( const QgsLayoutPoint &point ) const;
353 : :
354 : : /**
355 : : * Converts a \a length measurement from the layout's native units to a specified target \a unit.
356 : : * \returns length of measurement in specified units
357 : : * \see convertToLayoutUnits()
358 : : * \see units()
359 : : */
360 : : QgsLayoutMeasurement convertFromLayoutUnits( double length, QgsUnitTypes::LayoutUnit unit ) const;
361 : :
362 : : /**
363 : : * Converts a \a size from the layout's native units to a specified target \a unit.
364 : : * \returns size of measurement in specified units
365 : : * \see convertToLayoutUnits()
366 : : * \see units()
367 : : */
368 : : QgsLayoutSize convertFromLayoutUnits( QSizeF size, QgsUnitTypes::LayoutUnit unit ) const;
369 : :
370 : : /**
371 : : * Converts a \a point from the layout's native units to a specified target \a unit.
372 : : * \returns point in specified units
373 : : * \see convertToLayoutUnits()
374 : : * \see units()
375 : : */
376 : : QgsLayoutPoint convertFromLayoutUnits( QPointF point, QgsUnitTypes::LayoutUnit unit ) const;
377 : :
378 : : /**
379 : : * Returns a reference to the layout's render context, which stores information relating to the
380 : : * current rendering settings for the layout.
381 : : */
382 : : QgsLayoutRenderContext &renderContext();
383 : :
384 : : /**
385 : : * Returns a reference to the layout's render context, which stores information relating to the
386 : : * current rendering settings for the layout.
387 : : */
388 : : SIP_SKIP const QgsLayoutRenderContext &renderContext() const;
389 : :
390 : : /**
391 : : * Returns a reference to the layout's report context, which stores information relating to the
392 : : * current reporting context for the layout.
393 : : */
394 : : QgsLayoutReportContext &reportContext();
395 : :
396 : : /**
397 : : * Returns a reference to the layout's report context, which stores information relating to the
398 : : * current reporting context for the layout.
399 : : */
400 : : SIP_SKIP const QgsLayoutReportContext &reportContext() const;
401 : :
402 : : /**
403 : : * Returns a reference to the layout's snapper, which stores handles layout snap grids and lines
404 : : * and snapping points to the nearest matching point.
405 : : */
406 : : QgsLayoutSnapper &snapper() { return mSnapper; }
407 : :
408 : : /**
409 : : * Returns a reference to the layout's snapper, which stores handles layout snap grids and lines
410 : : * and snapping points to the nearest matching point.
411 : : */
412 : : SIP_SKIP const QgsLayoutSnapper &snapper() const { return mSnapper; }
413 : :
414 : : /**
415 : : * Returns a reference to the layout's grid settings, which stores settings relating
416 : : * to grid appearance, spacing and offsets.
417 : : */
418 : 0 : QgsLayoutGridSettings &gridSettings() { return mGridSettings; }
419 : :
420 : : /**
421 : : * Returns a reference to the layout's grid settings, which stores settings relating
422 : : * to grid appearance, spacing and offsets.
423 : : */
424 : : SIP_SKIP const QgsLayoutGridSettings &gridSettings() const { return mGridSettings; }
425 : :
426 : : /**
427 : : * Refreshes the layout when global layout related options change.
428 : : */
429 : : void reloadSettings();
430 : :
431 : : /**
432 : : * Returns a reference to the layout's guide collection, which manages page snap guides.
433 : : */
434 : : QgsLayoutGuideCollection &guides();
435 : :
436 : : /**
437 : : * Returns a reference to the layout's guide collection, which manages page snap guides.
438 : : */
439 : : SIP_SKIP const QgsLayoutGuideCollection &guides() const;
440 : :
441 : : /**
442 : : * Creates an expression context relating to the layout's current state. The context includes
443 : : * scopes for global, project, layout and layout context properties.
444 : : */
445 : : QgsExpressionContext createExpressionContext() const override;
446 : :
447 : : /**
448 : : * Set a custom property for the layout.
449 : : * \param key property key. If a property with the same key already exists it will be overwritten.
450 : : * \param value property value
451 : : * \see customProperty()
452 : : * \see removeCustomProperty()
453 : : * \see customProperties()
454 : : */
455 : : void setCustomProperty( const QString &key, const QVariant &value );
456 : :
457 : : /**
458 : : * Read a custom property from the layout.
459 : : * \param key property key
460 : : * \param defaultValue default value to return if property with matching key does not exist
461 : : * \returns value of matching property
462 : : * \see setCustomProperty()
463 : : * \see removeCustomProperty()
464 : : * \see customProperties()
465 : : */
466 : : QVariant customProperty( const QString &key, const QVariant &defaultValue = QVariant() ) const;
467 : :
468 : : /**
469 : : * Remove a custom property from the layout.
470 : : * \param key property key
471 : : * \see setCustomProperty()
472 : : * \see customProperty()
473 : : * \see customProperties()
474 : : */
475 : : void removeCustomProperty( const QString &key );
476 : :
477 : : /**
478 : : * Returns list of keys stored in custom properties for the layout.
479 : : * \see setCustomProperty()
480 : : * \see customProperty()
481 : : * \see removeCustomProperty()
482 : : */
483 : : QStringList customProperties() const;
484 : :
485 : : /**
486 : : * Returns the map item which will be used to generate corresponding world files when the
487 : : * layout is exported. If no map was explicitly set via setReferenceMap(), the largest
488 : : * map in the layout will be returned (or NULLPTR if there are no maps in the layout).
489 : : * \see setReferenceMap()
490 : : */
491 : : QgsLayoutItemMap *referenceMap() const;
492 : :
493 : : /**
494 : : * Sets the \a map item which will be used to generate corresponding world files when the
495 : : * layout is exported.
496 : : * \see referenceMap()
497 : : */
498 : : void setReferenceMap( QgsLayoutItemMap *map );
499 : :
500 : : /**
501 : : * Returns a pointer to the layout's page collection, which stores and manages
502 : : * page items in the layout.
503 : : */
504 : : QgsLayoutPageCollection *pageCollection();
505 : :
506 : : /**
507 : : * Returns a pointer to the layout's page collection, which stores and manages
508 : : * page items in the layout.
509 : : */
510 : : SIP_SKIP const QgsLayoutPageCollection *pageCollection() const;
511 : :
512 : : /**
513 : : * Calculates the bounds of all non-gui items in the layout. Ignores snap lines, mouse handles
514 : : * and other cosmetic items.
515 : : * \param ignorePages set to TRUE to ignore page items
516 : : * \param margin optional marginal (in percent, e.g., 0.05 = 5% ) to add around items
517 : : * \returns layout bounds, in layout units.
518 : : *
519 : : * \see pageItemBounds()
520 : : */
521 : : QRectF layoutBounds( bool ignorePages = false, double margin = 0.0 ) const;
522 : :
523 : : /**
524 : : * Returns the bounding box of the items contained on a specified \a page.
525 : : * A page number of 0 represents the first page in the layout.
526 : : *
527 : : * Set \a visibleOnly to TRUE to only include visible items.
528 : : *
529 : : * The returned bounds are in layout units.
530 : : *
531 : : * \see layoutBounds()
532 : : */
533 : : QRectF pageItemBounds( int page, bool visibleOnly = false ) const;
534 : :
535 : : /**
536 : : * Adds an \a item to the layout. This should be called instead of the base class addItem()
537 : : * method. Ownership of the item is transferred to the layout.
538 : : */
539 : : void addLayoutItem( QgsLayoutItem *item SIP_TRANSFER );
540 : :
541 : : /**
542 : : * Removes an \a item from the layout. This should be called instead of the base class removeItem()
543 : : * method.
544 : : * The item will also be deleted.
545 : : */
546 : : void removeLayoutItem( QgsLayoutItem *item );
547 : :
548 : : /**
549 : : * Adds a \a multiFrame to the layout. The object is owned by the layout until removeMultiFrame() is called.
550 : : * \see removeMultiFrame()
551 : : * \see multiFrames()
552 : : */
553 : : void addMultiFrame( QgsLayoutMultiFrame *multiFrame SIP_TRANSFER );
554 : :
555 : : /**
556 : : * Removes a \a multiFrame from the layout (but does not delete it).
557 : : * \see addMultiFrame()
558 : : * \see multiFrames()
559 : : */
560 : : void removeMultiFrame( QgsLayoutMultiFrame *multiFrame );
561 : :
562 : : /**
563 : : * Returns a list of multi frames contained in the layout.
564 : : * \see addMultiFrame()
565 : : * \see removeMultiFrame()
566 : : */
567 : : QList< QgsLayoutMultiFrame * > multiFrames() const;
568 : :
569 : : /**
570 : : * Saves the layout as a template at the given file \a path.
571 : : * Returns TRUE if save was successful.
572 : : * \see loadFromTemplate()
573 : : */
574 : : bool saveAsTemplate( const QString &path, const QgsReadWriteContext &context ) const;
575 : :
576 : : /**
577 : : * Load a layout template \a document.
578 : : *
579 : : * By default this method will clear all items from the existing layout and real all layout
580 : : * settings from the template. Setting \a clearExisting to FALSE will only add new items
581 : : * from the template, without overwriting the existing items or layout settings.
582 : : *
583 : : * If \a ok is specified, it will be set to TRUE if the load was successful.
584 : : *
585 : : * Returns a list of loaded items.
586 : : */
587 : : QList< QgsLayoutItem * > loadFromTemplate( const QDomDocument &document, const QgsReadWriteContext &context, bool clearExisting = true, bool *ok SIP_OUT = nullptr );
588 : :
589 : : /**
590 : : * Returns the layout's state encapsulated in a DOM element.
591 : : * \see readXml()
592 : : */
593 : : virtual QDomElement writeXml( QDomDocument &document, const QgsReadWriteContext &context ) const;
594 : :
595 : : /**
596 : : * Sets the collection's state from a DOM element. \a layoutElement is the DOM node corresponding to the layout.
597 : : * \see writeXml()
598 : : */
599 : : virtual bool readXml( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
600 : :
601 : : /**
602 : : * Add items from an XML representation to the layout. Used for project file reading and pasting items from clipboard.
603 : : *
604 : : * The \a position argument is optional, and if it is not specified the items will be restored to their
605 : : * original position from the XML serialization. If specified, the items will be positioned such that the top-left
606 : : * bounds of all added items is located at this \a position.
607 : : *
608 : : * The \a pasteInPlace argument determines whether the serialized position should be respected, but remapped to the
609 : : * origin of the page corresponding to the page at \a position.
610 : : *
611 : : * A list of the newly added items is returned.
612 : : */
613 : : QList< QgsLayoutItem * > addItemsFromXml( const QDomElement &parentElement, const QDomDocument &document,
614 : : const QgsReadWriteContext &context,
615 : : QPointF *position = nullptr, bool pasteInPlace = false );
616 : :
617 : : /**
618 : : * Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout
619 : : * and it's associated objects.
620 : : */
621 : : QgsLayoutUndoStack *undoStack();
622 : :
623 : : /**
624 : : * Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout
625 : : * and it's associated objects.
626 : : */
627 : : SIP_SKIP const QgsLayoutUndoStack *undoStack() const;
628 : :
629 : : QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id = 0, QUndoCommand *parent = nullptr ) SIP_FACTORY override;
630 : :
631 : : /**
632 : : * Creates a new group from a list of layout \a items and adds the group to the layout.
633 : : * If grouping was not possible, NULLPTR will be returned.
634 : : * \see ungroupItems()
635 : : */
636 : : QgsLayoutItemGroup *groupItems( const QList<QgsLayoutItem *> &items );
637 : :
638 : : /**
639 : : * Ungroups items by removing them from an item \a group and removing the group from the
640 : : * layout. Child items will remain in the layout and will not be deleted.
641 : : *
642 : : * Returns a list of the items removed from the group, or an empty list if ungrouping
643 : : * was not successful.
644 : : *
645 : : * \see groupItems()
646 : : */
647 : : QList<QgsLayoutItem *> ungroupItems( QgsLayoutItemGroup *group );
648 : :
649 : : /**
650 : : * Accepts the specified style entity \a visitor, causing it to visit all style entities associated
651 : : * with the layout.
652 : : *
653 : : * Returns TRUE if the visitor should continue visiting other objects, or FALSE if visiting
654 : : * should be canceled.
655 : : *
656 : : * \since QGIS 3.10
657 : : */
658 : : bool accept( QgsStyleEntityVisitorInterface *visitor ) const;
659 : :
660 : : public slots:
661 : :
662 : : /**
663 : : * Forces the layout, and all items contained within it, to refresh. For instance, this causes maps to redraw
664 : : * and rebuild cached images, html items to reload their source url, and attribute tables
665 : : * to refresh their contents. Calling this also triggers a recalculation of all data defined
666 : : * attributes within the layout.
667 : : *
668 : : * \see refreshed()
669 : : */
670 : : void refresh();
671 : :
672 : : /**
673 : : * Updates the scene bounds of the layout.
674 : : */
675 : : void updateBounds();
676 : :
677 : : signals:
678 : :
679 : : /**
680 : : * Emitted when properties of the layout change. This signal is only
681 : : * emitted for settings directly managed by the layout, and is not emitted
682 : : * when child items change.
683 : : */
684 : : void changed();
685 : :
686 : : /**
687 : : * Emitted whenever the expression variables stored in the layout have been changed.
688 : : */
689 : : void variablesChanged();
690 : :
691 : : /**
692 : : * Emitted whenever the selected item changes.
693 : : * If NULLPTR, no item is selected.
694 : : */
695 : : void selectedItemChanged( QgsLayoutItem *selected );
696 : :
697 : : /**
698 : : * Emitted when the layout has been refreshed and items should also be refreshed
699 : : * and updated.
700 : : */
701 : : void refreshed();
702 : :
703 : : /**
704 : : * Emitted whenever the \a total number of background tasks running in items from the layout changes.
705 : : *
706 : : * \since QGIS 3.10
707 : : */
708 : : void backgroundTaskCountChanged( int total );
709 : :
710 : : private slots:
711 : : void itemBackgroundTaskCountChanged( int count );
712 : :
713 : : private:
714 : :
715 : : QgsProject *mProject = nullptr;
716 : : std::unique_ptr< QgsLayoutModel > mItemsModel;
717 : :
718 : : QgsObjectCustomProperties mCustomProperties;
719 : :
720 : : QgsUnitTypes::LayoutUnit mUnits = QgsUnitTypes::LayoutMillimeters;
721 : : QgsLayoutRenderContext *mRenderContext = nullptr;
722 : : QgsLayoutReportContext *mReportContext = nullptr;
723 : : QgsLayoutSnapper mSnapper;
724 : : QgsLayoutGridSettings mGridSettings;
725 : :
726 : : std::unique_ptr< QgsLayoutPageCollection > mPageCollection;
727 : : std::unique_ptr< QgsLayoutUndoStack > mUndoStack;
728 : :
729 : : //! List of multiframe objects
730 : : QList<QgsLayoutMultiFrame *> mMultiFrames;
731 : :
732 : : //! Item ID for layout map to use for the world file generation
733 : : QString mWorldFileMapId;
734 : :
735 : : QHash< QgsLayoutItem *, int > mBackgroundTaskCount;
736 : :
737 : : //! Writes only the layout settings (not member settings like grid settings, etc) to XML
738 : : void writeXmlLayoutSettings( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
739 : : //! Reads only the layout settings (not member settings like grid settings, etc) from XML
740 : : bool readXmlLayoutSettings( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
741 : :
742 : : /**
743 : : * Adds a layout item to the layout, without adding the corresponding undo commands.
744 : : */
745 : : void addLayoutItemPrivate( QgsLayoutItem *item );
746 : :
747 : : /**
748 : : * Removes an item from the layout, without adding the corresponding undo commands.
749 : : */
750 : : void removeLayoutItemPrivate( QgsLayoutItem *item );
751 : :
752 : : void deleteAndRemoveMultiFrames();
753 : :
754 : : //! Calculates the item minimum position from an XML element
755 : : QPointF minPointFromXml( const QDomElement &elem ) const;
756 : :
757 : : QgsLayout( const QgsLayout & ) = delete;
758 : : QgsLayout &operator=( const QgsLayout & ) = delete;
759 : :
760 : : friend class QgsLayoutItemAddItemCommand;
761 : : friend class QgsLayoutItemDeleteUndoCommand;
762 : : friend class QgsLayoutItemUndoCommand;
763 : : friend class QgsLayoutUndoCommand;
764 : : friend class QgsLayoutItemGroupUndoCommand;
765 : : friend class QgsLayoutModel;
766 : : friend class QgsLayoutMultiFrame;
767 : : friend class QgsCompositionConverter;
768 : : };
769 : :
770 : : #endif //QGSLAYOUT_H
|
