Class: QgsLayoutPageCollection¶

class qgis.core.QgsLayoutPageCollection¶

Bases: PyQt5.QtCore.QObject, QgsLayoutSerializableObject

A manager for a collection of pages in a layout.

New in version 3.0.

QgsLayoutPageCollection(layout: QgsLayout) Constructor for QgsLayoutItemPage, with the specified parent layout.

Methods

addPage

Adds a page to the collection.

beginPageSizeChange

Should be called before changing any page item sizes, and followed by a call to endPageSizeChange().

childEvent

clear

Removes all pages from the collection.

connectNotify

customEvent

deletePage

Deletes a page from the collection.

disconnectNotify

endPageSizeChange

Should be called after changing any page item sizes, and preceded by a call to beginPageSizeChange().

extendByNewPage

Adds a new page to the end of the collection.

guides

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

hasUniformPageSizes

Returns True if the layout has uniform page sizes, e.g.

insertPage

Inserts a page into a specific position in the collection.

isSignalConnected

itemsOnPage

Returns a list of layout items on the specified page index.

layout

rtype:

QgsLayout

maximumPageSize

Returns the maximum size of any page in the collection, by area.

maximumPageWidth

Returns the maximum width of pages in the collection.

page

Returns a specific page (by pageNumber) from the collection.

pageAtPoint

Returns the page at a specified point (in layout coordinates).

pageCount

Returns the number of pages in the collection.

pageIsEmpty

Returns whether a given page index is empty, ie, it contains no items except for the background paper item.

pageNumber

Returns the page number for the specified page, or -1 if the page is not contained in the collection.

pageNumberForPoint

Returns the page number corresponding to a point in the layout (in layout units).

pagePositionToAbsolute

Converts a position on a page to an absolute position in (maintaining the units from the input position).

pagePositionToLayoutPosition

Converts a position on a page to an absolute position in layout coordinates.

pageShadowWidth

Returns the size of the page shadow, in layout units.

pageStyleSymbol

Returns the symbol to use for drawing pages in the collection.

pages

Returns a list of pages in the collection.

positionOnPage

Returns the position within a page of a point in the layout (in layout units).

predictPageNumberForPoint

Returns the theoretical page number corresponding to a point in the layout (in layout units), assuming that enough pages exist in the layout to cover that point.

readXml

Sets the collection's state from a DOM element.

receivers

redraw

Triggers a redraw for all pages.

reflow

Forces the page collection to reflow the arrangement of pages, e.g.

resizeToContents

Resizes the layout to a single page which fits the current contents of the layout.

sender

senderSignalIndex

setPageStyleSymbol

Sets the symbol to use for drawing pages in the collection.

shouldExportPage

Returns whether the specified page number should be included in exports of the layouts.

spaceBetweenPages

Returns the space between pages, in layout units.

stringType

rtype:

str

takePage

Takes a page from the collection, returning ownership of the page to the caller.

timerEvent

visiblePageNumbers

Returns a list of the page numbers which are visible within the specified region (in layout coordinates).

visiblePages

Returns a list of the pages which are visible within the specified region (in layout coordinates).

writeXml

Stores the collection's state in a DOM element.

Signals

changed

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

pageAboutToBeRemoved

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

addPage(self, page: QgsLayoutItemPage)¶

Adds a page to the collection. Ownership of the page is transferred to the collection, and the page will automatically be added to the collection’s layout() (there is no need to manually add the page item to the layout). The page will be added after all pages currently contained in the collection.

Calling addPage() automatically triggers a reflow() of pages.

See also

extendByNewPage()

See also

insertPage()

Parameters:: page (QgsLayoutItemPage) –

beginPageSizeChange(self)¶: Should be called before changing any page item sizes, and followed by a call to endPageSizeChange(). If page size changes are wrapped in these calls, then items will maintain their same relative position on pages after the page sizes are updated.

See also

endPageSizeChange()

changed¶

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:

name (str = ...) –
revision (int = ...) –
arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

childEvent(self, QChildEvent)¶

clear(self)¶: Removes all pages from the collection.

See also

deletePage()

connectNotify(self, QMetaMethod)¶

customEvent(self, QEvent)¶

deletePage(self, pageNumber: int)¶

Deletes a page from the collection. The page will automatically be removed from the collection’s layout().

Page numbers in collections begin at 0 - so a pageNumber of 0 will delete the first page in the collection.

Calling deletePage() automatically triggers a reflow() of pages.

See also

clear()

deletePage(self, page: QgsLayoutItemPage) Deletes a page from the collection. The page will automatically be removed from the collection’s layout().

