QGIS/python/core/auto_generated/layout/qgslayout.sip.in

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/layout/qgslayout.h                                          *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/



class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator, QgsLayoutUndoObjectInterface
{
%Docstring(signature="appended")
Base class for layouts, which can contain items such as maps, labels, scalebars, etc.

While the raw QGraphicsScene API can be used to render the contents of a :py:class:`QgsLayout`
to a QPainter, it is recommended to instead use a :py:class:`QgsLayoutExporter` to handle rendering
layouts instead. :py:class:`QgsLayoutExporter` automatically takes care of the intracacies of
preparing the layout and paint devices for correct exports, respecting various
user settings such as the layout context DPI.

.. versionadded:: 3.0
%End

%TypeHeaderCode
#include "qgslayout.h"
%End
  public:

    enum ZValues
    {
      ZPage,
      ZItem,
      ZGrid,
      ZGuide,
      ZSmartGuide,
      ZMouseHandles,
      ZViewTool,
      ZSnapIndicator,
    };

    enum UndoCommand
    {
      UndoLayoutDpi,
      UndoNone,
    };

    QgsLayout( QgsProject *project );
%Docstring
Construct a new layout linked to the specified ``project``.

If the layout is a "new" layout (as opposed to a layout which will
restore a previous state from XML) then :py:func:`~QgsLayout.initializeDefaults` should be
called on the new layout.
%End

    ~QgsLayout();

    QgsLayout *clone() const /Factory/;
%Docstring
Creates a clone of the layout. Ownership of the return layout
is transferred to the caller.
%End

    void initializeDefaults();
%Docstring
Initializes an empty layout, e.g. by adding a default page to the layout. This should be called after creating
a new layout.
%End

    void clear();
%Docstring
Clears the layout.

Calling this method removes all items and pages from the layout.
%End

    QgsProject *project() const;
%Docstring
The project associated with the layout. Used to get access to layers, map themes,
relations and various other bits. It is never ``None``.
%End

    QgsLayoutModel *itemsModel();
%Docstring
Returns the items model attached to the layout.
%End



    QList<QgsLayoutItem *> selectedLayoutItems( bool includeLockedItems = true );
%Docstring
Returns list of selected layout items.

If ``includeLockedItems`` is set to ``True``, then locked items will also be included
in the returned list.
%End

    void setSelectedItem( QgsLayoutItem *item );
%Docstring
Clears any selected items and sets ``item`` as the current selection.
%End

    void deselectAll();
%Docstring
Clears any selected items in the layout.

Call this method rather than QGraphicsScene.clearSelection, as the latter does
not correctly emit signals to allow the layout's model to update.
%End

    bool raiseItem( QgsLayoutItem *item, bool deferUpdate = false );
%Docstring
Raises an ``item`` up the z-order.
Returns ``True`` if the item was successfully raised.

If ``deferUpdate`` is ``True``, the scene will not be visibly updated
to reflect the new stacking order. This allows multiple
:py:func:`~QgsLayout.raiseItem` calls to be made in sequence without the cost of
updating the scene for each one.

.. seealso:: :py:func:`lowerItem`

.. seealso:: :py:func:`updateZValues`
%End

    bool lowerItem( QgsLayoutItem *item, bool deferUpdate = false );
%Docstring
Lowers an ``item`` down the z-order.
Returns ``True`` if the item was successfully lowered.

If ``deferUpdate`` is ``True``, the scene will not be visibly updated
to reflect the new stacking order. This allows multiple
:py:func:`~QgsLayout.raiseItem` calls to be made in sequence without the cost of
updating the scene for each one.

.. seealso:: :py:func:`raiseItem`

.. seealso:: :py:func:`updateZValues`
%End

    bool moveItemToTop( QgsLayoutItem *item, bool deferUpdate = false );
%Docstring
Raises an ``item`` up to the top of the z-order.
Returns ``True`` if the item was successfully raised.

If ``deferUpdate`` is ``True``, the scene will not be visibly updated
to reflect the new stacking order. This allows multiple
:py:func:`~QgsLayout.raiseItem` calls to be made in sequence without the cost of
updating the scene for each one.

.. seealso:: :py:func:`moveItemToBottom`

.. seealso:: :py:func:`updateZValues`
%End

