Class: QgsLayout ¶

See also

Parameters:

length (float)
unit (Qgis.LayoutUnit)

convertFromLayoutUnits(self, size: QSizeF, unit: Qgis.LayoutUnit) → QgsLayoutSize[source]

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

Return type:: QgsLayoutSize
Returns:: size of measurement in specified units

See also

See also

Parameters:

size (QSizeF)
unit (Qgis.LayoutUnit)

convertFromLayoutUnits(self, point: QPointF | QPoint, unit: Qgis.LayoutUnit) → QgsLayoutPoint[source]

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

Return type:: QgsLayoutPoint
Returns:: point in specified units

See also

See also

convertFromLayoutUnits()

Parameters:

point (Union[QPointF, QPoint])
unit (Qgis.LayoutUnit)

convertToLayoutUnits(self, measurement: QgsLayoutMeasurement) → float[source]¶

Converts a measurement into the layout’s native units.

Return type:: float
Returns:: length of measurement in layout units

See also

See also

convertFromLayoutUnits()

Parameters:: measurement (QgsLayoutMeasurement)

convertToLayoutUnits(self, size: QgsLayoutSize) → QSizeF[source]

Converts a size into the layout’s native units.

Return type:: QSizeF
Returns:: size of measurement in layout units

See also

See also

convertFromLayoutUnits()

Parameters:: size (QgsLayoutSize)

convertToLayoutUnits(self, point: QgsLayoutPoint) → QPointF[source]

Converts a point into the layout’s native units.

Return type:: QPointF
Returns:: point in layout units

See also

See also

Parameters:: point (QgsLayoutPoint)

abstract createExpressionContext(self) → QgsExpressionContext[source]¶

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

Return type:: QgsExpressionContext

customProperties(self) → List[str][source]¶

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

See also

setCustomProperty()

See also

customProperty()

See also

removeCustomProperty()

Return type:: List[str]

customProperty(self, key: str | None, defaultValue: Any = None) → Any[source]¶

Read a custom property from the layout.

Parameters:

key (Optional[str]) – property key
defaultValue (Any = None) – default value to return if property with matching key does not exist

Return type:

Any

Returns:

value of matching property

See also

setCustomProperty()

See also

removeCustomProperty()

See also

customProperties()

deselectAll(self)[source]¶

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.

gridSettings(self) → QgsLayoutGridSettings¶

Returns a reference to the layout’s grid settings, which stores settings relating to grid appearance, spacing and offsets.

Return type:: QgsLayoutGridSettings

groupItems(self, items: Iterable[QgsLayoutItem]) → QgsLayoutItemGroup | None[source]¶

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.

See also

ungroupItems()

Parameters:: items (Iterable[QgsLayoutItem])
Return type:: Optional[QgsLayoutItemGroup]

guides(self) → QgsLayoutGuideCollection¶

Returns a reference to the layout’s guide collection, which manages page snap guides.

Return type:: QgsLayoutGuideCollection

initializeDefaults(self)[source]¶: Initializes an empty layout, e.g. by adding a default page to the layout. This should be called after creating a new layout.

signal itemAdded(item: QgsLayoutItem)[source]¶

Emitted when an item was added to the layout.

Added in version 3.20.

Parameters:: item (QgsLayoutItem)

itemById(self, id: str | None) → QgsLayoutItem | None[source]¶

Returns a layout item given its id. Since item IDs are not necessarely unique, this function returns the first matching item found.

See also

itemByUuid()

Parameters:: id (Optional[str])
Return type:: Optional[QgsLayoutItem]

itemByTemplateUuid(self, uuid: str | None) → QgsLayoutItem | None[source]¶

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

See also

itemByUuid()

See also

multiFrameByUuid()

See also

itemById()

Parameters:: uuid (Optional[str])
Return type:: Optional[QgsLayoutItem]

itemByUuid(self, uuid: str | None, includeTemplateUuids: bool = False) → QgsLayoutItem | None[source]¶

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

See also

itemByTemplateUuid()

See also

