QgsLayoutItem class

Base class for graphical items within a QgsLayout.

Reference

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 QgsLayoutFrame: Base class for frame items, which form a layout multiframe item.
class QgsLayoutItem3DMap: 3
class QgsLayoutItemGroup: A container for grouping several QgsLayoutItems.
class QgsLayoutItemLabel: A layout item subclass for text labels.
class QgsLayoutItemLegend: A layout item subclass for map legends.
class QgsLayoutItemMap: Layout graphical items for displaying a map.
class QgsLayoutItemPage: Item representing the paper in a layout.
class QgsLayoutItemPicture: A layout item subclass that displays SVG files or raster format images (jpg, png, ...).
class QgsLayoutItemScaleBar: A layout item subclass for scale bars.
class QgsLayoutItemShape: Layout item for basic filled shapes (e.g.
class QgsLayoutNodesItem: An abstract layout item that provides generic methods for node based shapes such as polygon or polylines.

Public types

enum Flag { FlagOverridesPaint = 1 << 1 }: Flags for controlling how an item behaves.
enum ReferencePoint { UpperLeft, UpperMiddle, UpperRight, MiddleLeft, Middle, MiddleRight, LowerLeft, LowerMiddle, LowerRight }: Fixed position reference point.
enum UndoCommand { UndoNone = -1, UndoIncrementalMove = 1, UndoIncrementalResize, UndoStrokeColor, UndoStrokeWidth, UndoBackgroundColor, UndoOpacity, UndoSetId, UndoRotation, UndoShapeStyle, UndoShapeCornerRadius, UndoNodeMove, UndoAtlasMargin, UndoMapRotation, UndoZoomContent, UndoOverviewStyle, UndoGridFramePenColor, UndoMapGridFrameFill1Color, UndoMapGridFrameFill2Color, UndoMapAnnotationDistance, UndoMapGridAnnotationFontColor, UndoMapGridLineSymbol, UndoMapGridMarkerSymbol, UndoMapLabelMargin, UndoPictureRotation, UndoPictureFillColor, UndoPictureStrokeColor, UndoPictureStrokeWidth, UndoPictureNorthOffset, UndoLabelText, UndoLabelFont, UndoLabelMargin, UndoLabelFontColor, UndoLegendText, UndoLegendColumnCount, UndoLegendSymbolWidth, UndoLegendSymbolHeight, UndoLegendWmsLegendWidth, UndoLegendWmsLegendHeight, UndoLegendTitleSpaceBottom, UndoLegendGroupSpace, UndoLegendLayerSpace, UndoLegendSymbolSpace, UndoLegendIconSymbolSpace, UndoLegendFontColor, UndoLegendBoxSpace, UndoLegendColumnSpace, UndoLegendLineSpacing, UndoLegendRasterStrokeWidth, UndoLegendRasterStrokeColor, UndoLegendTitleFont, UndoLegendGroupFont, UndoLegendLayerFont, UndoLegendItemFont, UndoScaleBarLineWidth, UndoScaleBarSegmentSize, UndoScaleBarSegmentsLeft, UndoScaleBarSegments, UndoScaleBarHeight, UndoScaleBarFontColor, UndoScaleBarFillColor, UndoScaleBarFillColor2, UndoScaleBarStrokeColor, UndoScaleBarUnitText, UndoScaleBarMapUnitsSegment, UndoScaleBarLabelBarSize, UndoScaleBarBoxContentSpace, UndoArrowStrokeWidth, UndoArrowHeadWidth, UndoArrowHeadFillColor, UndoArrowHeadStrokeColor, UndoCustomCommand }: Layout item undo commands, used for collapsing undo commands.

Constructors, destructors, conversion operators

QgsLayoutItem(QgsLayout* layout, bool manageZValue = true) explicit: Constructor for QgsLayoutItem, with the specified parent layout.

Public functions

void attemptMove(const QgsLayoutPoint& point, bool useReferencePoint = true, bool includesFrame = false, int page = -1) virtual: Attempts to move the item to a specified point.
void attemptMoveBy(double deltaX, double deltaY): Attempts to shift the item's position by a specified deltaX and deltaY, in layout units.
void attemptResize(const QgsLayoutSize& size, bool includesFrame = false) virtual: Attempts to resize the item to a specified target size.
void attemptSetSceneRect(const QRectF& rect, bool includesFrame = false): Attempts to update the item's position and size to match the passed rect in layout coordinates.
auto backgroundColor() const -> QColor: Returns the background color for this item.
void beginCommand(const QString& commandText, UndoCommand command = UndoNone): Starts new undo command for this item.
auto blendMode() const -> QPainter::CompositionMode: Returns the item's composition blending mode.
void cancelCommand(): Cancels the current item command and discards it.
void cleanup() virtual: Called just before a batch of items are deleted, allowing them to run cleanup tasks.
auto containsAdvancedEffects() const -> bool virtual: Returns true if the item contains contents with blend modes or transparency effects which can only be reproduced by rastering the item.
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 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 virtual: Gets item display name.
void endCommand(): Completes the current item command and push it onto the layout's undo stack.
auto estimatedFrameBleed() const -> double virtual: Returns the estimated amount the item's frame bleeds outside the item's actual rectangle.
auto excludeFromExports() const -> bool: Returns whether the item should be excluded from layout exports and prints.
void finalizeRestoreFromXml() virtual: Called after all pending items have been restored from XML.
auto fixedSize() const -> QgsLayoutSize virtual: Returns the fixed size of the item, if applicable, or an empty size if item can be freely resized.
auto frameEnabled() const -> bool: Returns true if the item includes a frame.
auto frameJoinStyle() const -> Qt::PenJoinStyle: Returns the join style used for drawing the item's frame.
auto frameStrokeColor() const -> QColor: Returns the frame's stroke color.
auto frameStrokeWidth() const -> QgsLayoutMeasurement: Returns the frame's stroke width.
auto hasBackground() const -> bool: Returns true if the item has a background.
auto icon() const -> QIcon virtual: Returns the item's icon.
auto id() const -> QString: Returns the item's ID name.
auto isGroupMember() const -> bool: Returns true if the item is part of a QgsLayoutItemGroup group.
auto isLocked() const -> bool: Returns true if the item is locked, and cannot be interacted with using the mouse.
auto itemFlags() const -> Flags virtual: Returns the item's flags, which indicate how the item behaves.
auto itemOpacity() const -> double: Returns the item's opacity.
auto itemRotation() const -> double: Returns the current rotation for the item, in degrees clockwise.
auto minimumSize() const -> QgsLayoutSize virtual: Returns the minimum allowed size of the item, if applicable, or an empty size if item can be freely resized.
void moveContent(double dx, double dy) virtual: Moves the content of the item, by a specified dx and dy in layout units.
auto numberExportLayers() const -> int virtual: Returns the number of layers that this item requires for exporting during layered exports (e.g.
auto page() const -> int: Returns the page the item is currently on, with the first page returning 0.
auto pagePos() const -> QPointF: Returns the item's position (in layout units) relative to the top left corner of its current page.
auto pagePositionWithUnits() const -> QgsLayoutPoint: Returns the item's position (in item units) relative to the top left corner of its current page.
void paint(QPainter* painter, const QStyleOptionGraphicsItem* itemStyle, QWidget* pWidget) override: Handles preparing a paint surface for the layout item and painting the item's content.
auto parentGroup() const -> QgsLayoutItemGroup*: Returns the item's parent group, if the item is part of a QgsLayoutItemGroup group.
auto positionWithUnits() const -> QgsLayoutPoint: Returns the item's current position, including units.
auto readXml(const QDomElement& itemElement, const QDomDocument& document, const QgsReadWriteContext& context) -> bool: Sets the item state from a DOM element.
auto rectWithFrame() const -> QRectF virtual: Returns the item's rectangular bounds, including any bleed caused by the item's frame.
auto referencePoint() const -> ReferencePoint: Returns the reference point for positioning of the layout item.
auto requiresRasterization() const -> bool virtual: Returns true if the item is drawn in such a way that forces the whole layout to be rasterized when exporting to vector formats.
void setBackgroundColor(const QColor& color): Sets the background color for this item.
void setBackgroundEnabled(bool drawBackground): Sets whether this item has a background drawn under it or not.
void setBlendMode(QPainter::CompositionMode mode): Sets the item's composition blending mode.
void setExcludeFromExports(bool exclude): Sets whether the item should be excluded from layout exports and prints.
void setFrameEnabled(bool drawFrame) virtual: Sets whether this item has a frame drawn around it or not.
void setFrameJoinStyle(Qt::PenJoinStyle style): Sets the join style used when drawing the item's frame.
void setFrameStrokeColor(const QColor& color): Sets the frame stroke color.
void setFrameStrokeWidth(QgsLayoutMeasurement width) virtual: Sets the frame stroke width.
void setId(const QString& id) virtual: Set the item's id name.
void setItemOpacity(double opacity): Sets the item's opacity.
void setLocked(bool locked): Sets whether the item is locked, preventing mouse interactions with the item.
void setMoveContentPreviewOffset(double dx, double dy) virtual: Sets temporary offset for the item, by a specified dx and dy in layout units.
void setParentGroup(QgsLayoutItemGroup* group): Sets the item's parent group.
void setReferencePoint(ReferencePoint point): Sets the reference point for positioning of the layout item.
void setSelected(bool selected) virtual: Sets whether the item should be selected.
void setVisibility(bool visible) virtual: Sets whether the item is visible.
auto shouldDrawItem() const -> bool: Returns whether the item should be drawn in the current context.
auto sizeWithUnits() const -> QgsLayoutSize: Returns the item's current size, including units.
auto type() const -> int override: Returns a unique graphics item type identifier.
auto uuid() const -> QString virtual: Returns the item identification string.
auto writeXml(QDomElement& parentElement, QDomDocument& document, const QgsReadWriteContext& context) const -> bool: Stores the item state in a DOM element.
void zoomContent(double factor, QPointF point) virtual: Zooms content of item.

Signals

void frameChanged(): Emitted if the item's frame style changes.
void lockChanged(): Emitted if the item's lock status changes.
void rotationChanged(double newRotation): Emitted on item rotation change.
void sizePositionChanged(): Emitted when the item's size or position changes.

Public slots

void invalidateCache() virtual: Forces a deferred update of any cached image the item uses.
void redraw() virtual: Triggers a redraw (update) of the item.
void refresh() override: Refreshes the item, causing a recalculation of any property overrides and recalculation of its position and size.
void refreshDataDefinedProperty(QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties) virtual: Refreshes a data defined property for the item by reevaluating the property's value and redrawing the item with this new value.
void rotateItem(double angle, QPointF transformOrigin) virtual: Rotates the item by a specified angle in degrees clockwise around a specified reference point.
void setItemRotation(double rotation, bool adjustPosition = true) virtual: Sets the layout item's rotation, in degrees clockwise.

Protected functions

auto adjustPointForReferencePosition(QPointF point, QSizeF size, ReferencePoint reference) const -> QPointF: Adjusts the specified point at which a reference position of the item sits and returns the top left corner of the item, if reference point were placed at the specified position.
auto applyDataDefinedSize(const QgsLayoutSize& size) -> QgsLayoutSize: Applies any present data defined size overrides to the specified layout size.
auto applyItemSizeConstraint(QSizeF targetSize) -> QSizeF virtual: Applies any item-specific size constraint handling to a given targetSize in layout units.
void draw(QgsLayoutItemRenderContext& context) pure virtual: Draws the item's contents using the specified item render context.
void drawBackground(QgsRenderContext& context) virtual: Draws the background for the item.
void drawDebugRect(QPainter* painter) virtual: Draws a debugging rectangle of the item's current bounds within the specified painter.
void drawFrame(QgsRenderContext& context) virtual: Draws the frame around the item.
auto positionAtReferencePoint(ReferencePoint reference) const -> QPointF: Returns the current position (in layout units) of a reference point for the item.
auto readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) -> bool virtual: Sets item state from a DOM element.
void refreshBackgroundColor(bool updateItem = true): Refresh item's background color, considering data defined colors.
void refreshBlendMode(): Refresh item's blend mode, considering data defined blend mode.
void refreshFrame(bool updateItem = true): Refresh item's frame, considering data defined colors and frame size.
void refreshItemPosition(): Refreshes an item's position by rechecking it against any possible overrides such as data defined positioning.
void refreshItemRotation(QPointF* origin = nullptr): Refreshes an item's rotation by rechecking it against any possible overrides such as data defined rotation.
void refreshItemSize(): Refreshes an item's size by rechecking it against any possible item fixed or minimum sizes.
void refreshOpacity(bool updateItem = true): Refresh item's opacity, considering data defined opacity.
void setFixedSize(const QgsLayoutSize& size) virtual: Sets a fixed size for the layout item, which prevents it from being freely resized.
void setMinimumSize(const QgsLayoutSize& size) virtual: Sets the minimum allowed size for the layout item.
auto topLeftToReferencePoint(const QgsLayoutPoint& point) const -> QgsLayoutPoint: Returns the position for the reference point of the item, if the top-left of the item was placed at the specified point.
auto writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const -> bool virtual: Stores item state within an XML DOM element.

Enum documentation

enum QgsLayoutItem::Flag

Flags for controlling how an item behaves.

Enumerators
FlagOverridesPaint	Item overrides the default layout item painting method.

enum QgsLayoutItem::ReferencePoint

Fixed position reference point.

Enumerators
UpperLeft	Upper left corner of item.
UpperMiddle	Upper center of item.
UpperRight	Upper right corner of item.
MiddleLeft	Middle left of item.
Middle	Center of item.
MiddleRight	Middle right of item.
LowerLeft	Lower left corner of item.
LowerMiddle	Lower center of item.
LowerRight	Lower right corner of item.

enum QgsLayoutItem::UndoCommand

Layout item undo commands, used for collapsing undo commands.

Enumerators
UndoNone	No command suppression.
UndoIncrementalMove	Layout item incremental movement, e.g. as a result of a keypress.
UndoIncrementalResize	Incremental resize.
UndoStrokeColor	Stroke color adjustment.
UndoStrokeWidth	Stroke width adjustment.
UndoBackgroundColor	Background color adjustment.
UndoOpacity	Opacity adjustment.
UndoSetId	Change item ID.
UndoRotation	Rotation adjustment.
UndoShapeStyle	Shape symbol style.
UndoShapeCornerRadius	Shape corner radius.
UndoNodeMove	Node move.
UndoAtlasMargin	Map atlas margin changed.
UndoMapRotation	Map rotation changed.
UndoZoomContent	Item content zoomed.
UndoOverviewStyle	Map overview style.
UndoGridFramePenColor	Map grid frame pen color.
UndoMapGridFrameFill1Color	Map grid frame fill color 1.
UndoMapGridFrameFill2Color	Map grid frame fill color 2.
UndoMapAnnotationDistance	Map frame annotation distance.
UndoMapGridAnnotationFontColor	Map frame annotation color.
UndoMapGridLineSymbol	Grid line symbol.
UndoMapGridMarkerSymbol	Grid marker symbol.
UndoMapLabelMargin	Margin for labels from edge of map.
UndoPictureRotation	Picture rotation.
UndoPictureFillColor	Picture fill color.
UndoPictureStrokeColor	Picture stroke color.
UndoPictureStrokeWidth	Picture stroke width.
UndoPictureNorthOffset	Picture north offset.
UndoLabelText	Label text.
UndoLabelFont	Label font.
UndoLabelMargin	Label margin.
UndoLabelFontColor	Label color.
UndoLegendText	Legend text.
UndoLegendColumnCount	Legend column count.
UndoLegendSymbolWidth	Legend symbol width.
UndoLegendSymbolHeight	Legend symbol height.
UndoLegendWmsLegendWidth	Legend WMS width.
UndoLegendWmsLegendHeight	Legend WMS height.
UndoLegendTitleSpaceBottom	Legend title space.
UndoLegendGroupSpace	Legend group spacing.
UndoLegendLayerSpace	Legend layer spacing.
UndoLegendSymbolSpace	Legend symbol spacing.
UndoLegendIconSymbolSpace	Legend icon symbol space.
UndoLegendFontColor	Legend font color.
UndoLegendBoxSpace	Legend box space.
UndoLegendColumnSpace	Legend column space.
UndoLegendLineSpacing	Legend line spacing.
UndoLegendRasterStrokeWidth	Legend raster stroke width.
UndoLegendRasterStrokeColor	Legend raster stroke color.
UndoLegendTitleFont	Legend title font.
UndoLegendGroupFont	Legend group font.
UndoLegendLayerFont	Legend layer font.
UndoLegendItemFont	Legend item font.
UndoScaleBarLineWidth	Scalebar line width.
UndoScaleBarSegmentSize	Scalebar segment size.
UndoScaleBarSegmentsLeft	Scalebar segments left.
UndoScaleBarSegments	Scalebar number of segments.
UndoScaleBarHeight	Scalebar height.
UndoScaleBarFontColor	Scalebar font color.
UndoScaleBarFillColor	Scalebar fill color.
UndoScaleBarFillColor2	Scalebar secondary fill color.
UndoScaleBarStrokeColor	Scalebar stroke color.
UndoScaleBarUnitText	Scalebar unit text.
UndoScaleBarMapUnitsSegment	Scalebar map units per segment.
UndoScaleBarLabelBarSize	Scalebar label bar size.
UndoScaleBarBoxContentSpace	Scalebar box context space.
UndoArrowStrokeWidth	Arrow stroke width.
UndoArrowHeadWidth	Arrow head width.
UndoArrowHeadFillColor	Arrow head fill color.
UndoArrowHeadStrokeColor	Arrow head stroke color.
UndoCustomCommand	Base id for plugin based item undo commands.

Function documentation

QgsLayoutItem::QgsLayoutItem(QgsLayout* layout, bool manageZValue = true) explicit

Constructor for QgsLayoutItem, with the specified parent layout.

If manageZValue is true, the z-Value of this item will be managed by the layout. Generally this is the desired behavior.

void QgsLayoutItem::attemptMove(const QgsLayoutPoint& point, bool useReferencePoint = true, bool includesFrame = false, int page = -1) virtual

Attempts to move the item to a specified point.

If useReferencePoint is true, this method will respect the item's reference point, in that the item will be moved so that its current reference point is placed at the specified target point.

If useReferencePoint is false, the item will be moved so that point falls at the top-left corner of the item.

If includesFrame is true, then the position specified by point represents the point at which to place the outside of the item's frame.

If page is not left at the default -1 value, then the position specified by point refers to the relative position on the corresponding layout page (where a page of 0 represents the first page).

Note that the final position of the item may not match the specified target position, as data defined item position may override the specified value.

void QgsLayoutItem::attemptMoveBy(double deltaX, double deltaY)

Attempts to shift the item's position by a specified deltaX and deltaY, in layout units.

Note that the final position of the item may not match the specified offsets, as data defined item position and size may override the specified value.

void QgsLayoutItem::attemptResize(const QgsLayoutSize& size, bool includesFrame = false) virtual

Attempts to resize the item to a specified target size.

Note that the final size of the item may not match the specified target size, as items with a fixed or minimum size will place restrictions on the allowed item size. Data defined item size overrides will also override the specified target size.

If includesFrame is true, then the size specified by size includes the item's frame.

void QgsLayoutItem::attemptSetSceneRect(const QRectF& rect, bool includesFrame = false)

Attempts to update the item's position and size to match the passed rect in layout coordinates.

If includesFrame is true, then the position and size specified by rect represents the position and size at for the outside of the item's frame.

Note that the final position and size of the item may not match the specified target rect, as data defined item position and size may override the specified value.

QColor QgsLayoutItem::backgroundColor() const

Returns the background color for this item.

This is only used if hasBackground() returns true.

void QgsLayoutItem::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.

QPainter::CompositionMode QgsLayoutItem::blendMode() const

Returns the item's composition blending mode.

void QgsLayoutItem::cancelCommand()

Cancels the current item command and discards it.

bool QgsLayoutItem::containsAdvancedEffects() const virtual

Returns true if the item contains contents with blend modes or transparency effects which can only be reproduced by rastering the item.

Subclasses should ensure that implemented overrides of this method also check the base class result.

QgsAbstractLayoutUndoCommand* QgsLayoutItem::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.

QgsExpressionContext QgsLayoutItem::createExpressionContext() const override

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

QString QgsLayoutItem::displayName() const virtual

Gets item display name.

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

void QgsLayoutItem::endCommand()

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

double QgsLayoutItem::estimatedFrameBleed() const virtual

Returns the estimated amount the item's frame bleeds outside the item's actual rectangle.

For instance, if the item has a 2mm frame stroke, then 1mm of this frame is drawn outside the item's rect. In this case the return value will be 1.0.

Returned values are in layout units.

bool QgsLayoutItem::excludeFromExports() const

Returns whether the item should be excluded from layout exports and prints.

void QgsLayoutItem::finalizeRestoreFromXml() virtual

Called after all pending items have been restored from XML.

Items 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.

QgsLayoutSize QgsLayoutItem::fixedSize() const virtual

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

bool QgsLayoutItem::frameEnabled() const

Returns true if the item includes a frame.

Qt::PenJoinStyle QgsLayoutItem::frameJoinStyle() const

Returns the join style used for drawing the item's frame.

QColor QgsLayoutItem::frameStrokeColor() const

Returns the frame's stroke color.

This is only used if frameEnabled() returns true.

QgsLayoutMeasurement QgsLayoutItem::frameStrokeWidth() const

Returns the frame's stroke width.

This is only used if frameEnabled() returns true.

bool QgsLayoutItem::hasBackground() const

Returns true if the item has a background.

QString QgsLayoutItem::id() const

Returns the item's ID name.

This is not necessarily unique, and duplicate ID names may exist for a layout.

bool QgsLayoutItem::isGroupMember() const

Returns true if the item is part of a QgsLayoutItemGroup group.

bool QgsLayoutItem::isLocked() const

Returns true if the item is locked, and cannot be interacted with using the mouse.

Flags QgsLayoutItem::itemFlags() const virtual

Returns the item's flags, which indicate how the item behaves.

double QgsLayoutItem::itemOpacity() const

Returns the item's opacity.

Returns	opacity as double between 1.0 (opaque) and 0 (transparent).

This method should be used instead of QGraphicsItem::opacity() as any data defined overrides will be respected.

double QgsLayoutItem::itemRotation() const

Returns the current rotation for the item, in degrees clockwise.

Note that this method will always return the user-set rotation for the item, which may differ from the current item rotation (if data defined rotation settings are present). Use QGraphicsItem::rotation() to obtain the current item rotation.

QgsLayoutSize QgsLayoutItem::minimumSize() const virtual

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

void QgsLayoutItem::moveContent(double dx, double dy) virtual

Moves the content of the item, by a specified dx and dy in layout units.

The default implementation has no effect.

int QgsLayoutItem::numberExportLayers() const virtual

Returns the number of layers that this item requires for exporting during layered exports (e.g.

SVG). Returns 0 if this item is to be placed on the same layer as the previous item, 1 if it should be placed on its own layer, and >1 if it requires multiple export layers.

Items which require multiply layers should check QgsLayoutContext::currentExportLayer() during their rendering to determine which layer should be drawn.

int QgsLayoutItem::page() const

Returns the page the item is currently on, with the first page returning 0.

QPointF QgsLayoutItem::pagePos() const

Returns the item's position (in layout units) relative to the top left corner of its current page.

QgsLayoutPoint QgsLayoutItem::pagePositionWithUnits() const

Returns the item's position (in item units) relative to the top left corner of its current page.

void QgsLayoutItem::paint(QPainter* painter, const QStyleOptionGraphicsItem* itemStyle, QWidget* pWidget) override

Handles preparing a paint surface for the layout item and painting the item's content.

Derived classes must not override this method, but instead implement the pure virtual method QgsLayoutItem::draw.

QgsLayoutItemGroup* QgsLayoutItem::parentGroup() const

Returns the item's parent group, if the item is part of a QgsLayoutItemGroup group.

QgsLayoutPoint QgsLayoutItem::positionWithUnits() const

Returns the item's current position, including units.

The position returned is the position of the item's reference point, which may not necessarily be the top left corner of the item.

bool QgsLayoutItem::readXml(const QDomElement& itemElement, const QDomDocument& document, const QgsReadWriteContext& context)

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

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 readXml().

QRectF QgsLayoutItem::rectWithFrame() const virtual

Returns the item's rectangular bounds, including any bleed caused by the item's frame.

The bounds are returned in the item's coordinate system (see Qt's QGraphicsItem docs for more details about QGraphicsItem coordinate systems). The results differ from Qt's rect() function, as rect() makes no allowances for the portion of outlines which are drawn outside of the item.