    bool moveItemToBottom( QgsLayoutItem *item, bool deferUpdate = false );
%Docstring
Lowers an ``item`` down to the bottom of the z-order.
Returns ``True`` if the item was successfully lowered.
If ``deferUpdate`` is ``True``, the scene will not be visibly updated
to reflect the new stacking order. This allows multiple
:py:func:`~QgsLayout.raiseItem` calls to be made in sequence without the cost of
updating the scene for each one.

.. seealso:: :py:func:`moveItemToTop`

.. seealso:: :py:func:`updateZValues`
%End

    void updateZValues( bool addUndoCommands = true );
%Docstring
Resets the z-values of items based on their position in the internal
z order list. This should be called after any stacking changes
which deferred z-order updates.
%End

    QgsLayoutItem *itemByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
%Docstring
Returns the layout item with matching ``uuid`` unique identifier, or ``None``
if a matching item could not be found.

If ``includeTemplateUuids`` is ``True``, then item's template UUID
will also be tested when trying to match the uuid. This may differ from the item's UUID
for items which have been added to an existing layout from a template. In this case
the template UUID returns the original item UUID at the time the template was created,
vs the item's :py:func:`~QgsLayout.uuid` which returns the current instance of the item's unique identifier.
Note that template UUIDs are only available while a layout is being restored from XML.

.. seealso:: :py:func:`itemByTemplateUuid`

.. seealso:: :py:func:`multiFrameByUuid`

.. seealso:: :py:func:`itemById`
%End

    QgsLayoutItem *itemByTemplateUuid( const QString &uuid ) const;
%Docstring
Returns the layout item with matching template ``uuid`` unique identifier, or ``None``
if a matching item could not be found. Unlike :py:func:`~QgsLayout.itemByUuid`, this method ONLY checks
template UUIDs for a match.

Template UUIDs are valid only for items which have been added to an existing layout from a template. In this case
the template UUID is the original item UUID at the time the template was created,
vs the item's :py:func:`~QgsLayout.uuid` which returns the current instance of the item's unique identifier.

Note that template UUIDs are only available while a layout is being restored from XML.

.. seealso:: :py:func:`itemByUuid`

.. seealso:: :py:func:`multiFrameByUuid`

.. seealso:: :py:func:`itemById`
%End

    QgsLayoutItem *itemById( const QString &id ) const;
%Docstring
Returns a layout item given its ``id``.
Since item IDs are not necessarely unique, this function returns the first matching
item found.

.. seealso:: :py:func:`itemByUuid`
%End

    QgsLayoutMultiFrame *multiFrameByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
%Docstring
Returns the layout multiframe with matching ``uuid`` unique identifier, or ``None``
if a matching multiframe could not be found.

If ``includeTemplateUuids`` is ``True``, then the multiframe's :py:func:`QgsLayoutMultiFrame.templateUuid()`
will also be tested when trying to match the uuid. Template UUIDs are valid only for items
which have been added to an existing layout from a template. In this case
the template UUID is the original item UUID at the time the template was created,
vs the item's :py:func:`~QgsLayout.uuid` which returns the current instance of the item's unique identifier.
Note that template UUIDs are only available while a layout is being restored from XML.

.. seealso:: :py:func:`itemByUuid`
%End

    QgsLayoutItem *layoutItemAt( QPointF position, bool ignoreLocked = false ) const;
%Docstring
Returns the topmost layout item at a specified ``position``. Ignores paper items.
If ``ignoreLocked`` is set to ``True`` any locked items will be ignored.
%End

    QgsLayoutItem *layoutItemAt( QPointF position, const QgsLayoutItem *belowItem, bool ignoreLocked = false ) const;
%Docstring
Returns the topmost layout item at a specified ``position`` which is below a specified ``item``. Ignores paper items.
If ``ignoreLocked`` is set to ``True`` any locked items will be ignored.
%End

