Skip to content

Commit 89420fc

Browse files
committed
Sipify
1 parent 17656f2 commit 89420fc

8 files changed

+169
-47
lines changed

python/core/composer/qgslayoutmanager.sip

+74-7
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,13 @@ class QgsLayoutManager : QObject
1515
%Docstring
1616
.. versionadded:: 3.0
1717

18-
Manages storage of a set of compositions.
18+
Manages storage of a set of layouts.
1919

2020
QgsLayoutManager handles the storage, serializing and deserializing
21-
of QgsCompositions. Usually this class is not constructed directly, but
21+
of QgsLayouts. Usually this class is not constructed directly, but
2222
rather accessed through a QgsProject via QgsProject.layoutManager().
2323

24-
QgsLayoutManager retains ownership of all the compositions contained
24+
QgsLayoutManager retains ownership of all the layouts contained
2525
in the manager.
2626
%End
2727

@@ -48,6 +48,16 @@ class QgsLayoutManager : QObject
4848
:rtype: bool
4949
%End
5050

51+
bool addLayout( QgsLayout *layout /Transfer/ );
52+
%Docstring
53+
Adds a ``layout`` to the manager. Ownership of the layout is transferred to the manager.
54+
Returns true if the addition was successful, or false if the layout could not be added (eg
55+
as a result of a duplicate layout name).
56+
.. seealso:: :py:func:`removeLayout()`
57+
.. seealso:: :py:func:`layoutAdded()`
58+
:rtype: bool
59+
%End
60+
5161
bool removeComposition( QgsComposition *composition );
5262
%Docstring
5363
Removes a composition from the manager. The composition is deleted.
@@ -56,14 +66,26 @@ class QgsLayoutManager : QObject
5666
.. seealso:: :py:func:`addComposition()`
5767
.. seealso:: :py:func:`compositionRemoved()`
5868
.. seealso:: :py:func:`compositionAboutToBeRemoved()`
69+
.. seealso:: :py:func:`clear()`
70+
:rtype: bool
71+
%End
72+
73+
bool removeLayout( QgsLayout *layout );
74+
%Docstring
75+
Removes a ``layout`` from the manager. The layout is deleted.
76+
Returns true if the removal was successful, or false if the removal failed (eg as a result
77+
of removing a layout which is not contained in the manager).
78+
.. seealso:: :py:func:`addLayout()`
79+
.. seealso:: :py:func:`layoutRemoved()`
80+
.. seealso:: :py:func:`layoutAboutToBeRemoved()`
5981
.. seealso:: :py:func:`clear()`
6082
:rtype: bool
6183
%End
6284

6385
void clear();
6486
%Docstring
65-
Removes and deletes all compositions from the manager.
66-
.. seealso:: :py:func:`removeComposition()`
87+
Removes and deletes all layouts from the manager.
88+
.. seealso:: :py:func:`removeLayout()`
6789
%End
6890

6991
QList< QgsComposition * > compositions() const;
@@ -72,16 +94,29 @@ class QgsLayoutManager : QObject
7294
:rtype: list of QgsComposition
7395
%End
7496

97+
QList< QgsLayout * > layouts() const;
98+
%Docstring
99+
Returns a list of all layouts contained in the manager.
100+
:rtype: list of QgsLayout
101+
%End
102+
75103
QgsComposition *compositionByName( const QString &name ) const;
76104
%Docstring
77105
Returns the composition with a matching name, or None if no matching compositions
78106
were found.
79107
:rtype: QgsComposition
80108
%End
81109

110+
QgsLayout *layoutByName( const QString &name ) const;
111+
%Docstring
112+
Returns the layout with a matching name, or None if no matching layouts
113+
were found.
114+
:rtype: QgsLayout
115+
%End
116+
82117
bool readXml( const QDomElement &element, const QDomDocument &doc );
83118
%Docstring
84-
Reads the manager's state from a DOM element, restoring all compositions
119+
Reads the manager's state from a DOM element, restoring all layouts
85120
present in the XML document.
86121
.. seealso:: :py:func:`writeXml()`
87122
:rtype: bool
@@ -117,38 +152,70 @@ class QgsLayoutManager : QObject
117152
:rtype: QgsLayout
118153
%End
119154

120-
QString generateUniqueTitle() const;
155+
QString generateUniqueComposerTitle() const;
121156
%Docstring
122157
Generates a unique title for a new composition, which does not
123158
clash with any already contained by the manager.
124159
:rtype: str
125160
%End
126161

162+
QString generateUniqueTitle() const;
163+
%Docstring
164+
Generates a unique title for a new layout, which does not
165+
clash with any already contained by the manager.
166+
:rtype: str
167+
%End
168+
127169
signals:
128170