Calling deletePage() automatically triggers a reflow() of pages.

See also

clear()

Parameters:: pageNumber (int) –

disconnectNotify(self, QMetaMethod)¶

endPageSizeChange(self)¶: Should be called after changing any page item sizes, and preceded by a call to beginPageSizeChange(). If page size changes are wrapped in these calls, then items will maintain their same relative position on pages after the page sizes are updated.

See also

beginPageSizeChange()

extendByNewPage(self) → QgsLayoutItemPage¶

Adds a new page to the end of the collection. This page will inherit the same size as the current final page in the collection.

The newly created page will be returned.

See also

addPage()

See also

insertPage()

Return type:: QgsLayoutItemPage

guides(self) → QgsLayoutGuideCollection¶

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

Return type:: QgsLayoutGuideCollection

hasUniformPageSizes(self) → bool¶

Returns True if the layout has uniform page sizes, e.g. all pages are the same size.

This method does not consider differing units as non-uniform sizes, only the actual physical size of the pages.

Return type:: bool

insertPage(self, page: QgsLayoutItemPage, beforePage: int)¶

Inserts a page into a specific position in the collection.

Ownership of the page is transferred to the collection, and the page will automatically be added to the collection’s layout() (there is no need to manually add the page item to the layout).

The page will be added after before the page number specified by beforePage. (Page numbers in collections begin at 0 - so a beforePage of 0 will insert the page before all existing pages).

Calling insertPage() automatically triggers a reflow() of pages.

See also

addPage()

Parameters:

page (QgsLayoutItemPage) –
beforePage (int) –

isSignalConnected(self, QMetaMethod) → bool¶

itemsOnPage(self, page: int) → List[QgsLayoutItem]¶

Returns a list of layout items on the specified page index.

Parameters:: page (int) –
Return type:: List[QgsLayoutItem]

layout(self) → QgsLayout¶

Return type:: QgsLayout

maximumPageSize(self) → QSizeF¶

Returns the maximum size of any page in the collection, by area. The returned value is in layout units.

See also

maximumPageWidth()

Return type:: QSizeF

maximumPageWidth(self) → float¶

Returns the maximum width of pages in the collection. The returned value is in layout units.

See also

maximumPageSize()

Return type:: float

page(self, pageNumber: int) → QgsLayoutItemPage¶

Returns a specific page (by pageNumber) from the collection. Internal page numbering starts at 0 - so a pageNumber of 0 corresponds to the first page in the collection. A None is returned if an invalid page number is specified.

See also

pages()

Parameters:: pageNumber (int) –
Return type:: QgsLayoutItemPage

pageAboutToBeRemoved¶

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:

name (str = ...) –
revision (int = ...) –
arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

pageAtPoint(self, point: QPointF | QPoint) → QgsLayoutItemPage¶

Returns the page at a specified point (in layout coordinates).

If no page exists at point, None will be returned.

Note

Unlike pageNumberForPoint(), this method only returns pages which directly intersect with the specified point.

See also

pageNumberForPoint()

