QgsLayout class

Base class for layouts, which can contain items such as maps, labels, scalebars, etc.

Reference

While the raw QGraphicsScene API can be used to render the contents of a QgsLayout to a QPainter, it is recommended to instead use a QgsLayoutExporter to handle rendering layouts instead. 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.

Base classes

class QgsExpressionContextGenerator: Abstract interface for generating an expression context.
class QgsLayoutUndoObjectInterface: Interface for layout objects which support undo/redo commands.

Derived classes

class QgsPrintLayout: Print layout, a QgsLayout subclass for static or atlas-based layouts.

Public types

enum UndoCommand { UndoLayoutDpi, UndoNone = -1 }: Layout undo commands, used for collapsing undo commands.
enum ZValues { ZPage = 0, ZItem = 1, ZGrid = 9997, ZGuide = 9998, ZSmartGuide = 9999, ZMouseHandles = 10000, ZViewTool = 10001, ZSnapIndicator = 10002 }: Preset item z-values, to ensure correct stacking.

Constructors, destructors, conversion operators

QgsLayout(QgsProject* project): Construct a new layout linked to the specified project.

Public functions

auto addItemsFromXml(const QDomElement& parentElement, const QDomDocument& document, const QgsReadWriteContext& context, QPointF* position = nullptr, bool pasteInPlace = false) -> QList<QgsLayoutItem*>: Add items from an XML representation to the layout.
void addLayoutItem(QgsLayoutItem* item): Adds an item to the layout.
void addMultiFrame(QgsLayoutMultiFrame* multiFrame): Adds a multiFrame to the layout.
void clear(): Clears the layout.
auto clone() const -> QgsLayout*: Creates a clone of the layout.
auto convertFromLayoutUnits(double length, QgsUnitTypes::LayoutUnit unit) const -> QgsLayoutMeasurement: Converts a length measurement from the layout's native units to a specified target unit.
auto convertFromLayoutUnits(QSizeF size, QgsUnitTypes::LayoutUnit unit) const -> QgsLayoutSize: Converts a size from the layout's native units to a specified target unit.
auto convertFromLayoutUnits(QPointF point, QgsUnitTypes::LayoutUnit unit) const -> QgsLayoutPoint: Converts a point from the layout's native units to a specified target unit.
auto convertToLayoutUnits(QgsLayoutMeasurement measurement) const -> double: Converts a measurement into the layout's native units.
auto convertToLayoutUnits(const QgsLayoutSize& size) const -> QSizeF: Converts a size into the layout's native units.
auto convertToLayoutUnits(const QgsLayoutPoint& point) const -> QPointF: Converts a point into the layout's native units.
auto createCommand(const QString& text, int id = 0, QUndoCommand* parent = nullptr) -> QgsAbstractLayoutUndoCommand* override: Creates a new layout undo command with the specified text and parent.
auto createExpressionContext() const -> QgsExpressionContext override: Creates an expression context relating to the layout's current state.
auto customProperties() const -> QStringList: Returns list of keys stored in custom properties for the layout.
auto customProperty(const QString& key, const QVariant& defaultValue = QVariant()) const -> QVariant: Read a custom property from the layout.
void deselectAll(): Clears any selected items in the layout.
auto gridSettings() -> QgsLayoutGridSettings&: Returns a reference to the layout's grid settings, which stores settings relating to grid appearance, spacing and offsets.
auto gridSettings() const -> const QgsLayoutGridSettings&: Returns a reference to the layout's grid settings, which stores settings relating to grid appearance, spacing and offsets.
auto groupItems(const QList<QgsLayoutItem*>& items) -> QgsLayoutItemGroup*: Creates a new group from a list of layout items and adds the group to the layout.
auto guides() -> QgsLayoutGuideCollection&: Returns a reference to the layout's guide collection, which manages page snap guides.
auto guides() const -> const QgsLayoutGuideCollection&: Returns a reference to the layout's guide collection, which manages page snap guides.
void initializeDefaults(): Initializes an empty layout, e.g.
auto itemById(const QString& id) const -> QgsLayoutItem*: Returns a layout item given its id.
auto itemByTemplateUuid(const QString& uuid) const -> QgsLayoutItem*: Returns the layout item with matching template uuid unique identifier, or a nullptr if a matching item could not be found.
auto itemByUuid(const QString& uuid, bool includeTemplateUuids = false) const -> QgsLayoutItem*: Returns the layout item with matching uuid unique identifier, or a nullptr if a matching item could not be found.
auto itemsModel() -> QgsLayoutModel*: Returns the items model attached to the layout.
auto layoutBounds(bool ignorePages = false, double margin = 0.0) const -> QRectF: Calculates the bounds of all non-gui items in the layout.
auto layoutItemAt(QPointF position, bool ignoreLocked = false) const -> QgsLayoutItem*: Returns the topmost layout item at a specified position.
auto layoutItemAt(QPointF position, const QgsLayoutItem* belowItem, bool ignoreLocked = false) const -> QgsLayoutItem*: Returns the topmost layout item at a specified position which is below a specified item.
template<class T> void layoutItems(QList<T*>& itemList) const: Returns a list of layout items of a specific type.
template<class T> void layoutObjects(QList<T*>& objectList) const: Returns a list of layout objects (items and multiframes) of a specific type.
auto loadFromTemplate(const QDomDocument& document, const QgsReadWriteContext& context, bool clearExisting = true, bool* ok = nullptr) -> QList<QgsLayoutItem*>: Load a layout template document.
auto lowerItem(QgsLayoutItem* item, bool deferUpdate = false) -> bool: Lowers an item down the z-order.
auto moveItemToBottom(QgsLayoutItem* item, bool deferUpdate = false) -> bool: Lowers an item down to the bottom of the z-order.
auto moveItemToTop(QgsLayoutItem* item, bool deferUpdate = false) -> bool: Raises an item up to the top of the z-order.
auto multiFrameByUuid(const QString& uuid, bool includeTemplateUuids = false) const -> QgsLayoutMultiFrame*: Returns the layout multiframe with matching uuid unique identifier, or a nullptr if a matching multiframe could not be found.
auto multiFrames() const -> QList<QgsLayoutMultiFrame*>: Returns a list of multi frames contained in the layout.
auto pageCollection() -> QgsLayoutPageCollection*: Returns a pointer to the layout's page collection, which stores and manages page items in the layout.
auto pageCollection() const -> const QgsLayoutPageCollection*: Returns a pointer to the layout's page collection, which stores and manages page items in the layout.
auto pageItemBounds(int page, bool visibleOnly = false) const -> QRectF: Returns the bounding box of the items contained on a specified page.
auto project() const -> QgsProject*: The project associated with the layout.
auto raiseItem(QgsLayoutItem* item, bool deferUpdate = false) -> bool: Raises an item up the z-order.
auto readXml(const QDomElement& layoutElement, const QDomDocument& document, const QgsReadWriteContext& context) -> bool virtual: Sets the collection's state from a DOM element.
auto referenceMap() const -> QgsLayoutItemMap*: Returns the map item which will be used to generate corresponding world files when the layout is exported.
void reloadSettings(): Refreshes the layout when global layout related options change.
void removeCustomProperty(const QString& key): Remove a custom property from the layout.
void removeLayoutItem(QgsLayoutItem* item): Removes an item from the layout.
void removeMultiFrame(QgsLayoutMultiFrame* multiFrame): Removes a multiFrame from the layout (but does not delete it).
auto renderContext() -> QgsLayoutRenderContext&: Returns a reference to the layout's render context, which stores information relating to the current rendering settings for the layout.
auto renderContext() const -> const QgsLayoutRenderContext&: Returns a reference to the layout's render context, which stores information relating to the current rendering settings for the layout.
auto reportContext() -> QgsLayoutReportContext&: Returns a reference to the layout's report context, which stores information relating to the current reporting context for the layout.
auto reportContext() const -> const QgsLayoutReportContext&: Returns a reference to the layout's report context, which stores information relating to the current reporting context for the layout.
auto saveAsTemplate(const QString& path, const QgsReadWriteContext& context) const -> bool: Saves the layout as a template at the given file path.
auto selectedLayoutItems(bool includeLockedItems = true) -> QList<QgsLayoutItem*>: Returns list of selected layout items.
void setCustomProperty(const QString& key, const QVariant& value): Set a custom property for the layout.
void setReferenceMap(QgsLayoutItemMap* map): Sets the map item which will be used to generate corresponding world files when the layout is exported.
void setSelectedItem(QgsLayoutItem* item): Clears any selected items and sets item as the current selection.
void setUnits(QgsUnitTypes::LayoutUnit units): Sets the native measurement units for the layout.
auto snapper() -> QgsLayoutSnapper&: Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and snapping points to the nearest matching point.
auto snapper() const -> const QgsLayoutSnapper&: Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and snapping points to the nearest matching point.
auto undoStack() -> QgsLayoutUndoStack*: Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout and it's associated objects.
auto undoStack() const -> const QgsLayoutUndoStack*: Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout and it's associated objects.
auto ungroupItems(QgsLayoutItemGroup* group) -> QList<QgsLayoutItem*>: Ungroups items by removing them from an item group and removing the group from the layout.
auto units() const -> QgsUnitTypes::LayoutUnit: Returns the native units for the layout.
void updateZValues(bool addUndoCommands = true): Resets the z-values of items based on their position in the internal z order list.
auto writeXml(QDomDocument& document, const QgsReadWriteContext& context) const -> QDomElement virtual: Returns the layout's state encapsulated in a DOM element.