    void setUnits( QgsUnitTypes::LayoutUnit units );
%Docstring
Sets the native measurement ``units`` for the layout. These also form the default unit
for measurements for the layout.

.. seealso:: :py:func:`units`

.. seealso:: :py:func:`convertToLayoutUnits`
%End

    QgsUnitTypes::LayoutUnit units() const;
%Docstring
Returns the native units for the layout.

.. seealso:: :py:func:`setUnits`

.. seealso:: :py:func:`convertToLayoutUnits`
%End

    double convertToLayoutUnits( QgsLayoutMeasurement measurement ) const;
%Docstring
Converts a measurement into the layout's native units.

:return: length of measurement in layout units

.. seealso:: :py:func:`convertFromLayoutUnits`

.. seealso:: :py:func:`units`
%End

    QSizeF convertToLayoutUnits( const QgsLayoutSize &size ) const;
%Docstring
Converts a size into the layout's native units.

:return: size of measurement in layout units

.. seealso:: :py:func:`convertFromLayoutUnits`

.. seealso:: :py:func:`units`
%End

    QPointF convertToLayoutUnits( const QgsLayoutPoint &point ) const;
%Docstring
Converts a ``point`` into the layout's native units.

:return: point in layout units

.. seealso:: :py:func:`convertFromLayoutUnits`

.. seealso:: :py:func:`units`
%End

    QgsLayoutMeasurement convertFromLayoutUnits( double length, QgsUnitTypes::LayoutUnit unit ) const;
%Docstring
Converts a ``length`` measurement from the layout's native units to a specified target ``unit``.

:return: length of measurement in specified units

.. seealso:: :py:func:`convertToLayoutUnits`

.. seealso:: :py:func:`units`
%End

    QgsLayoutSize convertFromLayoutUnits( QSizeF size, QgsUnitTypes::LayoutUnit unit ) const;
%Docstring
Converts a ``size`` from the layout's native units to a specified target ``unit``.

:return: size of measurement in specified units

.. seealso:: :py:func:`convertToLayoutUnits`

.. seealso:: :py:func:`units`
%End

    QgsLayoutPoint convertFromLayoutUnits( QPointF point, QgsUnitTypes::LayoutUnit unit ) const;
%Docstring
Converts a ``point`` from the layout's native units to a specified target ``unit``.

:return: point in specified units

.. seealso:: :py:func:`convertToLayoutUnits`

.. seealso:: :py:func:`units`
%End

    QgsLayoutRenderContext &renderContext();
%Docstring
Returns a reference to the layout's render context, which stores information relating to the
current rendering settings for the layout.
%End


    QgsLayoutReportContext &reportContext();
%Docstring
Returns a reference to the layout's report context, which stores information relating to the
current reporting context for the layout.
%End


    QgsLayoutSnapper &snapper();
%Docstring
Returns a reference to the layout's snapper, which stores handles layout snap grids and lines
and snapping points to the nearest matching point.
%End


    QgsLayoutGridSettings &gridSettings();
%Docstring
Returns a reference to the layout's grid settings, which stores settings relating
to grid appearance, spacing and offsets.
%End


    void reloadSettings();
%Docstring
Refreshes the layout when global layout related options change.
%End

    QgsLayoutGuideCollection &guides();
%Docstring
Returns a reference to the layout's guide collection, which manages page snap guides.
%End


    virtual QgsExpressionContext createExpressionContext() const;

%Docstring
Creates an expression context relating to the layout's current state. The context includes
scopes for global, project, layout and layout context properties.
%End

    void setCustomProperty( const QString &key, const QVariant &value );
%Docstring
Set a custom property for the layout.

:param key: property key. If a property with the same key already exists it will be overwritten.
:param value: property value

.. seealso:: :py:func:`customProperty`

.. seealso:: :py:func:`removeCustomProperty`

.. seealso:: :py:func:`customProperties`
%End

