@@ -261,18 +261,10 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
261
261
virtual int type() const;
262
262
263
263
%Docstring
264
- Return correct graphics item type
265
- .. seealso:: :py:func:`stringType()`
266
- :rtype: int
267
- %End
268
-
269
- virtual QString stringType() const = 0;
270
- %Docstring
271
- Return the item type as a string.
264
+ Return unique graphics item type identifier.
272
265
273
- This string must be a unique, single word, character only representation of the item type, eg "LayoutScaleBar"
274
- .. seealso:: :py:func:`type()`
275
- :rtype: str
266
+ Plugin based subclasses should return an identifier greater than QgsLayoutItemRegistry.PluginItem.
267
+ :rtype: int
276
268
%End
277
269
278
270
virtual QString uuid() const;
@@ -284,6 +276,17 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
284
276
There is no corresponding setter for the uuid - it's created automatically.
285
277
.. seealso:: :py:func:`id()`
286
278
.. seealso:: :py:func:`setId()`
279
+ .. seealso:: :py:func:`templateUuid()`
280
+ :rtype: str
281
+ %End
282
+
283
+ QString templateUuid() const;
284
+ %Docstring
285
+ Returns the item's original identification string. This may differ from the item's uuid()
286
+ for items which have been added to an existing layout from a template. In this case
287
+ templateUuid() returns the original item UUID at the time the template was created,
288
+ while uuid() returns the current instance of the item's unique identifier.
289
+ .. seealso:: :py:func:`uuid()`
287
290
:rtype: str
288
291
%End
289
292
@@ -457,6 +460,7 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
457
460
Note that the final position of the item may not match the specified target position,
458
461
as data defined item position may override the specified value.
459
462
463
+ .. seealso:: :py:func:`attemptMoveBy()`
460
464
.. seealso:: :py:func:`attemptResize()`
461
465
.. seealso:: :py:func:`referencePoint()`
462
466
.. seealso:: :py:func:`positionWithUnits()`
@@ -473,6 +477,20 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
473
477
Note that the final position and size of the item may not match the specified target rect,
474
478
as data defined item position and size may override the specified value.
475
479
480
+ .. seealso:: :py:func:`attemptResize()`
481
+ .. seealso:: :py:func:`attemptMove()`
482
+ .. seealso:: :py:func:`referencePoint()`
483
+ .. seealso:: :py:func:`positionWithUnits()`
484
+ %End
485
+
486
+ void attemptMoveBy( double deltaX, double deltaY );
487
+ %Docstring
488
+ Attempts to shift the item's position by a specified ``deltaX`` and ``deltaY``, in layout
489
+ units.
490
+
491
+ Note that the final position of the item may not match the specified offsets,
492
+ as data defined item position and size may override the specified value.
493
+
476
494
.. seealso:: :py:func:`attemptResize()`
477
495
.. seealso:: :py:func:`attemptMove()`
478
496
.. seealso:: :py:func:`referencePoint()`
@@ -550,10 +568,28 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
550
568
\param itemElement is the DOM node corresponding to item (e.g. 'LayoutItem' element)
551
569
\param document DOM document
552
570
\param context read write context
571
+
572
+ Note that item subclasses should not rely on all other items being present in the
573
+ layout at the time this method is called. Instead, any connections and links to
574
+ other items must be made in the finalizeRestoreFromXml() method. E.g. when restoring
575
+ a scalebar, the connection to the linked map's signals should be implemented
576
+ in finalizeRestoreFromXml(), not readXml().
577
+
553
578
.. seealso:: :py:func:`writeXml()`
579
+ .. seealso:: :py:func:`finalizeRestoreFromXml()`
554
580
:rtype: bool
555
581
%End
556
582
583
+ virtual void finalizeRestoreFromXml();
584
+ %Docstring
585
+ Called after all pending items have been restored from XML. Items can use
586
+ this method to run steps which must take place after all items have been restored to the layout,
587
+ such as connecting to signals emitted by other items, which may not have existed in the layout
588
+ at the time readXml() was called. E.g. a scalebar can use this to connect to its linked
589
+ map item after restoration from XML.
590
+ .. seealso:: :py:func:`readXml()`
591
+ %End
592
+
557
593
virtual QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id, QUndoCommand *parent = 0 ) /Factory/;
558
594
559
595
@@ -995,6 +1031,13 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
995
1031
\param element is the DOM element for the item
996
1032
\param document DOM document
997
1033
\param context read write context
1034
+
1035
+ Note that item subclasses should not rely on all other items being present in the
1036
+ layout at the time this method is called. Instead, any connections and links to
1037
+ other items must be made in the finalizeRestoreFromXml() method. E.g. when restoring
1038
+ a scalebar, the connection to the linked map's signals should be implemented
1039
+ in finalizeRestoreFromXml(), not readPropertiesFromElement().
1040
+
998
1041
.. seealso:: :py:func:`writePropertiesToElement()`
999
1042
.. seealso:: :py:func:`readXml()`
1000
1043
:rtype: bool
0 commit comments