Signals

void changed(): Is emitted when properties of the layout change.
void refreshed(): Is emitted when the layout has been refreshed and items should also be refreshed and updated.
void selectedItemChanged(QgsLayoutItem* selected): Emitted whenever the selected item changes.
void variablesChanged(): Emitted whenever the expression variables stored in the layout have been changed.

Public slots

void refresh(): Forces the layout, and all items contained within it, to refresh.
void updateBounds(): Updates the scene bounds of the layout.

Enum documentation

enum QgsLayout::UndoCommand

Layout undo commands, used for collapsing undo commands.

Enumerators
UndoLayoutDpi	Change layout default DPI.
UndoNone	No command suppression.

enum QgsLayout::ZValues

Preset item z-values, to ensure correct stacking.

Enumerators
ZPage	Z-value for page (paper) items.
ZItem	Minimum z value for items.
ZGrid	Z-value for page grids.
ZGuide	Z-value for page guides.
ZSmartGuide	Z-value for smart (item bounds based) guides.
ZMouseHandles	Z-value for mouse handles.
ZViewTool	Z-value for temporary view tool items.
ZSnapIndicator	Z-value for snapping indicator.

Function documentation

QgsLayout::QgsLayout(QgsProject* project)

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 initializeDefaults() should be called on the new layout.