    QVariant customProperty( const QString &key, const QVariant &defaultValue = QVariant() ) const;
%Docstring
Read a custom property from the layout.

:param key: property key
:param defaultValue: default value to return if property with matching key does not exist

:return: value of matching property

.. seealso:: :py:func:`setCustomProperty`

.. seealso:: :py:func:`removeCustomProperty`

.. seealso:: :py:func:`customProperties`
%End

    void removeCustomProperty( const QString &key );
%Docstring
Remove a custom property from the layout.

:param key: property key

.. seealso:: :py:func:`setCustomProperty`

.. seealso:: :py:func:`customProperty`

.. seealso:: :py:func:`customProperties`
%End

    QStringList customProperties() const;
%Docstring
Returns list of keys stored in custom properties for the layout.

.. seealso:: :py:func:`setCustomProperty`

.. seealso:: :py:func:`customProperty`

.. seealso:: :py:func:`removeCustomProperty`
%End

    QgsLayoutItemMap *referenceMap() const;
%Docstring
Returns the map item which will be used to generate corresponding world files when the
layout is exported. If no map was explicitly set via :py:func:`~QgsLayout.setReferenceMap`, the largest
map in the layout will be returned (or ``None`` if there are no maps in the layout).

.. seealso:: :py:func:`setReferenceMap`
%End

    void setReferenceMap( QgsLayoutItemMap *map );
%Docstring
Sets the ``map`` item which will be used to generate corresponding world files when the
layout is exported.

.. seealso:: :py:func:`referenceMap`
%End

    QgsLayoutPageCollection *pageCollection();
%Docstring
Returns a pointer to the layout's page collection, which stores and manages
page items in the layout.
%End


    QRectF layoutBounds( bool ignorePages = false, double margin = 0.0 ) const;
%Docstring
Calculates the bounds of all non-gui items in the layout. Ignores snap lines, mouse handles
and other cosmetic items.

:param ignorePages: set to ``True`` to ignore page items
:param margin: optional marginal (in percent, e.g., 0.05 = 5% ) to add around items

:return: layout bounds, in layout units.

.. seealso:: :py:func:`pageItemBounds`
%End

    QRectF pageItemBounds( int page, bool visibleOnly = false ) const;
%Docstring
Returns the bounding box of the items contained on a specified ``page``.
A page number of 0 represents the first page in the layout.

Set ``visibleOnly`` to ``True`` to only include visible items.

The returned bounds are in layout units.

.. seealso:: :py:func:`layoutBounds`
%End

    void addLayoutItem( QgsLayoutItem *item /Transfer/ );
%Docstring
Adds an ``item`` to the layout. This should be called instead of the base class :py:func:`~QgsLayout.addItem`
method. Ownership of the item is transferred to the layout.
%End

    void removeLayoutItem( QgsLayoutItem *item );
%Docstring
Removes an ``item`` from the layout. This should be called instead of the base class :py:func:`~QgsLayout.removeItem`
method.
The item will also be deleted.
%End

    void addMultiFrame( QgsLayoutMultiFrame *multiFrame /Transfer/ );
%Docstring
Adds a ``multiFrame`` to the layout. The object is owned by the layout until :py:func:`~QgsLayout.removeMultiFrame` is called.

.. seealso:: :py:func:`removeMultiFrame`

.. seealso:: :py:func:`multiFrames`
%End

    void removeMultiFrame( QgsLayoutMultiFrame *multiFrame );
%Docstring
Removes a ``multiFrame`` from the layout (but does not delete it).

.. seealso:: :py:func:`addMultiFrame`

.. seealso:: :py:func:`multiFrames`
%End

    QList< QgsLayoutMultiFrame * > multiFrames() const;
%Docstring
Returns a list of multi frames contained in the layout.

.. seealso:: :py:func:`addMultiFrame`

.. seealso:: :py:func:`removeMultiFrame`
%End

    bool saveAsTemplate( const QString &path, const QgsReadWriteContext &context ) const;
%Docstring
Saves the layout as a template at the given file ``path``.
Returns ``True`` if save was successful.

.. seealso:: :py:func:`loadFromTemplate`
%End

