QGIS API Documentation  3.22.4-Białowieża (ce8e65e95e)
Public Slots | Signals | Public Member Functions | Friends | List of all members
QgsLayoutPageCollection Class Reference

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

#include <qgslayoutpagecollection.h>

Inheritance diagram for QgsLayoutPageCollection:
Inheritance graph
[legend]

Public Slots

void redraw ()
 Triggers a redraw for all pages. More...
 

Signals

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

Public Member Functions

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

Friends

class QgsLayoutPageCollectionUndoCommand
 

Detailed Description

A manager for a collection of pages in a layout.

Since
QGIS 3.0

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 563 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 697 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 626 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 660 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 574 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 427 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 432 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 138 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 586 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 521 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 446 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 121 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 111 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 461 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 466 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 208 of file qgslayoutpagecollection.cpp.

◆ pageCount()

int QgsLayoutPageCollection::pageCount ( ) const

Returns the number of pages in the collection.

See also
pages()

Definition at line 456 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 502 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 471 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 156 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 233 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 223 of file qgslayoutpagecollection.cpp.

◆ pages()

QList< QgsLayoutItemPage * > QgsLayoutPageCollection::pages ( )

Returns a list of pages in the collection.

See also
page()
pageCount()

Definition at line 451 of file qgslayoutpagecollection.cpp.

◆ pageShadowWidth()

double QgsLayoutPageCollection::pageShadowWidth ( ) const

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

Definition at line 279 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:
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 244 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 174 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 375 of file qgslayoutpagecollection.cpp.

◆ redraw

void QgsLayoutPageCollection::redraw ( )
slot

Triggers a redraw for all pages.

Definition at line 437 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 95 of file qgslayoutpagecollection.cpp.

◆ resizeToContents()

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.

Definition at line 284 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 537 of file qgslayoutpagecollection.cpp.

◆ spaceBetweenPages()

double QgsLayoutPageCollection::spaceBetweenPages ( ) const

Returns the space between pages, in layout units.

Definition at line 274 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 717 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 488 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 476 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 357 of file qgslayoutpagecollection.cpp.

Friends And Related Function Documentation

◆ QgsLayoutPageCollectionUndoCommand

friend class QgsLayoutPageCollectionUndoCommand
friend

Definition at line 430 of file qgslayoutpagecollection.h.


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