QList<QgsLayoutItem> QgsLayout::addItemsFromXml(const QDomElement& parentElement, const QDomDocument& document, const QgsReadWriteContext& context, QPointF position = nullptr, bool pasteInPlace = false)

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.

void QgsLayout::addLayoutItem(QgsLayoutItem* item)

Adds an item to the layout.

This should be called instead of the base class addItem() method. Ownership of the item is transferred to the layout.

void QgsLayout::addMultiFrame(QgsLayoutMultiFrame* multiFrame)

Adds a multiFrame to the layout.

The object is owned by the layout until removeMultiFrame() is called.

void QgsLayout::clear()

Clears the layout.

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

QgsLayout* QgsLayout::clone() const

Creates a clone of the layout.

Ownership of the return layout is transferred to the caller.

QgsLayoutMeasurement QgsLayout::convertFromLayoutUnits(double length, QgsUnitTypes::LayoutUnit unit) const

Converts a length measurement from the layout's native units to a specified target unit.

Returns	length of measurement in specified units

QgsLayoutSize QgsLayout::convertFromLayoutUnits(QSizeF size, QgsUnitTypes::LayoutUnit unit) const

Converts a size from the layout's native units to a specified target unit.

Returns	size of measurement in specified units

QgsLayoutPoint QgsLayout::convertFromLayoutUnits(QPointF point, QgsUnitTypes::LayoutUnit unit) const

