Class: QgsLayoutMultiFrame

class qgis.core.QgsLayoutMultiFrame

Bases: QgsLayoutObject, QgsLayoutUndoObjectInterface

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

New in version 3.0.

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

Methods

addFrame

Adds a frame to the multiframe.

beginCommand

Starts new undo command for this item.

cancelCommand

Cancels the current item command and discards it.

childEvent

connectNotify

createCommand

param text

createExpressionContext

rtype

QgsExpressionContext

createNewFrame

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

customEvent

deleteFrames

Removes and deletes all child frames.

disconnectNotify

displayName

Returns the multiframe display name.

endCommand

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

finalizeRestoreFromXml

Called after all pending items have been restored from XML.

findNearbyPageBreak

Finds the optimal position to break a frame at.

fixedFrameSize

Returns the fixed size for a frame, if desired.

frame

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

frameCount

Returns the number of frames associated with this multiframe.

frameIndex

Returns the index of a frame within the multiframe.

frames

Returns a list of all child frames for this multiframe.

icon

Returns the item's icon.

isSignalConnected

minFrameSize

Returns the minimum size for a frames, if desired.

readObjectPropertiesFromElement

Sets object properties from a DOM element

readPropertiesFromElement

Sets multiframe state from a DOM element.

readXml

Sets the item state from a DOM element.

recalculateFrameRects

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

recalculateFrameSizes

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

receivers

refresh

Refreshes the multiframe, causing a recalculation of any property overrides.

refreshDataDefinedProperty

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

removeFrame

Removes a frame by index from the multiframe.

render

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

resizeMode

Returns the resize mode for the multiframe.

sender

senderSignalIndex

setResizeMode

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

timerEvent

totalSize

Returns the total size of the multiframe's content, in layout units.

type

Returns unique multiframe type id.

update

Forces a redraw of all child frames.

uuid

Returns the multiframe identification string.

writeObjectPropertiesToElement

Stores object properties within an XML DOM element.

writePropertiesToElement

Stores multiframe state within an XML DOM element.

writeXml

Stores the multiframe state in a DOM element.

Signals

contentsChanged

Emitted when the contents of the multi frame have changed and the frames must be redrawn.

Attributes

ExtendToNextPage

RepeatOnEveryPage

RepeatUntilFinished

UndoHtmlBreakDistance

UndoHtmlSource

UndoHtmlStylesheet

UndoNone

UndoTableBackgroundColor

UndoTableCellStyle

UndoTableContentFontColor

UndoTableGridColor

UndoTableGridStrokeWidth

UndoTableHeaderFontColor

UndoTableMargin

UndoTableMaximumFeatures

UseExistingFrames

ExtendToNextPage = 1
RepeatOnEveryPage = 2
RepeatUntilFinished = 3
class ResizeMode

Bases: int

class UndoCommand

Bases: int

UndoHtmlBreakDistance = 0
UndoHtmlSource = 1
UndoHtmlStylesheet = 2
UndoNone = -1
UndoTableBackgroundColor = 10
UndoTableCellStyle = 3
UndoTableContentFontColor = 7
UndoTableGridColor = 9
UndoTableGridStrokeWidth = 8
UndoTableHeaderFontColor = 6
UndoTableMargin = 5
UndoTableMaximumFeatures = 4
UseExistingFrames = 0
addFrame(self, frame: QgsLayoutFrame, recalcFrameSizes: bool = True)

Adds a frame to the multiframe.

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

See also

removeFrame()