multiFrameByUuid()

See also

itemById()

Parameters:

uuid (Optional[str])
includeTemplateUuids (bool = False)

Return type:

Optional[QgsLayoutItem]

itemsModel(self) → QgsLayoutModel | None[source]¶

Returns the items model attached to the layout.

Return type:: Optional[QgsLayoutModel]

layoutBounds(self, ignorePages: bool = False, margin: float = 0) → QRectF[source]¶

Calculates the bounds of all non-gui items in the layout. Ignores snap lines, mouse handles and other cosmetic items.

Parameters:

ignorePages (bool = False) – set to True to ignore page items
margin (float = 0) – optional marginal (in percent, e.g., 0.05 = 5% ) to add around items

Return type:

QRectF

Returns:

layout bounds, in layout units.

See also

pageItemBounds()

layoutItemAt(self, position: QPointF | QPoint, ignoreLocked: bool = False, searchTolerance: float = 0) → QgsLayoutItem | None[source]¶

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.

Parameters:

position (Union[QPointF, QPoint])
ignoreLocked (bool = False)
searchTolerance (float = 0)

Return type:

Optional[QgsLayoutItem]

layoutItemAt(self, position: QPointF | QPoint, belowItem: QgsLayoutItem | None, ignoreLocked: bool = False, searchTolerance: float = 0) → QgsLayoutItem | None[source]

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.

Parameters:

position (Union[QPointF, QPoint])
belowItem (Optional[QgsLayoutItem])
ignoreLocked (bool = False)
searchTolerance (float = 0)

Return type:

Optional[QgsLayoutItem]

loadFromTemplate(self, document: QDomDocument, context: QgsReadWriteContext, clearExisting: bool = True)¶

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.

Parameters:

document (QDomDocument)
context (QgsReadWriteContext)
clearExisting (bool = True) -> (List[QgsLayoutItem])

lowerItem(self, item: QgsLayoutItem | None, deferUpdate: bool = False) → bool[source]¶

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.

See also

raiseItem()

See also

Parameters:

item (Optional[QgsLayoutItem])
deferUpdate (bool = False)

Return type:

bool

moveItemToBottom(self, item: QgsLayoutItem | None, deferUpdate: bool = False) → bool[source]¶

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.

See also

moveItemToTop()

See also

Parameters:

item (Optional[QgsLayoutItem])
deferUpdate (bool = False)

Return type:

bool

moveItemToTop(self, item: QgsLayoutItem | None, deferUpdate: bool = False) → bool[source]¶

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

See also

moveItemToBottom()

See also

Parameters:

item (Optional[QgsLayoutItem])
deferUpdate (bool = False)

Return type:

bool

multiFrameByUuid(self, uuid: str | None, includeTemplateUuids: bool = False) → QgsLayoutMultiFrame | None[source]¶

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

See also

itemByUuid()

Parameters:

uuid (Optional[str])
includeTemplateUuids (bool = False)

Return type:

Optional[QgsLayoutMultiFrame]

multiFrames(self) → List[QgsLayoutMultiFrame]¶

Returns a list of multi frames contained in the layout.

See also

addMultiFrame()

See also

removeMultiFrame()

Return type:: List[QgsLayoutMultiFrame]

pageCollection(self) → QgsLayoutPageCollection | None[source]¶

Returns a pointer to the layout’s page collection, which stores and manages page items in the layout.

Return type:: Optional[QgsLayoutPageCollection]

pageItemBounds(self, page: int, visibleOnly: bool = False) → QRectF[source]¶

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.

See also

layoutBounds()

Parameters:

page (int)
visibleOnly (bool = False)

Return type:

QRectF

project(self) → QgsProject | None[source]¶

The project associated with the layout. Used to get access to layers, map themes, relations and various other bits. It is never None.

Return type:: Optional[QgsProject]

raiseItem(self, item: QgsLayoutItem | None, deferUpdate: bool = False) → bool[source]¶

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

See also

lowerItem()

See also

Parameters:

item (Optional[QgsLayoutItem])
deferUpdate (bool = False)