ReferencePoint QgsLayoutItem::referencePoint() const

Returns the reference point for positioning of the layout item.

This point is also fixed during resizing of the item, and any size changes will be performed so that the position of the reference point within the layout remains unchanged.

bool QgsLayoutItem::requiresRasterization() const virtual

Returns true if the item is drawn in such a way that forces the whole layout to be rasterized when exporting to vector formats.

void QgsLayoutItem::setBackgroundColor(const QColor& color)

Sets the background color for this item.

void QgsLayoutItem::setBackgroundEnabled(bool drawBackground)

Sets whether this item has a background drawn under it or not.

void QgsLayoutItem::setBlendMode(QPainter::CompositionMode mode)

Sets the item's composition blending mode.

void QgsLayoutItem::setExcludeFromExports(bool exclude)

Sets whether the item should be excluded from layout exports and prints.

void QgsLayoutItem::setFrameEnabled(bool drawFrame) virtual

Sets whether this item has a frame drawn around it or not.

void QgsLayoutItem::setFrameJoinStyle(Qt::PenJoinStyle style)

Sets the join style used when drawing the item's frame.

void QgsLayoutItem::setFrameStrokeColor(const QColor& color)

Sets the frame stroke color.

void QgsLayoutItem::setFrameStrokeWidth(QgsLayoutMeasurement width) virtual