    QList< QgsLayoutItem * > loadFromTemplate( const QDomDocument &document, const QgsReadWriteContext &context, bool clearExisting = true, bool *ok /Out/ = 0 );
%Docstring
Load a layout template ``document``.

By default this method will clear all items from the existing layout and real all layout
settings from the template. Setting ``clearExisting`` to ``False`` will only add new items
from the template, without overwriting the existing items or layout settings.

If ``ok`` is specified, it will be set to ``True`` if the load was successful.

Returns a list of loaded items.
%End

    virtual QDomElement writeXml( QDomDocument &document, const QgsReadWriteContext &context ) const;
%Docstring
Returns the layout's state encapsulated in a DOM element.

.. seealso:: :py:func:`readXml`
%End

    virtual bool readXml( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );
%Docstring
Sets the collection's state from a DOM element. ``layoutElement`` is the DOM node corresponding to the layout.

.. seealso:: :py:func:`writeXml`
%End

    QList< QgsLayoutItem * > addItemsFromXml( const QDomElement &parentElement, const QDomDocument &document,
        const QgsReadWriteContext &context,
        QPointF *position = 0, bool pasteInPlace = false );
%Docstring
Add items from an XML representation to the layout. Used for project file reading and pasting items from clipboard.

The ``position`` argument is optional, and if it is not specified the items will be restored to their
original position from the XML serialization. If specified, the items will be positioned such that the top-left
bounds of all added items is located at this ``position``.

The ``pasteInPlace`` argument determines whether the serialized position should be respected, but remapped to the
origin of the page corresponding to the page at ``position``.

A list of the newly added items is returned.
%End

    QgsLayoutUndoStack *undoStack();
%Docstring
Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout
and it's associated objects.
%End


    virtual QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id = 0, QUndoCommand *parent = 0 ) /Factory/;


    QgsLayoutItemGroup *groupItems( const QList<QgsLayoutItem *> &items );
%Docstring
Creates a new group from a list of layout ``items`` and adds the group to the layout.
If grouping was not possible, ``None`` will be returned.

.. seealso:: :py:func:`ungroupItems`
%End

    QList<QgsLayoutItem *> ungroupItems( QgsLayoutItemGroup *group );
%Docstring
Ungroups items by removing them from an item ``group`` and removing the group from the
layout. Child items will remain in the layout and will not be deleted.

Returns a list of the items removed from the group, or an empty list if ungrouping
was not successful.

.. seealso:: :py:func:`groupItems`
%End

    bool accept( QgsStyleEntityVisitorInterface *visitor ) const;
%Docstring
Accepts the specified style entity ``visitor``, causing it to visit all style entities associated
with the layout.

Returns ``True`` if the visitor should continue visiting other objects, or ``False`` if visiting
should be canceled.

.. versionadded:: 3.10
%End

    struct Settings
    {
      const QgsSettingsEntryStringList searchPathForTemplates;
    };

  public slots:

    void refresh();
%Docstring
Forces the layout, and all items contained within it, to refresh. For instance, this causes maps to redraw
and rebuild cached images, html items to reload their source url, and attribute tables
to refresh their contents. Calling this also triggers a recalculation of all data defined
attributes within the layout.

.. seealso:: :py:func:`refreshed`
%End

    void updateBounds();
%Docstring
Updates the scene bounds of the layout.
%End

  signals:

    void changed();
%Docstring
Emitted when properties of the layout change. This signal is only
emitted for settings directly managed by the layout, and is not emitted
when child items change.
%End

    void variablesChanged();
%Docstring
Emitted whenever the expression variables stored in the layout have been changed.
%End

    void selectedItemChanged( QgsLayoutItem *selected );
%Docstring
Emitted whenever the selected item changes.
If ``None``, no item is selected.
%End

    void refreshed();
%Docstring
Emitted when the layout has been refreshed and items should also be refreshed
and updated.
%End

    void backgroundTaskCountChanged( int total );
%Docstring
Emitted whenever the ``total`` number of background tasks running in items from the layout changes.

.. versionadded:: 3.10
%End

};

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/layout/qgslayout.h                                          *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/