Sipify

Author: nyalldawson

python/core/composer/qgslayoutmanager.sip

@@ -15,13 +15,13 @@ class QgsLayoutManager : QObject
 %Docstring
 .. versionadded:: 3.0
 
- Manages storage of a set of compositions.
+ Manages storage of a set of layouts.
 
  QgsLayoutManager handles the storage, serializing and deserializing
- of QgsCompositions. Usually this class is not constructed directly, but
+ of QgsLayouts. Usually this class is not constructed directly, but
  rather accessed through a QgsProject via QgsProject.layoutManager().
 
- QgsLayoutManager retains ownership of all the compositions contained
+ QgsLayoutManager retains ownership of all the layouts contained
  in the manager.
 %End
 
@@ -48,6 +48,16 @@ class QgsLayoutManager : QObject
  :rtype: bool
 %End
 
+    bool addLayout( QgsLayout *layout /Transfer/ );
+%Docstring
+ Adds a ``layout`` to the manager. Ownership of the layout is transferred to the manager.
+ Returns true if the addition was successful, or false if the layout could not be added (eg
+ as a result of a duplicate layout name).
+.. seealso:: :py:func:`removeLayout()`
+.. seealso:: :py:func:`layoutAdded()`
+ :rtype: bool
+%End
+
     bool removeComposition( QgsComposition *composition );
 %Docstring
  Removes a composition from the manager. The composition is deleted.
@@ -56,14 +66,26 @@ class QgsLayoutManager : QObject
 .. seealso:: :py:func:`addComposition()`
 .. seealso:: :py:func:`compositionRemoved()`
 .. seealso:: :py:func:`compositionAboutToBeRemoved()`
+.. seealso:: :py:func:`clear()`
+ :rtype: bool
+%End
+
+    bool removeLayout( QgsLayout *layout );
+%Docstring
+ Removes a ``layout`` from the manager. The layout is deleted.
+ Returns true if the removal was successful, or false if the removal failed (eg as a result
+ of removing a layout which is not contained in the manager).
+.. seealso:: :py:func:`addLayout()`
+.. seealso:: :py:func:`layoutRemoved()`
+.. seealso:: :py:func:`layoutAboutToBeRemoved()`
 .. seealso:: :py:func:`clear()`
  :rtype: bool
 %End
 
     void clear();
 %Docstring
- Removes and deletes all compositions from the manager.
-.. seealso:: :py:func:`removeComposition()`
+ Removes and deletes all layouts from the manager.
+.. seealso:: :py:func:`removeLayout()`
 %End
 
     QList< QgsComposition * > compositions() const;
@@ -72,16 +94,29 @@ class QgsLayoutManager : QObject
  :rtype: list of QgsComposition
 %End
 
+    QList< QgsLayout * > layouts() const;
+%Docstring
+ Returns a list of all layouts contained in the manager.
+ :rtype: list of QgsLayout
+%End
+
     QgsComposition *compositionByName( const QString &name ) const;
 %Docstring
  Returns the composition with a matching name, or None if no matching compositions
  were found.
  :rtype: QgsComposition
 %End
 
+    QgsLayout *layoutByName( const QString &name ) const;
+%Docstring
+ Returns the layout with a matching name, or None if no matching layouts
+ were found.
+ :rtype: QgsLayout
+%End
+
     bool readXml( const QDomElement &element, const QDomDocument &doc );
 %Docstring
- Reads the manager's state from a DOM element, restoring all compositions
+ Reads the manager's state from a DOM element, restoring all layouts
  present in the XML document.
 .. seealso:: :py:func:`writeXml()`
  :rtype: bool
@@ -117,38 +152,70 @@ class QgsLayoutManager : QObject
  :rtype: QgsLayout
 %End
 
-    QString generateUniqueTitle() const;
+    QString generateUniqueComposerTitle() const;
 %Docstring
  Generates a unique title for a new composition, which does not
  clash with any already contained by the manager.
  :rtype: str
 %End
 
+    QString generateUniqueTitle() const;
+%Docstring
+ Generates a unique title for a new layout, which does not
+ clash with any already contained by the manager.
+ :rtype: str
+%End
+
   signals:
 
     void compositionAboutToBeAdded( const QString &name );
 %Docstring
 Emitted when a composition is about to be added to the manager
+%End
+
+    void layoutAboutToBeAdded( const QString &name );
+%Docstring
+Emitted when a layout is about to be added to the manager
 %End
 
     void compositionAdded( const QString &name );
 %Docstring
 Emitted when a composition has been added to the manager
+%End
+
+    void layoutAdded( const QString &name );
+%Docstring
+Emitted when a layout has been added to the manager
 %End
 
     void compositionRemoved( const QString &name );
 %Docstring
 Emitted when a composition was removed from the manager
+%End
+
+    void layoutRemoved( const QString &name );
+%Docstring
+Emitted when a layout was removed from the manager
 %End
 
     void compositionAboutToBeRemoved( const QString &name );
 %Docstring
 Emitted when a composition is about to be removed from the manager
