QgsLayoutMultiFrame class

Abstract base class for layout items with the ability to distribute the content to several frames (QgsLayoutFrame items).

Contents

Base classes

class QgsLayoutObject
A base class for objects which belong to a layout.
class QgsLayoutUndoObjectInterface
Interface for layout objects which support undo/redo commands.

Derived classes

class QgsLayoutItemHtml
A layout multiframe subclass for HTML content.
class QgsLayoutTable
A class to display a table in the print layout, and allow the table to span over multiple frames.

Public types

enum ResizeMode { UseExistingFrames = 0, ExtendToNextPage, RepeatOnEveryPage, RepeatUntilFinished }
Specifies the behavior for creating new frames to fit the multiframe's content.
enum UndoCommand { UndoHtmlBreakDistance, UndoHtmlSource, UndoHtmlStylesheet, UndoTableCellStyle, UndoTableMaximumFeatures, UndoTableMargin, UndoTableHeaderFontColor, UndoTableContentFontColor, UndoTableGridStrokeWidth, UndoTableGridColor, UndoTableBackgroundColor, UndoNone = -1 }
Multiframe item undo commands, used for collapsing undo commands.

Constructors, destructors, conversion operators

QgsLayoutMultiFrame(QgsLayout* layout)
Construct a new multiframe item, attached to the specified layout.

Public functions

void addFrame(QgsLayoutFrame* frame, bool recalcFrameSizes = true) virtual
Adds a frame to the multiframe.
void beginCommand(const QString& commandText, UndoCommand command = UndoNone)
Starts new undo command for this item.
void cancelCommand()
Cancels the current item command and discards it.
auto createCommand(const QString& text, int id, QUndoCommand* parent = nullptr) -> QgsAbstractLayoutUndoCommand* override
Creates a new layout undo command with the specified text and parent.
auto createNewFrame(QgsLayoutFrame* currentFrame, QPointF pos, QSizeF size) -> QgsLayoutFrame*
Creates a new frame and adds it to the multi frame and layout.
void deleteFrames()
Removes and deletes all child frames.
auto displayName() const -> QString virtual
Returns the multiframe display name.
void endCommand()
Completes the current item command and push it onto the layout's undo stack.
void finalizeRestoreFromXml() virtual
Called after all pending items have been restored from XML.
auto findNearbyPageBreak(double yPos) -> double virtual
Finds the optimal position to break a frame at.
auto fixedFrameSize(int frameIndex = -1) const -> QSizeF virtual
Returns the fixed size for a frame, if desired.
auto frame(int index) const -> QgsLayoutFrame*
Returns the child frame at a specified index from the multiframe.
auto frameCount() const -> int
Returns the number of frames associated with this multiframe.
auto frameIndex(QgsLayoutFrame* frame) const -> int
Returns the index of a frame within the multiframe.
auto frames() const -> QList<QgsLayoutFrame*>
Returns a list of all child frames for this multiframe.
auto icon() const -> QIcon virtual
Returns the item's icon.
auto minFrameSize(int frameIndex = -1) const -> QSizeF virtual
Returns the minimum size for a frames, if desired.
auto readXml(const QDomElement& itemElement, const QDomDocument& document, const QgsReadWriteContext& context, bool includeFrames = false) -> bool
Sets the item state from a DOM element.
void removeFrame(int index, bool removeEmptyPages = false)
Removes a frame by index from the multiframe.
void render(QgsLayoutItemRenderContext& context, const QRectF& renderExtent, int frameIndex) pure virtual
Renders a portion of the multiframe's content into a render context.
auto resizeMode() const -> ResizeMode
Returns the resize mode for the multiframe.
void setResizeMode(ResizeMode mode)
Sets the resize mode for the multiframe, and recalculates frame sizes to match.
auto totalSize() const -> QSizeF pure virtual
Returns the total size of the multiframe's content, in layout units.
auto type() const -> int pure virtual
Returns unique multiframe type id.
auto uuid() const -> QString
Returns the multiframe identification string.
auto writeXml(QDomElement& parentElement, QDomDocument& document, const QgsReadWriteContext& context, bool includeFrames = false) const -> bool
Stores the multiframe state in a DOM element.

Signals

void contentsChanged()
Emitted when the contents of the multi frame have changed and the frames must be redrawn.

Public slots

