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 specifiedlayout
.Methods
Adds a
frame
to the multiframe.Starts new undo command for this item.
Cancels the current item command and discards it.
- param text:
- rtype:
QgsExpressionContext
Creates a new frame and adds it to the multi frame and layout.
Removes and deletes all child frames.
Returns the multiframe display name.
Completes the current item command and push it onto the layout's undo stack.
Called after all pending items have been restored from XML.
Finds the optimal position to break a frame at.
Returns the fixed size for a frame, if desired.
Returns the child frame at a specified
index
from the multiframe.Returns the number of frames associated with this multiframe.
Returns the index of a
frame
within the multiframe.Returns a list of all child frames for this multiframe.
Returns the item's icon.
Returns the minimum size for a frames, if desired.
Sets object properties from a DOM element
Sets multiframe state from a DOM element.
Sets the item state from a DOM element.
Forces a recalculation of all the associated frame's scene rectangles.
Recalculates the portion of the multiframe item which is shown in each of its component frames.
Refreshes the multiframe, causing a recalculation of any property overrides.
Refreshes a data defined
property
for the multi frame by reevaluating the property's value and redrawing the item with this new value.Removes a frame by
index
from the multiframe.Renders a portion of the multiframe's content into a render
context
.Returns the resize mode for the multiframe.
Sets the resize
mode
for the multiframe, and recalculates frame sizes to match.Returns the total size of the multiframe's content, in layout units.
Returns unique multiframe type id.
Forces a redraw of all child frames.
Returns the multiframe identification string.
Stores object properties within an XML DOM element.
Stores multiframe state within an XML DOM element.
Stores the multiframe state in a DOM element.
Signals
pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL
Attributes
- 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 toTrue
, then a recalculation of all existing frame sizes will be forced.See also
- Parameters:
frame (QgsLayoutFrame) –
recalcFrameSizes (bool = True) –
- 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 samecommand
will be collapsed into a single undo command in the layout history.See also
See also
- Parameters:
commandText (str) –
command (QgsLayoutMultiFrame.UndoCommand = QgsLayoutMultiFrame.UndoNone) –
- cancelCommand(self)¶
Cancels the current item command and discards it.
See also
See also
- childEvent(self, QChildEvent)¶
- connectNotify(self, QMetaMethod)¶
- contentsChanged¶
pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL
types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.
- Parameters:
name (str = ...) –
revision (int = ...) –
arguments (Sequence = ...) –
- Return type:
PYQT_SIGNAL
- createCommand(self, text: str, id: int, parent: QUndoCommand = None) QgsAbstractLayoutUndoCommand ¶
- Parameters:
text (str) –
id (int) –
parent (QUndoCommand = None) –
- Return type:
- createExpressionContext(self) QgsExpressionContext ¶
- Return type:
- createNewFrame(self, currentFrame: QgsLayoutFrame, pos: 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:
- customEvent(self, QEvent)¶
- deleteFrames(self)¶
Removes and deletes all child frames.
See also
- 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
See also
- 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
- 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
See also
- frame(self, index: int) QgsLayoutFrame ¶
Returns the child frame at a specified
index
from the multiframe.See also
- Parameters:
index (int) –
- Return type:
- frameCount(self) int ¶
Returns the number of frames associated with this multiframe.
See also
- 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
- Parameters:
frame (QgsLayoutFrame) –
- frames(self) List[QgsLayoutFrame] ¶
Returns a list of all child frames for this multiframe.
See also
- 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
See also
- 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
See also
- 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
See also
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 infinalizeRestoreFromXml()
, notreadPropertiesFromElement()
.See also
- 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
- 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()
orfixedFrameSize()
method.See also
See also
See also
- 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.
See also
- 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. Ifproperty
is set toQgsLayoutObject
.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 toTrue
, then pages which are empty after the frame is removed will also be removed from the layout.See also
See also
- 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
- Return type:
- 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
- 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
See also
- 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
See also
- 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
- Return type:
bool