QgsLayoutPageCollection class

A manager for a collection of pages in a layout.

Contents

Base classes

class QgsLayoutSerializableObject
An interface for layout objects which can be stored and read from DOM elements.

Constructors, destructors, conversion operators

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

Public functions

void addPage(QgsLayoutItemPage* page)
Adds a page to the collection.
void beginPageSizeChange()
Should be called before changing any page item sizes, and followed by a call to endPageSizeChange().
void clear()
Removes all pages from the collection.
void deletePage(int pageNumber)
Deletes a page from the collection.
void deletePage(QgsLayoutItemPage* page)
Deletes a page from the collection.
void endPageSizeChange()
Should be called after changing any page item sizes, and preceded by a call to beginPageSizeChange().
auto extendByNewPage() -> QgsLayoutItemPage*
Adds a new page to the end of the collection.
auto guides() -> QgsLayoutGuideCollection&
Returns a reference to the collection's guide collection, which manages page snap guides.
auto guides() const -> const QgsLayoutGuideCollection&
Returns a reference to the collection's guide collection, which manages page snap guides.
auto hasUniformPageSizes() const -> bool
Returns true if the layout has uniform page sizes, e.g.
void insertPage(QgsLayoutItemPage* page, int beforePage)
Inserts a page into a specific position in the collection.
auto itemsOnPage(int page) const -> QList<QgsLayoutItem*>
Returns a list of layout items on the specified page index.
template<class T>
void itemsOnPage(QList<T*>& itemList, int page) const
Returns layout items of a specific type on a specified page.
auto layout() -> QgsLayout* override
Returns the layout the object belongs to.
auto maximumPageSize() const -> QSizeF
Returns the maximum size of any page in the collection, by area.
auto maximumPageWidth() const -> double
Returns the maximum width of pages in the collection.
auto page(int pageNumber) -> QgsLayoutItemPage*
Returns a specific page (by pageNumber) from the collection.
auto page(int pageNumber) const -> const QgsLayoutItemPage*
Returns a specific page (by pageNumber) from the collection.
auto pageAtPoint(QPointF point) const -> QgsLayoutItemPage*
Returns the page at a specified point (in layout coordinates).
auto pageCount() const -> int
Returns the number of pages in the collection.
auto pageIsEmpty(int page) const -> bool
Returns whether a given page index is empty, ie, it contains no items except for the background paper item.
auto pageNumber(QgsLayoutItemPage* page) const -> int
Returns the page number for the specified page, or -1 if the page is not contained in the collection.
auto pageNumberForPoint(QPointF point) const -> int
Returns the page number corresponding to a point in the layout (in layout units).
auto pagePositionToAbsolute(int page, const QgsLayoutPoint& position) const -> QgsLayoutPoint
Converts a position on a page to an absolute position in (maintaining the units from the input position).
auto pagePositionToLayoutPosition(int page, const QgsLayoutPoint& position) const -> QPointF
Converts a position on a page to an absolute position in layout coordinates.
auto pages() -> QList<QgsLayoutItemPage*>
Returns a list of pages in the collection.
auto pageShadowWidth() const -> double
Returns the size of the page shadow, in layout units.
auto pageStyleSymbol() const -> const QgsFillSymbol*
Returns the symbol to use for drawing pages in the collection.
auto positionOnPage(QPointF point) const -> QPointF
Returns the position within a page of a point in the layout (in layout units).
auto predictPageNumberForPoint(QPointF point) const -> 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.
auto readXml(const QDomElement& collectionElement, const QDomDocument& document, const QgsReadWriteContext& context) -> bool override
Sets the collection's state from a DOM element.
void reflow()
Forces the page collection to reflow the arrangement of pages, e.g.
void resizeToContents(const QgsMargins& margins, QgsUnitTypes::LayoutUnit marginUnits)
Resizes the layout to a single page which fits the current contents of the layout.
void setPageStyleSymbol(QgsFillSymbol* symbol)
Sets the symbol to use for drawing pages in the collection.
auto shouldExportPage(int page) const -> bool
Returns whether the specified page number should be included in exports of the layouts.
auto spaceBetweenPages() const -> double
Returns the space between pages, in layout units.
auto stringType() const -> QString override
Returns the object type as a string.
auto takePage(QgsLayoutItemPage* page) -> QgsLayoutItemPage*
Takes a page from the collection, returning ownership of the page to the caller.
auto visiblePageNumbers(const QRectF& region) const -> QList<int>
Returns a list of the page numbers which are visible within the specified region (in layout coordinates).
auto visiblePages(const QRectF& region) const -> QList<QgsLayoutItemPage*>
Returns a list of the pages which are visible within the specified region (in layout coordinates).
auto writeXml(QDomElement& parentElement, QDomDocument& document, const QgsReadWriteContext& context) const -> bool override
Stores the collection's state in a DOM element.