129171
void compositionAboutToBeAdded( const QString &name );
130172
%Docstring
131173
Emitted when a composition is about to be added to the manager
174+
%End
175+
176+
void layoutAboutToBeAdded( const QString &name );
177+
%Docstring
178+
Emitted when a layout is about to be added to the manager
132179
%End
133180

134181
void compositionAdded( const QString &name );
135182
%Docstring
136183
Emitted when a composition has been added to the manager
184+
%End
185+
186+
void layoutAdded( const QString &name );
187+
%Docstring
188+
Emitted when a layout has been added to the manager
137189
%End
138190

139191
void compositionRemoved( const QString &name );
140192
%Docstring
141193
Emitted when a composition was removed from the manager
194+
%End
195+
196+
void layoutRemoved( const QString &name );
197+
%Docstring
198+
Emitted when a layout was removed from the manager
142199
%End
143200

144201
void compositionAboutToBeRemoved( const QString &name );
145202
%Docstring
146203
Emitted when a composition is about to be removed from the manager
204+
%End
205+
206+
void layoutAboutToBeRemoved( const QString &name );
207+
%Docstring
208+
Emitted when a layout is about to be removed from the manager
147209
%End
148210

149211
void compositionRenamed( QgsComposition *composition, const QString &newName );
150212
%Docstring
151213
Emitted when a composition is renamed
214+
%End
215+
216+
void layoutRenamed( QgsLayout *layout, const QString &newName );
217+
%Docstring
218+
Emitted when a layout is renamed
152219
%End
153220

154221
};

python/core/core_auto.sip

+1-1
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@
5151
%Include qgsfeaturestore.sip
5252
%Include qgsfieldformatter.sip
5353
%Include qgsfields.sip
54+
%Include qgsfileutils.sip
5455
%Include qgsfontutils.sip
5556
%Include qgsgeometrysimplifier.sip
5657
%Include qgshistogram.sip
@@ -313,7 +314,6 @@
313314
%Include qgsfieldmodel.sip
314315
%Include qgsfieldproxymodel.sip
315316
%Include qgsfiledownloader.sip
316-
%Include qgsfileutils.sip
317317
%Include qgsfeaturefiltermodel.sip
318318
%Include qgsgeometryvalidator.sip
319319
%Include qgsgml.sip

python/core/layout/qgslayout.sip

+7-3
Original file line numberDiff line numberDiff line change
@@ -178,10 +178,14 @@ class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator, QgsLayoutUndoOb
178178
which deferred z-order updates.
179179
%End
180180

181-
QgsLayoutItem *itemByUuid( const QString &uuid );
181+
QgsLayoutItem *itemByUuid( const QString &uuid, bool includeTemplateUuids = false );
182182
%Docstring
183183
Returns the layout item with matching ``uuid`` unique identifier, or a None
184184
if a matching item could not be found.
185+
186+
If ``includeTemplateUuids`` is true, then item's QgsLayoutItem.templateUuid()
187+
will also be tested when trying to match the uuid.
188+
185189
.. seealso:: :py:func:`multiFrameByUuid()`
186190
:rtype: QgsLayoutItem
187191
%End
@@ -421,7 +425,7 @@ class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator, QgsLayoutUndoOb
421425
%Docstring
422426
Saves the layout as a template at the given file ``path``.
423427
Returns true if save was successful.
424-
.. seealso:: loadFromTemplate()
428+
.. seealso:: :py:func:`loadFromTemplate()`
425429
:rtype: bool
426430
%End
427431

@@ -540,7 +544,7 @@ class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator, QgsLayoutUndoOb
540544
void nameChanged( const QString &name );
541545
%Docstring
542546
Emitted when the layout's name is changed.
543-
.. seealso:: setName()
547+
.. seealso:: :py:func:`setName()`
544548
%End
545549

546550
};

python/core/layout/qgslayoutitem.sip

+54-11
Original file line numberDiff line numberDiff line change
@@ -261,18 +261,10 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
261261
virtual int type() const;
262262

263263
%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.
272265

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
276268
%End
277269