void recalculateFrameRects()
Forces a recalculation of all the associated frame's scene rectangles.
void recalculateFrameSizes() virtual
Recalculates the portion of the multiframe item which is shown in each of its component frames.
void refresh() override
Refreshes the multiframe, causing a recalculation of any property overrides.
void refreshDataDefinedProperty(QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties) virtual
Refreshes a data defined property for the multi frame by reevaluating the property's value and redrawing the item with this new value.
void update()
Forces a redraw of all child frames.

Protected functions

auto readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) -> bool virtual
Sets multiframe state from a DOM element.
auto writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const -> bool virtual
Stores multiframe state within an XML DOM element.

Enum documentation

enum QgsLayoutMultiFrame::ResizeMode

Specifies the behavior for creating new frames to fit the multiframe's content.

Enumerators
UseExistingFrames

Don't automatically create new frames, just use existing frames.
ExtendToNextPage

Creates new full page frames on the following page(s) until the entire multiframe content is visible.
RepeatOnEveryPage

Repeats the same frame on every page.
RepeatUntilFinished

creates new frames with the same position and dimensions as the existing frame on the following page(s), until the entire multiframe content is visible

enum QgsLayoutMultiFrame::UndoCommand

Multiframe item undo commands, used for collapsing undo commands.

Enumerators
UndoHtmlBreakDistance

HTML page break distance.
UndoHtmlSource

HTML source.
UndoHtmlStylesheet

HTML stylesheet.
UndoTableCellStyle

Table cell style.
UndoTableMaximumFeatures

Maximum features in table.
UndoTableMargin

Table margins.
UndoTableHeaderFontColor

Table header font color.
UndoTableContentFontColor

Table content font color.
UndoTableGridStrokeWidth

Table grid stroke width.
UndoTableGridColor

Table grid color.
UndoTableBackgroundColor

Table background color.
UndoNone

No command suppression.

Function documentation

void QgsLayoutMultiFrame::addFrame(QgsLayoutFrame* frame, bool recalcFrameSizes = true) virtual

Adds a frame to the multiframe.

If recalcFrameSizes is set to true, then a recalculation of all existing frame sizes will be forced.

void QgsLayoutMultiFrame::beginCommand(const QString& commandText, UndoCommand command = UndoNone)

Starts new undo command for this item.

The commandText should be a capitalized, imperative tense description (e.g. "Add Map Item"). If specified, multiple consecutive commands for this item with the same command will be collapsed into a single undo command in the layout history.

void QgsLayoutMultiFrame::cancelCommand()

Cancels the current item command and discards it.

QgsAbstractLayoutUndoCommand* QgsLayoutMultiFrame::createCommand(const QString& text, int id, QUndoCommand* parent = nullptr) override

Creates a new layout undo command with the specified text and parent.

The id argument can be used to specify an id number for the source event - this is used to determine whether QUndoCommand command compression can apply to the command.

QgsLayoutFrame* QgsLayoutMultiFrame::createNewFrame(QgsLayoutFrame* currentFrame, QPointF pos, QSizeF size)

Creates a new frame and adds it to the multi frame and layout.

Parameters
currentFrame an existing QgsLayoutFrame from which to copy the size and general frame properties (e.g., frame style, background, rendering settings).
pos position of top-left corner of the new frame, in layout units
size size of the new frame, in layout units

void QgsLayoutMultiFrame::deleteFrames()

Removes and deletes all child frames.

void QgsLayoutMultiFrame::endCommand()

Completes the current item command and push it onto the layout's undo stack.

void QgsLayoutMultiFrame::finalizeRestoreFromXml() virtual

Called after all pending items have been restored from XML.

Multiframes can use this method to run steps which must take place after all items have been restored to the layout, such as connecting to signals emitted by other items, which may not have existed in the layout at the time readXml() was called. E.g. a scalebar can use this to connect to its linked map item after restoration from XML.

double QgsLayoutMultiFrame::findNearbyPageBreak(double yPos) virtual

Finds the optimal position to break a frame at.

Parameters
yPos maximum vertical position for break, in layout units.
Returns the optimal breakable position which occurs in the multi frame close to and before the specified yPos

QSizeF QgsLayoutMultiFrame::fixedFrameSize(int frameIndex = -1) const virtual

Returns the fixed size for a frame, if desired.