+%End
+
+    void layoutAboutToBeRemoved( const QString &name );
+%Docstring
+Emitted when a layout is about to be removed from the manager
 %End
 
     void compositionRenamed( QgsComposition *composition, const QString &newName );
 %Docstring
 Emitted when a composition is renamed
+%End
+
+    void layoutRenamed( QgsLayout *layout, const QString &newName );
+%Docstring
+Emitted when a layout is renamed
 %End
 
 };

python/core/core_auto.sip

@@ -51,6 +51,7 @@
 %Include qgsfeaturestore.sip
 %Include qgsfieldformatter.sip
 %Include qgsfields.sip
+%Include qgsfileutils.sip
 %Include qgsfontutils.sip
 %Include qgsgeometrysimplifier.sip
 %Include qgshistogram.sip
@@ -313,7 +314,6 @@
 %Include qgsfieldmodel.sip
 %Include qgsfieldproxymodel.sip
 %Include qgsfiledownloader.sip
-%Include qgsfileutils.sip
 %Include qgsfeaturefiltermodel.sip
 %Include qgsgeometryvalidator.sip
 %Include qgsgml.sip

python/core/layout/qgslayout.sip

@@ -178,10 +178,14 @@ class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator, QgsLayoutUndoOb
  which deferred z-order updates.
 %End
 
-    QgsLayoutItem *itemByUuid( const QString &uuid );
+    QgsLayoutItem *itemByUuid( const QString &uuid, bool includeTemplateUuids = false );
 %Docstring
  Returns the layout item with matching ``uuid`` unique identifier, or a None
  if a matching item could not be found.
+
+ If ``includeTemplateUuids`` is true, then item's QgsLayoutItem.templateUuid()
+ will also be tested when trying to match the uuid.
+
 .. seealso:: :py:func:`multiFrameByUuid()`
  :rtype: QgsLayoutItem
 %End
@@ -421,7 +425,7 @@ class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator, QgsLayoutUndoOb
 %Docstring
  Saves the layout as a template at the given file ``path``.
  Returns true if save was successful.
-.. seealso:: loadFromTemplate()
+.. seealso:: :py:func:`loadFromTemplate()`
  :rtype: bool
 %End
 
@@ -540,7 +544,7 @@ class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator, QgsLayoutUndoOb
     void nameChanged( const QString &name );
 %Docstring
  Emitted when the layout's name is changed.
-.. seealso:: setName()
+.. seealso:: :py:func:`setName()`
 %End
 
 };

python/core/layout/qgslayoutitem.sip

@@ -261,18 +261,10 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
     virtual int type() const;
 
 %Docstring
- Return correct graphics item type
-.. seealso:: :py:func:`stringType()`
- :rtype: int
-%End
-
-    virtual QString stringType() const = 0;
-%Docstring
- Return the item type as a string.
+ Return unique graphics item type identifier.
 
- This string must be a unique, single word, character only representation of the item type, eg "LayoutScaleBar"
-.. seealso:: :py:func:`type()`
- :rtype: str
+ Plugin based subclasses should return an identifier greater than QgsLayoutItemRegistry.PluginItem.
+ :rtype: int
 %End
 
     virtual QString uuid() const;
@@ -284,6 +276,17 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
    There is no corresponding setter for the uuid - it's created automatically.
 .. seealso:: :py:func:`id()`
 .. seealso:: :py:func:`setId()`
+.. seealso:: :py:func:`templateUuid()`
+ :rtype: str
+%End
+
+    QString templateUuid() const;
+%Docstring
+ Returns the item's original identification string. This may differ from the item's uuid()
+ for items which have been added to an existing layout from a template. In this case
+ templateUuid() returns the original item UUID at the time the template was created,
+ while uuid() returns the current instance of the item's unique identifier.
+.. seealso:: :py:func:`uuid()`
  :rtype: str
 %End
 
@@ -457,6 +460,7 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
  Note that the final position of the item may not match the specified target position,
  as data defined item position may override the specified value.
 
+.. seealso:: :py:func:`attemptMoveBy()`
 .. seealso:: :py:func:`attemptResize()`
 .. seealso:: :py:func:`referencePoint()`
 .. seealso:: :py:func:`positionWithUnits()`
@@ -473,6 +477,20 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
  Note that the final position and size of the item may not match the specified target rect,
  as data defined item position and size may override the specified value.
 
+.. seealso:: :py:func:`attemptResize()`
+.. seealso:: :py:func:`attemptMove()`
+.. seealso:: :py:func:`referencePoint()`
+.. seealso:: :py:func:`positionWithUnits()`
+%End
+
+    void attemptMoveBy( double deltaX, double deltaY );
+%Docstring
+ Attempts to shift the item's position by a specified ``deltaX`` and ``deltaY``, in layout
+ units.
+
+ Note that the final position of the item may not match the specified offsets,
+ as data defined item position and size may override the specified value.
+
 .. seealso:: :py:func:`attemptResize()`
 .. seealso:: :py:func:`attemptMove()`
 .. seealso:: :py:func:`referencePoint()`