Converts a point from the layout's native units to a specified target unit.

Returns	point in specified units

double QgsLayout::convertToLayoutUnits(QgsLayoutMeasurement measurement) const

Converts a measurement into the layout's native units.

Returns	length of measurement in layout units

QSizeF QgsLayout::convertToLayoutUnits(const QgsLayoutSize& size) const

Converts a size into the layout's native units.

Returns	size of measurement in layout units

QPointF QgsLayout::convertToLayoutUnits(const QgsLayoutPoint& point) const

Converts a point into the layout's native units.

Returns	point in layout units

QgsAbstractLayoutUndoCommand* QgsLayout::createCommand(const QString& text, int id = 0, QUndoCommand* parent = nullptr) override

Creates a new layout undo command with the specified text and parent.

The id argument can be used to specify an id number for the source event - this is used to determine whether QUndoCommand command compression can apply to the command.

QgsExpressionContext QgsLayout::createExpressionContext() const override

Creates an expression context relating to the layout's current state.

The context includes scopes for global, project, layout and layout context properties.

QStringList QgsLayout::customProperties() const

Returns list of keys stored in custom properties for the layout.

QVariant QgsLayout::customProperty(const QString& key, const QVariant& defaultValue = QVariant()) const

Read a custom property from the layout.

Parameters
key	property key
defaultValue	default value to return if property with matching key does not exist
Returns	value of matching property

void QgsLayout::deselectAll()

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.

QgsLayoutItemGroup* QgsLayout::groupItems(const QList<QgsLayoutItem*>& items)

Creates a new group from a list of layout items and adds the group to the layout.

If grouping was not possible, a nullptr will be returned.

void QgsLayout::initializeDefaults()

Initializes an empty layout, e.g.

by adding a default page to the layout. This should be called after creating a new layout.

QgsLayoutItem* QgsLayout::itemById(const QString& id) const

Returns a layout item given its id.

Since item IDs are not necessarely unique, this function returns the first matching item found.

QgsLayoutItem* QgsLayout::itemByTemplateUuid(const QString& uuid) const

Returns the layout item with matching template uuid unique identifier, or a nullptr if a matching item could not be found.

Unlike 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 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.

QgsLayoutItem* QgsLayout::itemByUuid(const QString& uuid, bool includeTemplateUuids = false) const

Returns the layout item with matching uuid unique identifier, or a nullptr 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 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.

QRectF QgsLayout::layoutBounds(bool ignorePages = false, double margin = 0.0) const

Calculates the bounds of all non-gui items in the layout.

Parameters
ignorePages	set to true to ignore page items
margin	optional marginal (in percent, e.g., 0.05 = 5% ) to add around items
Returns	layout bounds, in layout units.

Ignores snap lines, mouse handles and other cosmetic items.

QgsLayoutItem* QgsLayout::layoutItemAt(QPointF position, bool ignoreLocked = false) const

Returns the topmost layout item at a specified position.

Ignores paper items. If ignoreLocked is set to true any locked items will be ignored.

QgsLayoutItem* QgsLayout::layoutItemAt(QPointF position, const QgsLayoutItem* belowItem, bool ignoreLocked = false) const

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.

template<class T>
void QgsLayout::layoutItems(QList<T*>& itemList) const

Returns a list of layout items of a specific type.

template<class T>
void QgsLayout::layoutObjects(QList<T*>& objectList) const

Returns a list of layout objects (items and multiframes) of a specific type.

