A manager for a collection of pages in a layout. More...

#include <qgslayoutpagecollection.h>

Inheritance diagram for QgsLayoutPageCollection:

[legend]

Public Slots
void	redraw ()
	Triggers a redraw for all pages.

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 Member Functions
	QgsLayoutPageCollection (QgsLayout *layout)
	Constructor for QgsLayoutItemPage, with the specified parent layout.

	~QgsLayoutPageCollection () override

void	addPage (QgsLayoutItemPage *page)
	Adds a page to the collection.

void	applyPropertiesToAllOtherPages (int sourcePage)
	Apply the source page properties (size & background color) to all other pages.

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

QgsLayoutItemPage *	extendByNewPage ()
	Adds a new page to the end of the collection.

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

const QgsLayoutGuideCollection &	guides () const
	Returns a reference to the collection's guide collection, which manages page snap guides.

bool	hasUniformPageSizes () const
	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.

QList< QgsLayoutItem * >	itemsOnPage (int page) const
	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.

QgsLayout *	layout () override
	Returns the layout the object belongs to.

QSizeF	maximumPageSize () const
	Returns the maximum size of any page in the collection, by area.

double	maximumPageWidth () const
	Returns the maximum width of pages in the collection.

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

const QgsLayoutItemPage *	page (int pageNumber) const
	Returns a specific page (by pageNumber) from the collection.

QgsLayoutItemPage *	pageAtPoint (QPointF point) const
	Returns the page at a specified point (in layout coordinates).

int	pageCount () const
	Returns the number of pages in the collection.

bool	pageIsEmpty (int page) const
	Returns whether a given page index is empty, ie, it contains no items except for the background paper item.

int	pageNumber (QgsLayoutItemPage *page) const
	Returns the page number for the specified page, or -1 if the page is not contained in the collection.

int	pageNumberForPoint (QPointF point) const
	Returns the page number corresponding to a point in the layout (in layout units).

QgsLayoutPoint	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	pagePositionToLayoutPosition (int page, const QgsLayoutPoint &position) const
	Converts a position on a page to an absolute position in layout coordinates.

QList< QgsLayoutItemPage * >	pages ()
	Returns a list of pages in the collection.

double	pageShadowWidth () const
	Returns the size of the page shadow, in layout units.

Q_DECL_DEPRECATED const QgsFillSymbol *	pageStyleSymbol () const
	Returns the symbol to use for drawing pages in the collection.

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

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

bool	readXml (const QDomElement &collectionElement, const QDomDocument &document, const QgsReadWriteContext &context) 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, Qgis::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.

bool	shouldExportPage (int page) const
	Returns whether the specified page number should be included in exports of the layouts.

double	spaceBetweenPages () const
	Returns the space between pages, in layout units.

QString	stringType () const override
	Returns the object type as a string.

QgsLayoutItemPage *	takePage (QgsLayoutItemPage *page)
	Takes a page from the collection, returning ownership of the page to the caller.

QList< int >	visiblePageNumbers (const QRectF &region) const
	Returns a list of the page numbers which are visible within the specified region (in layout coordinates).

QList< QgsLayoutItemPage * >	visiblePages (const QRectF &region) const
	Returns a list of the pages which are visible within the specified region (in layout coordinates).

bool	writeXml (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context) const override
	Stores the collection's state in a DOM element.

Public Member Functions inherited from QgsLayoutSerializableObject
QgsAbstractLayoutUndoCommand *	createCommand (const QString &text, int id, QUndoCommand *parent=nullptr) override
	Creates a new layout undo command with the specified text and parent.

Public Member Functions inherited from QgsLayoutUndoObjectInterface
virtual	~QgsLayoutUndoObjectInterface ()=default

Friends
class	QgsLayoutPageCollectionUndoCommand

Detailed Description

A manager for a collection of pages in a layout.

Definition at line 39 of file qgslayoutpagecollection.h.

Constructor & Destructor Documentation

◆ QgsLayoutPageCollection()

QgsLayoutPageCollection::QgsLayoutPageCollection ( QgsLayout * layout )

explicit

Constructor for QgsLayoutItemPage, with the specified parent layout.

Definition at line 27 of file qgslayoutpagecollection.cpp.

◆ ~QgsLayoutPageCollection()

QgsLayoutPageCollection::~QgsLayoutPageCollection ( )

override

Definition at line 35 of file qgslayoutpagecollection.cpp.

Member Function Documentation

◆ addPage()

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.

See also: extendByNewPage(); insertPage()

Definition at line 600 of file qgslayoutpagecollection.cpp.

◆ applyPropertiesToAllOtherPages()

void QgsLayoutPageCollection::applyPropertiesToAllOtherPages ( int sourcePage )

Apply the source page properties (size & background color) to all other pages.

Since: QGIS 3.42

Definition at line 448 of file qgslayoutpagecollection.cpp.

◆ beginPageSizeChange()

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.