@@ -550,10 +568,28 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
  \param itemElement is the DOM node corresponding to item (e.g. 'LayoutItem' element)
  \param document DOM document
  \param context read write context
+
+ Note that item subclasses should not rely on all other items being present in the
+ layout at the time this method is called. Instead, any connections and links to
+ other items must be made in the finalizeRestoreFromXml() method. E.g. when restoring
+ a scalebar, the connection to the linked map's signals should be implemented
+ in finalizeRestoreFromXml(), not readXml().
+
 .. seealso:: :py:func:`writeXml()`
+.. seealso:: :py:func:`finalizeRestoreFromXml()`
  :rtype: bool
 %End
 
+    virtual void finalizeRestoreFromXml();
+%Docstring
+ Called after all pending items have been restored from XML. Items can use
+ this method to run steps which must take place after all items have been restored to the layout,
+ such as connecting to signals emitted by other items, which may not have existed in the layout
+ at the time readXml() was called. E.g. a scalebar can use this to connect to its linked
+ map item after restoration from XML.
+.. seealso:: :py:func:`readXml()`
+%End
+
     virtual QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id, QUndoCommand *parent = 0 ) /Factory/;
 
 
@@ -995,6 +1031,13 @@ class QgsLayoutItem : QgsLayoutObject, QGraphicsRectItem, QgsLayoutUndoObjectInt
  \param element is the DOM element for the item
  \param document DOM document
  \param context read write context
+
+ Note that item subclasses should not rely on all other items being present in the
+ layout at the time this method is called. Instead, any connections and links to
+ other items must be made in the finalizeRestoreFromXml() method. E.g. when restoring
+ a scalebar, the connection to the linked map's signals should be implemented
+ in finalizeRestoreFromXml(), not readPropertiesFromElement().
+
 .. seealso:: :py:func:`writePropertiesToElement()`
 .. seealso:: :py:func:`readXml()`
  :rtype: bool

python/core/layout/qgslayoutmultiframe.sip

@@ -76,15 +76,6 @@ class QgsLayoutMultiFrame: QgsLayoutObject, QgsLayoutUndoObjectInterface
  :rtype: int
 %End
 
-    virtual QString stringType() const = 0;
-%Docstring
- Return the multiframe type as a string.
-
- This string must be a unique, single word, character only representation of the item type, eg "LayoutHtml"
-.. seealso:: :py:func:`type()`
- :rtype: str
-%End
-
     virtual QSizeF fixedFrameSize( const int frameIndex = -1 ) const;
 %Docstring
  Returns the fixed size for a frame, if desired. If the fixed frame size changes,
@@ -262,6 +253,16 @@ class QgsLayoutMultiFrame: QgsLayoutObject, QgsLayoutUndoObjectInterface
  Cancels the current item command and discards it.
 .. seealso:: :py:func:`beginCommand()`
 .. seealso:: :py:func:`endCommand()`
+%End
+
+    virtual void finalizeRestoreFromXml();
+%Docstring
+ Called after all pending items have been restored from XML. Multiframes can use
+ this method to run steps which must take place after all items have been restored to the layout,
+ such as connecting to signals emitted by other items, which may not have existed in the layout
+ at the time readXml() was called. E.g. a scalebar can use this to connect to its linked
+ map item after restoration from XML.
+.. seealso:: :py:func:`readXml()`
 %End
 
   public slots:
@@ -338,6 +339,13 @@ class QgsLayoutMultiFrame: QgsLayoutObject, QgsLayoutUndoObjectInterface
  \param document DOM document
  \param context read write context
 .. seealso:: :py:func:`writePropertiesToElement()`
+
+ Note that item subclasses should not rely on all other items being present in the
+ layout at the time this method is called. Instead, any connections and links to
+ other items must be made in the finalizeRestoreFromXml() method. E.g. when restoring
+ a scalebar, the connection to the linked map's signals should be implemented
+ in finalizeRestoreFromXml(), not readPropertiesFromElement().
+
 .. seealso:: :py:func:`readXml()`
  :rtype: bool
 %End

python/core/layout/qgslayoutpagecollection.sip

@@ -145,7 +145,7 @@ class QgsLayoutPageCollection : QObject, QgsLayoutSerializableObject
 
  Calling deletePage() automatically triggers a reflow() of pages.
 
-.. seealso:: clear()
+.. seealso:: :py:func:`clear()`
 %End
 
     void deletePage( QgsLayoutItemPage *page );
@@ -155,13 +155,13 @@ class QgsLayoutPageCollection : QObject, QgsLayoutSerializableObject
 
  Calling deletePage() automatically triggers a reflow() of pages.
 
-.. seealso:: clear()
+.. seealso:: :py:func:`clear()`
 %End
 
     void clear();
 %Docstring
  Removes all pages from the collection.
-.. seealso:: deletePage()
+.. seealso:: :py:func:`deletePage()`
 %End
 
     QgsLayoutItemPage *takePage( QgsLayoutItemPage *page ) /TransferBack/;