Sets the frame stroke width.

void QgsLayoutItem::setId(const QString& id) virtual

Set the item's id name.

This is not necessarily unique, and duplicate ID names may exist for a layout.

void QgsLayoutItem::setItemOpacity(double opacity)

Sets the item's opacity.

Parameters
opacity	double between 1.0 (opaque) and 0 (transparent).

This method should be used instead of QGraphicsItem::setOpacity() as any data defined overrides will be respected.

void QgsLayoutItem::setLocked(bool locked)

Sets whether the item is locked, preventing mouse interactions with the item.

void QgsLayoutItem::setMoveContentPreviewOffset(double dx, double dy) virtual

Sets temporary offset for the item, by a specified dx and dy in layout units.

This is useful for live updates when moving item content in a QgsLayoutView. The default implementation has no effect.

void QgsLayoutItem::setParentGroup(QgsLayoutItemGroup* group)

Sets the item's parent group.

void QgsLayoutItem::setReferencePoint(ReferencePoint point)

Sets the reference point for positioning of the layout item.

This point is also fixed during resizing of the item, and any size changes will be performed so that the position of the reference point within the layout remains unchanged.

void QgsLayoutItem::setVisibility(bool visible) virtual

Sets whether the item is visible.

QgsLayoutSize QgsLayoutItem::sizeWithUnits() const