See also: endPageSizeChange()

Definition at line 64 of file qgslayoutpagecollection.cpp.

◆ changed

void QgsLayoutPageCollection::changed ( )

signal

Emitted when pages are added or removed from the collection.

◆ clear()

void QgsLayoutPageCollection::clear ( )

Removes all pages from the collection.

See also: deletePage()

Definition at line 734 of file qgslayoutpagecollection.cpp.

◆ deletePage() [1/2]

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.

See also: clear()

Definition at line 663 of file qgslayoutpagecollection.cpp.

◆ deletePage() [2/2]

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.

See also: clear()

Definition at line 697 of file qgslayoutpagecollection.cpp.

◆ endPageSizeChange()

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.

See also: beginPageSizeChange()

Definition at line 79 of file qgslayoutpagecollection.cpp.

◆ extendByNewPage()

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.

See also: addPage(); insertPage()

Definition at line 611 of file qgslayoutpagecollection.cpp.

◆ guides() [1/2]

QgsLayoutGuideCollection & QgsLayoutPageCollection::guides ( )

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

Definition at line 438 of file qgslayoutpagecollection.cpp.

◆ guides() [2/2]

const QgsLayoutGuideCollection & QgsLayoutPageCollection::guides ( ) const

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

Definition at line 443 of file qgslayoutpagecollection.cpp.

◆ hasUniformPageSizes()

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.

Definition at line 149 of file qgslayoutpagecollection.cpp.

◆ insertPage()

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.

See also: addPage()

Definition at line 623 of file qgslayoutpagecollection.cpp.

◆ itemsOnPage() [1/2]

QList< QgsLayoutItem * > QgsLayoutPageCollection::itemsOnPage ( int page ) const

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

Definition at line 558 of file qgslayoutpagecollection.cpp.

◆ itemsOnPage() [2/2]

template<class T >

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

inline

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

Note: not available in Python bindings.

Definition at line 124 of file qgslayoutpagecollection.h.

◆ layout()

QgsLayout * QgsLayoutPageCollection::layout ( )

overridevirtual

Returns the layout the object belongs to.

Implements QgsLayoutSerializableObject.

Definition at line 483 of file qgslayoutpagecollection.cpp.

◆ maximumPageSize()

QSizeF QgsLayoutPageCollection::maximumPageSize ( ) const

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

The returned value is in layout units.

See also: maximumPageWidth()

Definition at line 132 of file qgslayoutpagecollection.cpp.

◆ maximumPageWidth()

double QgsLayoutPageCollection::maximumPageWidth ( ) const

Returns the maximum width of pages in the collection.

The returned value is in layout units.

See also: maximumPageSize()

Definition at line 122 of file qgslayoutpagecollection.cpp.

◆ page() [1/2]

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.

See also: pages()

Definition at line 498 of file qgslayoutpagecollection.cpp.

◆ page() [2/2]

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.

See also: pages()

Note: Not available in Python bindings.

Definition at line 503 of file qgslayoutpagecollection.cpp.

◆ pageAboutToBeRemoved

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.

◆ pageAtPoint()

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.

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

See also: pageNumberForPoint()

Definition at line 219 of file qgslayoutpagecollection.cpp.

◆ pageCount()

int QgsLayoutPageCollection::pageCount ( ) const

Returns the number of pages in the collection.

See also: pages()

Definition at line 493 of file qgslayoutpagecollection.cpp.

◆ pageIsEmpty()

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.

See also: shouldExportPage()

Definition at line 539 of file qgslayoutpagecollection.cpp.

◆ pageNumber()

int QgsLayoutPageCollection::pageNumber ( QgsLayoutItemPage * page ) const

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

Definition at line 508 of file qgslayoutpagecollection.cpp.

◆ pageNumberForPoint()

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.

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(); pageAtPoint(); positionOnPage()

Definition at line 167 of file qgslayoutpagecollection.cpp.

◆ pagePositionToAbsolute()

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

See also: pagePositionToLayoutPosition()

Definition at line 244 of file qgslayoutpagecollection.cpp.

◆ pagePositionToLayoutPosition()

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

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

\

See also: pagePositionToAbsolute()

Definition at line 234 of file qgslayoutpagecollection.cpp.

◆ pages()

QList< QgsLayoutItemPage * > QgsLayoutPageCollection::pages ( )

Returns a list of pages in the collection.

See also: page(); pageCount()

Definition at line 488 of file qgslayoutpagecollection.cpp.

◆ pageShadowWidth()

double QgsLayoutPageCollection::pageShadowWidth ( ) const

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

Definition at line 290 of file qgslayoutpagecollection.cpp.

◆ pageStyleSymbol()

const QgsFillSymbol * QgsLayoutPageCollection::pageStyleSymbol ( ) const

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

See also: setPageStyleSymbol()

Deprecated:: QGIS 3.40. Use QgsLayoutItemPage::pageStyleSymbol() instead.

