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.py 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.
%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, double searchTolerance = 0 ) 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. Since QGIS 3.34 the ``searchTolerance`` parameter was
added, which can be used to specify a search tolerance in layout units.
%End

    QgsLayoutItem *layoutItemAt( QPointF position, const QgsLayoutItem *belowItem, bool ignoreLocked = false, double searchTolerance = 0 ) 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. Since QGIS 3.34 the
``searchTolerance`` parameter was added, which can be used to specify a
search tolerance in layout units.
%End

    void setUnits( Qgis::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

    Qgis::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, Qgis::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, Qgis::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, Qgis::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


  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

    void itemAdded( QgsLayoutItem *item );
%Docstring
Emitted when an ``item`` was added to the layout.

.. versionadded:: 3.20
%End

};

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