Returns the item's current size, including units.

int QgsLayoutItem::type() const override

Returns a unique graphics item type identifier.

Plugin based subclasses should return an identifier greater than QgsLayoutItemRegistry::PluginItem.

QString QgsLayoutItem::uuid() const virtual

Returns the item identification string.

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

bool QgsLayoutItem::writeXml(QDomElement& parentElement, QDomDocument& document, const QgsReadWriteContext& context) const

Stores the item state in a DOM element.

Parameters
parentElement	parent DOM element (e.g. 'Layout' element)
document	DOM document
context	read write context

void QgsLayoutItem::zoomContent(double factor, QPointF point) virtual

Zooms content of item.

Parameters
factor	zoom factor, where > 1 results in a zoom in and < 1 results in a zoom out
point	item point for zoom center

Does nothing by default.

void QgsLayoutItem::lockChanged() signal

Emitted if the item's lock status changes.

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

Refreshes a data defined property for the item 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.

void QgsLayoutItem::rotateItem(double angle, QPointF transformOrigin) virtual public slot

Rotates the item by a specified angle in degrees clockwise around a specified reference point.

void QgsLayoutItem::setItemRotation(double rotation, bool adjustPosition = true) virtual public slot

Sets the layout item's rotation, in degrees clockwise.

If adjustPosition is true, then this rotation occurs around the center of the item. If adjustPosition is false, rotation occurs around the item origin.