Return type:

bool

virtual readXml(self, layoutElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool[source]¶

Sets the collection’s state from a DOM element. layoutElement is the DOM node corresponding to the layout.

See also

writeXml()

Parameters:

layoutElement (QDomElement)
document (QDomDocument)
context (QgsReadWriteContext)

Return type:

bool

referenceMap(self) → QgsLayoutItemMap | None[source]¶

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 None if there are no maps in the layout).

See also

setReferenceMap()

Return type:: Optional[QgsLayoutItemMap]

refresh(self)[source]¶: 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.

See also

refreshed()

signal refreshed[source]¶: Emitted when the layout has been refreshed and items should also be refreshed and updated.

reloadSettings(self)[source]¶: Refreshes the layout when global layout related options change.

removeCustomProperty(self, key: str | None)[source]¶

Remove a custom property from the layout.

Parameters:: key (Optional[str]) – property key

See also

setCustomProperty()

See also

customProperty()

See also

customProperties()

removeLayoutItem(self, item: QgsLayoutItem | None)[source]¶

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

Parameters:: item (Optional[QgsLayoutItem])

removeMultiFrame(self, multiFrame: QgsLayoutMultiFrame | None)[source]¶

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

See also

addMultiFrame()

See also

multiFrames()

Parameters:: multiFrame (Optional[QgsLayoutMultiFrame])

renderContext(self) → QgsLayoutRenderContext¶

Returns a reference to the layout’s render context, which stores information relating to the current rendering settings for the layout.

Return type:: QgsLayoutRenderContext

reportContext(self) → QgsLayoutReportContext¶

Returns a reference to the layout’s report context, which stores information relating to the current reporting context for the layout.

Return type:: QgsLayoutReportContext

saveAsTemplate(self, path: str | None, context: QgsReadWriteContext) → bool[source]¶

Saves the layout as a template at the given file path. Returns True if save was successful.

See also

loadFromTemplate()

Parameters:

path (Optional[str])
context (QgsReadWriteContext)

Return type:

bool

signal selectedItemChanged(selected: QgsLayoutItem)[source]¶

Emitted whenever the selected item changes. If None, no item is selected.

Parameters:: selected (QgsLayoutItem)

selectedLayoutItems(self, includeLockedItems: bool = True) → List[QgsLayoutItem]¶

Returns list of selected layout items.

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

Parameters:: includeLockedItems (bool = True)
Return type:: List[QgsLayoutItem]

setCustomProperty(self, key: str | None, value: Any)[source]¶

Set a custom property for the layout.

Parameters:

key (Optional[str]) – property key. If a property with the same key already exists it will be overwritten.
value (Any) – property value

See also

customProperty()

See also

removeCustomProperty()

See also

customProperties()

setReferenceMap(self, map: QgsLayoutItemMap | None)[source]¶

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

See also

referenceMap()

Parameters:: map (Optional[QgsLayoutItemMap])

setSelectedItem(self, item: QgsLayoutItem | None)[source]¶

Clears any selected items and sets item as the current selection.

Parameters:: item (Optional[QgsLayoutItem])

setUnits(self, units: Qgis.LayoutUnit)[source]¶

Sets the native measurement units for the layout. These also form the default unit for measurements for the layout.

See also

See also

Parameters:: units (Qgis.LayoutUnit)

snapper(self) → 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.

Return type:: QgsLayoutSnapper

undoStack(self) → QgsLayoutUndoStack | None[source]¶

Returns a pointer to the layout’s undo stack, which manages undo/redo states for the layout and it’s associated objects.

Return type:: Optional[QgsLayoutUndoStack]

ungroupItems(self, group: QgsLayoutItemGroup | None) → List[QgsLayoutItem]¶

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.

See also

groupItems()

Parameters:: group (Optional[QgsLayoutItemGroup])
Return type:: List[QgsLayoutItem]

units(self) → Qgis.LayoutUnit[source]¶

Returns the native units for the layout.

See also

setUnits()

See also