QgsLayoutFrame class

Base class for frame items, which form a layout multiframe item.

Reference

Base classes

class QgsLayoutItem: Base class for graphical items within a QgsLayout.

Public static functions

static auto create(QgsLayout* layout) -> QgsLayoutFrame*: Creates a new QgsLayoutFrame belonging to the specified layout.

Constructors, destructors, conversion operators

QgsLayoutFrame(QgsLayout* layout, QgsLayoutMultiFrame* multiFrame): Constructor for QgsLayoutFrame, with the specified parent layout and belonging to a multiFrame.

Public functions

void cleanup() override: Called just before a batch of items are deleted, allowing them to run cleanup tasks.
auto createExpressionContext() const -> QgsExpressionContext override: This method needs to be reimplemented in all classes which implement this interface and return an expression context.
auto displayName() const -> QString override: Gets item display name.
auto extent() const -> QRectF: Returns the visible portion of the multi frame's content which is shown in this frame, in layout units.
auto fixedSize() const -> QgsLayoutSize override: Returns the fixed size of the item, if applicable, or an empty size if item can be freely resized.
auto hideBackgroundIfEmpty() const -> bool: Returns whether the background and frame stroke should be hidden if this frame is empty.
auto hidePageIfEmpty() const -> bool: Returns whether the page should be hidden (ie, not included in layout exports) if this frame is empty.
auto icon() const -> QIcon override: Returns the item's icon.
auto isEmpty() const -> bool: Returns whether the frame is empty.
auto minimumSize() const -> QgsLayoutSize override: Returns the minimum allowed size of the item, if applicable, or an empty size if item can be freely resized.
auto multiFrame() const -> QgsLayoutMultiFrame*: Returns the parent multiframe for the frame.
void setContentSection(const QRectF& section): Sets the visible part of the multiframe's content which is visible within this frame (relative to the total multiframe extent in layout units).
void setHideBackgroundIfEmpty(bool hideBackgroundIfEmpty): Sets whether the background and frame stroke should be hidden if this frame is empty.
void setHidePageIfEmpty(bool hidePageIfEmpty): Sets whether the page should be hidden (ie, not included in layout exports) if this frame is empty.

Protected functions

void draw(QgsLayoutItemRenderContext& context) override: Draws the item's contents using the specified item render context.
void drawBackground(QgsRenderContext& context) override: Draws the background for the item.
void drawFrame(QgsRenderContext& context) override: Draws the frame around the item.
auto readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) -> bool override: Sets item state from a DOM element.
auto writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const -> bool override: Stores item state within an XML DOM element.

Function documentation

QgsExpressionContext QgsLayoutFrame::createExpressionContext() const override

This method needs to be reimplemented in all classes which implement this interface and return an expression context.

QString QgsLayoutFrame::displayName() const override

Gets item display name.

This is the item's id if set, and if not, a user-friendly string identifying item type.

QRectF QgsLayoutFrame::extent() const

Returns the visible portion of the multi frame's content which is shown in this frame, in layout units.

QgsLayoutSize QgsLayoutFrame::fixedSize() const override

Returns the fixed size of the item, if applicable, or an empty size if item can be freely resized.

bool QgsLayoutFrame::hideBackgroundIfEmpty() const

Returns whether the background and frame stroke should be hidden if this frame is empty.

Returns	true if background and stroke should be hidden if frame is empty

bool QgsLayoutFrame::hidePageIfEmpty() const

Returns whether the page should be hidden (ie, not included in layout exports) if this frame is empty.

Returns	true if page should be hidden if frame is empty

bool QgsLayoutFrame::isEmpty() const

Returns whether the frame is empty.

QgsLayoutSize QgsLayoutFrame::minimumSize() const override

Returns the minimum allowed size of the item, if applicable, or an empty size if item can be freely resized.

void QgsLayoutFrame::setContentSection(const QRectF& section)

Sets the visible part of the multiframe's content which is visible within this frame (relative to the total multiframe extent in layout units).

void QgsLayoutFrame::setHideBackgroundIfEmpty(bool hideBackgroundIfEmpty)

Sets whether the background and frame stroke should be hidden if this frame is empty.

Parameters
hideBackgroundIfEmpty	set to true if background and stroke should be hidden if frame is empty

void QgsLayoutFrame::setHidePageIfEmpty(bool hidePageIfEmpty)

Sets whether the page should be hidden (ie, not included in layout exports) if this frame is empty.

Parameters
hidePageIfEmpty	set to true if page should be hidden if frame is empty

void QgsLayoutFrame::draw(QgsLayoutItemRenderContext& context) override protected

Draws the item's contents using the specified item render context.

Note that the context's painter has been scaled so that painter units are pixels. Use the QgsRenderContext methods to convert from millimeters or other units to the painter's units.

bool QgsLayoutFrame::readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) override protected

Sets item state from a DOM element.

Parameters
element	is the DOM element for the item
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 QgsLayoutFrame::writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const override protected

Stores item state within an XML DOM element.

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