QSizeF QgsLayoutItem::applyItemSizeConstraint(QSizeF targetSize) virtual protected

Applies any item-specific size constraint handling to a given targetSize in layout units.

Subclasses can override this method if they need to apply advanced logic regarding item sizes, which cannot be covered by setFixedSize() or setMinimumSize(). Item size constraints are applied after fixed, minimum and data defined size constraints.

void QgsLayoutItem::draw(QgsLayoutItemRenderContext& context) pure virtual 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.

void QgsLayoutItem::drawDebugRect(QPainter* painter) virtual protected

Draws a debugging rectangle of the item's current bounds within the specified painter.

Parameters
painter	destination QPainter

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

Sets item state from a DOM element.

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

void QgsLayoutItem::refreshBackgroundColor(bool updateItem = true) protected

Refresh item's background color, considering data defined colors.

If updateItem is set to false, the item will not be automatically updated after the frame color is set and a later call to update() must be made.

void QgsLayoutItem::refreshFrame(bool updateItem = true) protected

Refresh item's frame, considering data defined colors and frame size.

If updateItem is set to false, the item will not be automatically updated after the frame is set and a later call to update() must be made.

void QgsLayoutItem::refreshItemPosition() protected

Refreshes an item's position by rechecking it against any possible overrides such as data defined positioning.

void QgsLayoutItem::refreshItemRotation(QPointF* origin = nullptr) protected

Refreshes an item's rotation by rechecking it against any possible overrides such as data defined rotation.

The optional origin point specifies the origin (in item coordinates) around which the rotation should be applied.

void QgsLayoutItem::refreshItemSize() protected

Refreshes an item's size by rechecking it against any possible item fixed or minimum sizes.

void QgsLayoutItem::refreshOpacity(bool updateItem = true) protected

Refresh item's opacity, considering data defined opacity.

If updateItem is set to false the item will not be automatically updated after the opacity is set and a later call to update() must be made.

void QgsLayoutItem::setFixedSize(const QgsLayoutSize& size) virtual protected

Sets a fixed size for the layout item, which prevents it from being freely resized.

Set an empty size if item can be freely resized.

void QgsLayoutItem::setMinimumSize(const QgsLayoutSize& size) virtual protected

Sets the minimum allowed size for the layout item.