278270
virtual QString uuid() const;
@@ -284,6 +276,17 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
284276
There is no corresponding setter for the uuid - it's created automatically.
285277
.. seealso:: :py:func:`id()`
286278
.. 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()`
287290
:rtype: str
288291
%End
289292

@@ -457,6 +460,7 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
457460
Note that the final position of the item may not match the specified target position,
458461
as data defined item position may override the specified value.
459462

463+
.. seealso:: :py:func:`attemptMoveBy()`
460464
.. seealso:: :py:func:`attemptResize()`
461465
.. seealso:: :py:func:`referencePoint()`
462466
.. seealso:: :py:func:`positionWithUnits()`
@@ -473,6 +477,20 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
473477
Note that the final position and size of the item may not match the specified target rect,
474478
as data defined item position and size may override the specified value.
475479

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+
476494
.. seealso:: :py:func:`attemptResize()`
477495
.. seealso:: :py:func:`attemptMove()`
478496
.. seealso:: :py:func:`referencePoint()`
@@ -550,10 +568,28 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
550568
\param itemElement is the DOM node corresponding to item (e.g. 'LayoutItem' element)
551569
\param document DOM document
552570
\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+
553578
.. seealso:: :py:func:`writeXml()`
579+
.. seealso:: :py:func:`finalizeRestoreFromXml()`
554580
:rtype: bool
555581
%End
556582

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+
557593
virtual QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id, QUndoCommand *parent = 0 ) /Factory/;
558594

559595

@@ -995,6 +1031,13 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
9951031
\param element is the DOM element for the item
9961032
\param document DOM document
9971033
\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+
9981041
.. seealso:: :py:func:`writePropertiesToElement()`
9991042
.. seealso:: :py:func:`readXml()`
10001043
:rtype: bool

python/core/layout/qgslayoutmultiframe.sip

+17-9
Original file line numberDiff line numberDiff line change
@@ -76,15 +76,6 @@ class QgsLayoutMultiFrame: QgsLayoutObject, QgsLayoutUndoObjectInterface
7676
:rtype: int
7777
%End
7878

79-
virtual QString stringType() const = 0;
80-
%Docstring
81-
Return the multiframe type as a string.
82-
83-
This string must be a unique, single word, character only representation of the item type, eg "LayoutHtml"
84-
.. seealso:: :py:func:`type()`
85-
:rtype: str
86-
%End
87-
8879
virtual QSizeF fixedFrameSize( const int frameIndex = -1 ) const;
8980
%Docstring
9081
Returns the fixed size for a frame, if desired. If the fixed frame size changes,
@@ -262,6 +253,16 @@ class QgsLayoutMultiFrame: QgsLayoutObject, QgsLayoutUndoObjectInterface
262253
Cancels the current item command and discards it.
263254
.. seealso:: :py:func:`beginCommand()`
264255
.. seealso:: :py:func:`endCommand()`
256+
%End
257+
258+
virtual void finalizeRestoreFromXml();
259+
%Docstring
260+
Called after all pending items have been restored from XML. Multiframes can use
261+
this method to run steps which must take place after all items have been restored to the layout,
262+
such as connecting to signals emitted by other items, which may not have existed in the layout
263+
at the time readXml() was called. E.g. a scalebar can use this to connect to its linked
264+
map item after restoration from XML.
265+
.. seealso:: :py:func:`readXml()`
265266
%End
266267

267268
public slots:
@@ -338,6 +339,13 @@ class QgsLayoutMultiFrame: QgsLayoutObject, QgsLayoutUndoObjectInterface
338339
\param document DOM document
339340
\param context read write context
340341
.. seealso:: :py:func:`writePropertiesToElement()`
342+
343+
Note that item subclasses should not rely on all other items being present in the
344+
layout at the time this method is called. Instead, any connections and links to
345+
other items must be made in the finalizeRestoreFromXml() method. E.g. when restoring
346+
a scalebar, the connection to the linked map's signals should be implemented
347+
in finalizeRestoreFromXml(), not readPropertiesFromElement().
348+
341349
.. seealso:: :py:func:`readXml()`
342350
:rtype: bool
343351
%End

python/core/layout/qgslayoutpagecollection.sip

+3-3
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ class QgsLayoutPageCollection : QObject, QgsLayoutSerializableObject
145145

146146
Calling deletePage() automatically triggers a reflow() of pages.
147147

148-
.. seealso:: clear()
148+
.. seealso:: :py:func:`clear()`
149149
%End
150150

151151
void deletePage( QgsLayoutItemPage *page );
@@ -155,13 +155,13 @@ class QgsLayoutPageCollection : QObject, QgsLayoutSerializableObject
155155

156156
Calling deletePage() automatically triggers a reflow() of pages.
157157

158-
.. seealso:: clear()
158+
.. seealso:: :py:func:`clear()`
159159
%End
160160

161161
void clear();
162162
%Docstring
163163
Removes all pages from the collection.
164-
.. seealso:: deletePage()
164+
.. seealso:: :py:func:`deletePage()`
165165
%End
166166

167167
QgsLayoutItemPage *takePage( QgsLayoutItemPage *page ) /TransferBack/;

0 commit comments

Comments
 (0)