Definition at line 59 of file qgslayoutpagecollection.cpp.

◆ positionOnPage()

QPointF QgsLayoutPageCollection::positionOnPage ( QPointF point ) const

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

See also: pageNumberForPoint()

Definition at line 255 of file qgslayoutpagecollection.cpp.

◆ predictPageNumberForPoint()

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.

See also: pageNumberForPoint(); pageAtPoint(); positionOnPage()

Definition at line 185 of file qgslayoutpagecollection.cpp.

◆ readXml()

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

overridevirtual

Sets the collection's state from a DOM element.

collectionElement is the DOM node corresponding to the collection.

See also: writeXml()

Implements QgsLayoutSerializableObject.

Definition at line 386 of file qgslayoutpagecollection.cpp.

◆ redraw

void QgsLayoutPageCollection::redraw ( )

slot

Triggers a redraw for all pages.

Definition at line 474 of file qgslayoutpagecollection.cpp.

◆ reflow()

void QgsLayoutPageCollection::reflow ( )

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

to account for page size/orientation change.

Definition at line 106 of file qgslayoutpagecollection.cpp.

◆ resizeToContents()

void QgsLayoutPageCollection::resizeToContents	(	const QgsMargins &	margins,
		Qgis::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.

Definition at line 295 of file qgslayoutpagecollection.cpp.

◆ setPageStyleSymbol()

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.

See also: pageStyleSymbol()

Definition at line 45 of file qgslayoutpagecollection.cpp.

◆ shouldExportPage()

bool QgsLayoutPageCollection::shouldExportPage ( int page ) const

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()

Definition at line 574 of file qgslayoutpagecollection.cpp.

◆ spaceBetweenPages()

double QgsLayoutPageCollection::spaceBetweenPages ( ) const

Returns the space between pages, in layout units.

Definition at line 285 of file qgslayoutpagecollection.cpp.

◆ stringType()

QString QgsLayoutPageCollection::stringType ( ) const

inlineoverridevirtual

Returns the object type as a string.

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

Implements QgsLayoutSerializableObject.

Definition at line 53 of file qgslayoutpagecollection.h.

◆ takePage()

QgsLayoutItemPage * QgsLayoutPageCollection::takePage ( QgsLayoutItemPage * page )

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

Definition at line 754 of file qgslayoutpagecollection.cpp.

◆ visiblePageNumbers()

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

See also: visiblePages()

Definition at line 525 of file qgslayoutpagecollection.cpp.

◆ visiblePages()

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

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

See also: visiblePageNumbers()

Definition at line 513 of file qgslayoutpagecollection.cpp.

◆ writeXml()

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

overridevirtual

Stores the collection's state in a DOM element.

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

See also: readXml()

Implements QgsLayoutSerializableObject.

Definition at line 368 of file qgslayoutpagecollection.cpp.

Friends And Related Symbol Documentation

◆ QgsLayoutPageCollectionUndoCommand

friend class QgsLayoutPageCollectionUndoCommand

friend

Definition at line 437 of file qgslayoutpagecollection.h.

The documentation for this class was generated from the following files:

/build/qgis-3.41.0+git20241119+45a0abf3bec+99sid/src/core/layout/qgslayoutpagecollection.h
/build/qgis-3.41.0+git20241119+45a0abf3bec+99sid/src/core/layout/qgslayoutpagecollection.cpp

Public Slots

Signals

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ QgsLayoutPageCollection()

◆ ~QgsLayoutPageCollection()

Member Function Documentation

◆ addPage()

◆ applyPropertiesToAllOtherPages()

◆ beginPageSizeChange()

◆ changed

◆ clear()

◆ deletePage() [1/2]

◆ deletePage() [2/2]

◆ endPageSizeChange()

◆ extendByNewPage()

◆ guides() [1/2]

◆ guides() [2/2]

◆ hasUniformPageSizes()

◆ insertPage()

◆ itemsOnPage() [1/2]

◆ itemsOnPage() [2/2]

◆ layout()

◆ maximumPageSize()

◆ maximumPageWidth()

◆ page() [1/2]

◆ page() [2/2]

◆ pageAboutToBeRemoved

◆ pageAtPoint()

◆ pageCount()

◆ pageIsEmpty()

◆ pageNumber()

◆ pageNumberForPoint()

◆ pagePositionToAbsolute()

◆ pagePositionToLayoutPosition()

◆ pages()

◆ pageShadowWidth()

◆ pageStyleSymbol()

◆ positionOnPage()

◆ predictPageNumberForPoint()

◆ readXml()

◆ redraw

◆ reflow()

◆ resizeToContents()

◆ setPageStyleSymbol()

◆ shouldExportPage()

◆ spaceBetweenPages()

◆ stringType()

◆ takePage()

◆ visiblePageNumbers()

◆ visiblePages()

◆ writeXml()

Friends And Related Symbol Documentation

◆ QgsLayoutPageCollectionUndoCommand