QList<QgsLayoutItem> QgsLayout::loadFromTemplate(const QDomDocument& document, const QgsReadWriteContext& context, bool clearExisting = true, bool ok = nullptr)

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.

bool QgsLayout::lowerItem(QgsLayoutItem* item, bool deferUpdate = false)

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 raiseItem() calls to be made in sequence without the cost of updating the scene for each one.

bool QgsLayout::moveItemToBottom(QgsLayoutItem* item, bool deferUpdate = false)

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 raiseItem() calls to be made in sequence without the cost of updating the scene for each one.

bool QgsLayout::moveItemToTop(QgsLayoutItem* item, bool deferUpdate = false)

Raises an item up to the top of the z-order.

Returns true if the item was successfully raised.

QgsLayoutMultiFrame* QgsLayout::multiFrameByUuid(const QString& uuid, bool includeTemplateUuids = false) const

Returns the layout multiframe with matching uuid unique identifier, or a nullptr if a matching multiframe could not be found.

If includeTemplateUuids is true, then the multiframe's 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 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.

QList<QgsLayoutMultiFrame*> QgsLayout::multiFrames() const

Returns a list of multi frames contained in the layout.

QRectF QgsLayout::pageItemBounds(int page, bool visibleOnly = false) const

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.

QgsProject* QgsLayout::project() const

The project associated with the layout.

Used to get access to layers, map themes, relations and various other bits. It is never null.

bool QgsLayout::raiseItem(QgsLayoutItem* item, bool deferUpdate = false)

Raises an item up the z-order.

Returns true if the item was successfully raised.

bool QgsLayout::readXml(const QDomElement& layoutElement, const QDomDocument& document, const QgsReadWriteContext& context) virtual

Sets the collection's state from a DOM element.

layoutElement is the DOM node corresponding to the layout.

QgsLayoutItemMap* QgsLayout::referenceMap() const

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 setReferenceMap(), the largest map in the layout will be returned (or nullptr if there are no maps in the layout).

void QgsLayout::removeCustomProperty(const QString& key)

Remove a custom property from the layout.

Parameters
key	property key

void QgsLayout::removeLayoutItem(QgsLayoutItem* item)

Removes an item from the layout.

This should be called instead of the base class removeItem() method. The item will also be deleted.

void QgsLayout::removeMultiFrame(QgsLayoutMultiFrame* multiFrame)

Removes a multiFrame from the layout (but does not delete it).

bool QgsLayout::saveAsTemplate(const QString& path, const QgsReadWriteContext& context) const

Saves the layout as a template at the given file path.

Returns true if save was successful.

QList<QgsLayoutItem*> QgsLayout::selectedLayoutItems(bool includeLockedItems = true)

Returns list of selected layout items.

If includeLockedItems is set to true, then locked items will also be included in the returned list.

void QgsLayout::setCustomProperty(const QString& key, const QVariant& value)

Set a custom property for the layout.

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

void QgsLayout::setReferenceMap(QgsLayoutItemMap* map)

Sets the map item which will be used to generate corresponding world files when the layout is exported.

void QgsLayout::setUnits(QgsUnitTypes::LayoutUnit units)

Sets the native measurement units for the layout.

These also form the default unit for measurements for the layout.

QList<QgsLayoutItem> QgsLayout::ungroupItems(QgsLayoutItemGroup group)

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.

QgsUnitTypes::LayoutUnit QgsLayout::units() const

Returns the native units for the layout.

void QgsLayout::updateZValues(bool addUndoCommands = true)

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.

QDomElement QgsLayout::writeXml(QDomDocument& document, const QgsReadWriteContext& context) const virtual

Returns the layout's state encapsulated in a DOM element.

void QgsLayout::changed() signal

Is 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.

void QgsLayout::selectedItemChanged(QgsLayoutItem* selected) signal

Emitted whenever the selected item changes.

If nullptr, no item is selected.

void QgsLayout::refresh() public slot

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.