Signals

void changed()
Emitted when pages are added or removed from the collection.
void pageAboutToBeRemoved(int pageNumber)
Emitted just before a page is removed from the collection.

Public slots

void redraw()
Triggers a redraw for all pages.

Function documentation

void QgsLayoutPageCollection::addPage(QgsLayoutItemPage* page)

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.

void QgsLayoutPageCollection::beginPageSizeChange()

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.

void QgsLayoutPageCollection::clear()

Removes all pages from the collection.

void QgsLayoutPageCollection::deletePage(int pageNumber)

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.

void QgsLayoutPageCollection::deletePage(QgsLayoutItemPage* page)

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.

void QgsLayoutPageCollection::endPageSizeChange()

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.

QgsLayoutItemPage* QgsLayoutPageCollection::extendByNewPage()

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.

bool QgsLayoutPageCollection::hasUniformPageSizes() const

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.

void QgsLayoutPageCollection::insertPage(QgsLayoutItemPage* page, int beforePage)

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.

template<class T>
void QgsLayoutPageCollection::itemsOnPage(QList<T*>& itemList, int page) const

Returns layout items of a specific type on a specified page.

QSizeF QgsLayoutPageCollection::maximumPageSize() const

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

The returned value is in layout units.

double QgsLayoutPageCollection::maximumPageWidth() const

Returns the maximum width of pages in the collection.

The returned value is in layout units.

QgsLayoutItemPage* QgsLayoutPageCollection::page(int pageNumber)

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 nullptr is returned if an invalid page number is specified.

const QgsLayoutItemPage* QgsLayoutPageCollection::page(int pageNumber) const

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 nullptr is returned if an invalid page number is specified.

QgsLayoutItemPage* QgsLayoutPageCollection::pageAtPoint(QPointF point) const

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

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

int QgsLayoutPageCollection::pageCount() const

Returns the number of pages in the collection.

bool QgsLayoutPageCollection::pageIsEmpty(int page) const

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

int QgsLayoutPageCollection::pageNumberForPoint(QPointF point) const

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.

QgsLayoutPoint QgsLayoutPageCollection::pagePositionToAbsolute(int page, const QgsLayoutPoint& position) const

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

QPointF QgsLayoutPageCollection::pagePositionToLayoutPosition(int page, const QgsLayoutPoint& position) const

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

\

QList<QgsLayoutItemPage*> QgsLayoutPageCollection::pages()

Returns a list of pages in the collection.

const QgsFillSymbol* QgsLayoutPageCollection::pageStyleSymbol() const

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

QPointF QgsLayoutPageCollection::positionOnPage(QPointF point) const

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

int QgsLayoutPageCollection::predictPageNumberForPoint(QPointF point) const

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.

bool QgsLayoutPageCollection::readXml(const QDomElement& collectionElement, const QDomDocument& document, const QgsReadWriteContext& context) override

Sets the collection's state from a DOM element.

collectionElement is the DOM node corresponding to the collection.

void QgsLayoutPageCollection::reflow()

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

to account for page size/orientation change.

void QgsLayoutPageCollection::resizeToContents(const QgsMargins& margins, QgsUnitTypes::LayoutUnit marginUnits)

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.

void QgsLayoutPageCollection::setPageStyleSymbol(QgsFillSymbol* symbol)

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

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

bool QgsLayoutPageCollection::shouldExportPage(int page) const

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

QString QgsLayoutPageCollection::stringType() const override

Returns the object type as a string.

This string must be a unique, single word, character only representation of the item type, eg "LayoutScaleBar"

QList<int> QgsLayoutPageCollection::visiblePageNumbers(const QRectF& region) const

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

QList<QgsLayoutItemPage*> QgsLayoutPageCollection::visiblePages(const QRectF& region) const

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

bool QgsLayoutPageCollection::writeXml(QDomElement& parentElement, QDomDocument& document, const QgsReadWriteContext& context) const override

Stores the collection's state in a DOM element.

The parentElement should refer to the parent layout's DOM element.

void QgsLayoutPageCollection::pageAboutToBeRemoved(int pageNumber) signal

Emitted just before a page is removed from the collection.

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