Parameters:: point (Union[QPointF) –
Return type:: QgsLayoutItemPage

pageCount(self) → int¶

Returns the number of pages in the collection.

See also

pages()

Return type:: int

pageIsEmpty(self, page: int) → bool¶

Returns whether a given page index is empty, ie, it contains no items except for the background paper item.

See also

shouldExportPage()

Parameters:: page (int) –
Return type:: bool

pageNumber(self, page: QgsLayoutItemPage) → int¶

Returns the page number for the specified page, or -1 if the page is not contained in the collection.

Parameters:: page (QgsLayoutItemPage) –
Return type:: int

pageNumberForPoint(self, point: QPointF | QPoint) → int¶

Returns the page number corresponding to a point in the layout (in layout units).

Page numbers in collections begin at 0 - so a page number of 0 indicates the first page.

Note

This is a relaxed check, which will always return a page number. For instance, it does not consider x coordinates and vertical coordinates before the first page or after the last page will still return the nearest page.

See also

predictPageNumberForPoint()

See also

pageAtPoint()

See also

positionOnPage()

Parameters:: point (Union[QPointF) –
Return type:: int

pagePositionToAbsolute(self, page: int, position: QgsLayoutPoint) → QgsLayoutPoint¶

Converts a position on a page to an absolute position in (maintaining the units from the input position).

See also

pagePositionToLayoutPosition()

Parameters:

page (int) –
position (QgsLayoutPoint) –

Return type:

QgsLayoutPoint

pagePositionToLayoutPosition(self, page: int, position: QgsLayoutPoint) → QPointF¶

Converts a position on a page to an absolute position in layout coordinates.

See also

pagePositionToAbsolute()

Parameters:

page (int) –
position (QgsLayoutPoint) –

Return type:

QPointF

pageShadowWidth(self) → float¶

Returns the size of the page shadow, in layout units.

Return type:: float

pageStyleSymbol(self) → QgsFillSymbol¶

Returns the symbol to use for drawing pages in the collection.

See also

setPageStyleSymbol()

Deprecated since version Use: QgsLayoutItemPage.pageStyleSymbol() instead.

Return type:: QgsFillSymbol

pages(self) → List[QgsLayoutItemPage]¶

Returns a list of pages in the collection.

See also

page()

See also

pageCount()

Return type:: List[QgsLayoutItemPage]

positionOnPage(self, point: QPointF | QPoint) → QPointF¶

Returns the position within a page of a point in the layout (in layout units).

See also

pageNumberForPoint()

Parameters:: point (Union[QPointF) –
Return type:: QPointF

predictPageNumberForPoint(self, point: QPointF | QPoint) → int¶

Returns the theoretical page number corresponding to a point in the layout (in layout units), assuming that enough pages exist in the layout to cover that point.

If there are insufficient pages currently in the layout, this method will assume that extra “imaginary” pages have been added at the end of the layout until that point is reached. These imaginary pages will inherit the size of the existing final page in the layout.

Page numbers in collections begin at 0 - so a page number of 0 indicates the first page.

See also

pageNumberForPoint()

See also

pageAtPoint()

See also

positionOnPage()

Parameters:: point (Union[QPointF) –
Return type:: int

readXml(self, collectionElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool¶

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

See also

writeXml()

Parameters:

collectionElement (QDomElement) –
document (QDomDocument) –
context (QgsReadWriteContext) –

Return type:

bool

receivers(self, PYQT_SIGNAL) → int¶

redraw(self)¶: Triggers a redraw for all pages.

reflow(self)¶: Forces the page collection to reflow the arrangement of pages, e.g. to account for page size/orientation change.

resizeToContents(self, margins: QgsMargins, marginUnits: Qgis.LayoutUnit)¶

Resizes the layout to a single page which fits the current contents of the layout.

Calling this method resets the number of pages to 1, with the size set to the minimum size required to fit all existing layout items. Items will also be repositioned so that the new top-left bounds of the layout is at the point (marginLeft, marginTop). An optional margin can be specified.

Parameters:

margins (QgsMargins) –
marginUnits (Qgis.LayoutUnit) –

sender(self) → QObject¶

senderSignalIndex(self) → int¶

setPageStyleSymbol(self, symbol: QgsFillSymbol)¶

Sets the symbol to use for drawing pages in the collection.

Ownership is not transferred, and a copy of the symbol is created internally.

See also

pageStyleSymbol()

Parameters:: symbol (QgsFillSymbol) –

shouldExportPage(self, page: int) → bool¶

Returns whether the specified page number should be included in exports of the layouts.

Warning

This will always return True unless the layout is being currently exported – it cannot be used in advance to determine whether a given page will be exported!

See also

pageIsEmpty()

Parameters:: page (int) –
Return type:: bool

spaceBetweenPages(self) → float¶

Returns the space between pages, in layout units.

Return type:: float

stringType(self) → str¶

Return type:: str

takePage(self, page: QgsLayoutItemPage) → QgsLayoutItemPage¶

Takes a page from the collection, returning ownership of the page to the caller.

Parameters:: page (QgsLayoutItemPage) –
Return type:: QgsLayoutItemPage

timerEvent(self, QTimerEvent)¶

visiblePageNumbers(self, region: QRectF) → List[int]¶

Returns a list of the page numbers which are visible within the specified region (in layout coordinates).

See also

visiblePages()

Parameters:: region (QRectF) –
Return type:: List[int]

visiblePages(self, region: QRectF) → List[QgsLayoutItemPage]¶

Returns a list of the pages which are visible within the specified region (in layout coordinates).

See also

visiblePageNumbers()

Parameters:: region (QRectF) –
Return type:: List[QgsLayoutItemPage]

writeXml(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool¶

Stores the collection’s state in a DOM element. The parentElement should refer to the parent layout’s DOM element.

See also

readXml()

Parameters:

parentElement (QDomElement) –
document (QDomDocument) –
context (QgsReadWriteContext) –

Return type:

bool