Parameters
frameIndex frame number
Returns fixed size for frame. If the size has a width or height of 0, then the frame size is not fixed in that direction and frames can have variable width or height accordingly.

If the fixed frame size changes, the sizes of all frames can be recalculated by calling recalculateFrameRects().

QgsLayoutFrame* QgsLayoutMultiFrame::frame(int index) const

Returns the child frame at a specified index from the multiframe.

int QgsLayoutMultiFrame::frameCount() const

Returns the number of frames associated with this multiframe.

int QgsLayoutMultiFrame::frameIndex(QgsLayoutFrame* frame) const

Returns the index of a frame within the multiframe.

Returns index for frame if found, -1 if frame not found in multiframe

QList<QgsLayoutFrame*> QgsLayoutMultiFrame::frames() const

Returns a list of all child frames for this multiframe.

QSizeF QgsLayoutMultiFrame::minFrameSize(int frameIndex = -1) const virtual

Returns the minimum size for a frames, if desired.

Parameters
frameIndex frame number
Returns minimum size for frame. If the size has a width or height of 0, then the frame size has no minimum in that direction.

If the minimum size changes, the sizes of all frames can be recalculated by calling recalculateFrameRects().

bool QgsLayoutMultiFrame::readXml(const QDomElement& itemElement, const QDomDocument& document, const QgsReadWriteContext& context, bool includeFrames = false)

Sets the item state from a DOM element.

Parameters
itemElement is the DOM node corresponding to item (e.g. 'LayoutItem' element)
document DOM document
context read write context
includeFrames set to true to read state information about child frames from DOM

void QgsLayoutMultiFrame::removeFrame(int index, bool removeEmptyPages = false)

Removes a frame by index from the multiframe.

This method automatically removes the frame from the layout too.

If removeEmptyPages is set to true, then pages which are empty after the frame is removed will also be removed from the layout.

void QgsLayoutMultiFrame::render(QgsLayoutItemRenderContext& context, const QRectF& renderExtent, int frameIndex) pure virtual

Renders a portion of the multiframe's content into a render context.

Parameters
context destination render painter
renderExtent visible extent of content to render into the painter.
frameIndex frame number for content

ResizeMode QgsLayoutMultiFrame::resizeMode() const

Returns the resize mode for the multiframe.

void QgsLayoutMultiFrame::setResizeMode(ResizeMode mode)

Sets the resize mode for the multiframe, and recalculates frame sizes to match.

QString QgsLayoutMultiFrame::uuid() const

Returns the multiframe identification string.

This is a unique random string set for the multiframe upon creation.

bool QgsLayoutMultiFrame::writeXml(QDomElement& parentElement, QDomDocument& document, const QgsReadWriteContext& context, bool includeFrames = false) const

Stores the multiframe state in a DOM element.

Parameters
parentElement parent DOM element (e.g. 'Layout' element)
document DOM document
context read write context
includeFrames set to true to write state information about child frames into DOM

void QgsLayoutMultiFrame::recalculateFrameRects() public slot

Forces a recalculation of all the associated frame's scene rectangles.

This method is useful for multiframes which implement a minFrameSize() or fixedFrameSize() method.

void QgsLayoutMultiFrame::recalculateFrameSizes() virtual public slot

Recalculates the portion of the multiframe item which is shown in each of its component frames.

If the resize mode is set to anything but UseExistingFrames then this may cause new frames to be added or frames to be removed, in order to fit the current size of the multiframe's content.

void QgsLayoutMultiFrame::refreshDataDefinedProperty(QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties) virtual public slot

Refreshes a data defined property for the multi frame by reevaluating the property's value and redrawing the item with this new value.

If property is set to QgsLayoutObject::AllProperties then all data defined properties for the item will be refreshed.

bool QgsLayoutMultiFrame::readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) virtual protected

Sets multiframe state from a DOM element.

Parameters
element is the DOM element for the multiframe
document DOM document
context read write context

Note that item subclasses should not rely on all other items being present in the layout at the time this method is called. Instead, any connections and links to other items must be made in the finalizeRestoreFromXml() method. E.g. when restoring a scalebar, the connection to the linked map's signals should be implemented in finalizeRestoreFromXml(), not readPropertiesFromElement().

bool QgsLayoutMultiFrame::writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const virtual protected

Stores multiframe state within an XML DOM element.

Parameters
element is the DOM element to store the multiframe's properties in
document DOM document
context read write context