Parameters
beginCommand(self, commandText: str, command: QgsLayoutMultiFrame.UndoCommand = QgsLayoutMultiFrame.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.

See also

endCommand()

See also

cancelCommand()

Parameters
  • commandText (str) –

  • command (QgsLayoutMultiFrame.UndoCommand = QgsLayoutMultiFrame.UndoNone) –

cancelCommand(self)

Cancels the current item command and discards it.

See also

beginCommand()

See also

endCommand()

childEvent(self, QChildEvent)
connectNotify(self, QMetaMethod)
contentsChanged

Emitted when the contents of the multi frame have changed and the frames must be redrawn. [signal]

createCommand(self, text: str, id: int, parent: QUndoCommand = None) QgsAbstractLayoutUndoCommand
Parameters
  • text (str) –

  • id (int) –

  • parent (QUndoCommand = None) –

Return type

QgsAbstractLayoutUndoCommand

createExpressionContext(self) QgsExpressionContext
Return type

QgsExpressionContext

createNewFrame(self, currentFrame: QgsLayoutFrame, pos: Union[QPointF, QPoint], size: QSizeF) QgsLayoutFrame

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

Parameters
  • currentFrame (QgsLayoutFrame) – an existing QgsLayoutFrame from which to copy the size and general frame properties (e.g., frame style, background, rendering settings).

  • pos (Union[QPointF) – position of top-left corner of the new frame, in layout units

  • size (QSizeF) – size of the new frame, in layout units

Return type

QgsLayoutFrame

customEvent(self, QEvent)
deleteFrames(self)

Removes and deletes all child frames.

See also

removeFrame()

disconnectNotify(self, QMetaMethod)
displayName(self) str

Returns the multiframe display name.

Return type

str

endCommand(self)

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

See also

beginCommand()

See also

cancelCommand()

finalizeRestoreFromXml(self)

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.

See also

readXml()

findNearbyPageBreak(self, yPos: float) float

Finds the optimal position to break a frame at.

Parameters

yPos (float) – maximum vertical position for break, in layout units.

Return type

float

Returns

the optimal breakable position which occurs in the multi frame close to and before the specified yPos

fixedFrameSize(self, frameIndex: int = -1) QSizeF

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

Parameters

frameIndex (int = -1) – frame number

Return type

QSizeF

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.

See also

minFrameSize()

frame(self, index: int) QgsLayoutFrame

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

See also

frameIndex()

Parameters

index (int) –

Return type

QgsLayoutFrame

frameCount(self) int

Returns the number of frames associated with this multiframe.

See also

frames()

Return type

int

frameIndex(self, frame: QgsLayoutFrame) int

Returns the index of a frame within the multiframe.

Return type

int

Returns

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

See also

frame()

Parameters

frame (QgsLayoutFrame) –

frames(self) List[QgsLayoutFrame]

Returns a list of all child frames for this multiframe.

See also

frameCount()

Return type

List[QgsLayoutFrame]

icon(self) QIcon

Returns the item’s icon.

Return type

QIcon

isSignalConnected(self, QMetaMethod) bool
minFrameSize(self, frameIndex: int = -1) QSizeF

Returns the minimum size for a frames, if desired. If the minimum size changes, the sizes of all frames can be recalculated by calling recalculateFrameRects().

Parameters

frameIndex (int = -1) – frame number

Return type

QSizeF

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.

See also

fixedFrameSize()

readObjectPropertiesFromElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Sets object properties from a DOM element

Parameters
  • parentElement – is the parent DOM element for the object

  • document – DOM document

  • context – read write context

Returns

True if read was successful

readPropertiesFromElement(self, element: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Sets multiframe state from a DOM element.

Parameters
  • element (QDomElement) – is the DOM element for the multiframe

  • document (QDomDocument) – DOM document

  • context (QgsReadWriteContext) – 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().

See also

readXml()

Return type

bool

readXml(self, itemElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext, includeFrames: bool = False) bool

Sets the item state from a DOM element.

Parameters
  • itemElement (QDomElement) – is the DOM node corresponding to item (e.g. ‘LayoutItem’ element)

  • document (QDomDocument) – DOM document

  • context (QgsReadWriteContext) – read write context

  • includeFrames (bool = False) – set to True to read state information about child frames from DOM

See also

writeXml()

Return type

bool

recalculateFrameRects(self)

Forces a recalculation of all the associated frame’s scene rectangles. This method is useful for multiframes which implement a minFrameSize() or fixedFrameSize() method.

See also

minFrameSize()

See also

fixedFrameSize()

recalculateFrameSizes(self)

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.

receivers(self, PYQT_SIGNAL) int
refresh(self)

Refreshes the multiframe, causing a recalculation of any property overrides.

refreshDataDefinedProperty(self, property: QgsLayoutObject.DataDefinedProperty = QgsLayoutObject.AllProperties)

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.

Parameters

property (QgsLayoutObject.DataDefinedProperty = QgsLayoutObject.AllProperties) –

removeFrame(self, index: int, removeEmptyPages: bool = 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.

See also

addFrame()

See also

deleteFrames()

Parameters
  • index (int) –

  • removeEmptyPages (bool = False) –

render(self, context: QgsLayoutItemRenderContext, renderExtent: QRectF, frameIndex: int)

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

Parameters
  • context (QgsLayoutItemRenderContext) – destination render painter

  • renderExtent (QRectF) – visible extent of content to render into the painter.

  • frameIndex (int) – frame number for content

resizeMode(self) QgsLayoutMultiFrame.ResizeMode

Returns the resize mode for the multiframe.

See also

setResizeMode()

Return type

QgsLayoutMultiFrame.ResizeMode

sender(self) QObject
senderSignalIndex(self) int
setResizeMode(self, mode: QgsLayoutMultiFrame.ResizeMode)

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

See also

resizeMode()

Parameters

mode (QgsLayoutMultiFrame.ResizeMode) –

timerEvent(self, QTimerEvent)
totalSize(self) QSizeF

Returns the total size of the multiframe’s content, in layout units.

Return type

QSizeF

type(self) int

Returns unique multiframe type id.

Return type

int

update(self)

Forces a redraw of all child frames.

uuid(self) str

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

Note

There is no corresponding setter for the uuid - it’s created automatically.

Return type

str

writeObjectPropertiesToElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Stores object properties within an XML DOM element.

Parameters
  • parentElement – is the parent DOM element to store the object’s properties in

  • document – DOM document

  • context – read write context

Returns

True if write was successful

writePropertiesToElement(self, element: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Stores multiframe state within an XML DOM element.

Parameters
  • element (QDomElement) – is the DOM element to store the multiframe’s properties in

  • document (QDomDocument) – DOM document

  • context (QgsReadWriteContext) – read write context

See also

writeXml()

Return type

bool

writeXml(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext, includeFrames: bool = False) bool

Stores the multiframe state in a DOM element.

Parameters
  • parentElement (QDomElement) – parent DOM element (e.g. ‘Layout’ element)

  • document (QDomDocument) – DOM document

  • context (QgsReadWriteContext) – read write context

  • includeFrames (bool = False) – set to True to write state information about child frames into DOM

See also

readXml()

Return type

bool