Base class for graphical items within a QgsLayout. More...

#include <qgslayoutitem.h>

Inheritance diagram for QgsLayoutItem:

[legend]

Classes
struct	ExportLayerDetail
	Contains details of a particular export layer relating to a layout item. More...

Public Types
enum	ExportLayerBehavior { CanGroupWithAnyOtherItem , CanGroupWithItemsOfSameType , MustPlaceInOwnLayer , ItemContainsSubLayers }
	Behavior of item when exporting to layered outputs. More...

enum	Flag { FlagOverridesPaint = 1 << 1 , FlagProvidesClipPath = 1 << 2 }
	Flags for controlling how an item behaves. More...

enum	ReferencePoint { UpperLeft , UpperMiddle , UpperRight , MiddleLeft , Middle , MiddleRight , LowerLeft , LowerMiddle , LowerRight }
	Fixed position reference point. More...

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 , UndoMapGridIntervalRange , UndoMapLabelMargin , UndoPictureRotation , UndoPictureFillColor , UndoPictureStrokeColor , UndoPictureStrokeWidth , UndoPictureNorthOffset , UndoLabelText , UndoLabelFont , UndoLabelMargin , UndoLabelFontColor , UndoLegendText , UndoLegendColumnCount , UndoLegendSymbolWidth , UndoLegendSymbolHeight , UndoLegendMaxSymbolSize , UndoLegendMinSymbolSize , UndoLegendWmsLegendWidth , UndoLegendWmsLegendHeight , UndoLegendTitleSpaceBottom , UndoLegendGroupSpace , UndoLegendGroupIndent , UndoLegendSubgroupIndent , UndoLegendLayerSpace , UndoLegendSymbolSpace , UndoLegendIconSymbolSpace , UndoLegendFontColor , UndoLegendBoxSpace , UndoLegendColumnSpace , UndoLegendLineSpacing , UndoLegendRasterStrokeWidth , UndoLegendRasterStrokeColor , UndoLegendTitleFont , UndoLegendGroupFont , UndoLegendLayerFont , UndoLegendItemFont , UndoScaleBarLineWidth , UndoScaleBarSegmentSize , UndoScaleBarSegmentsLeft , UndoScaleBarSegments , UndoScaleBarHeight , UndoScaleBarSubdivisions , UndoScaleBarSubdivisionsHeight , UndoScaleBarFontColor , UndoScaleBarFillColor , UndoScaleBarFillColor2 , UndoScaleBarStrokeColor , UndoScaleBarUnitText , UndoScaleBarMapUnitsSegment , UndoScaleBarLabelBarSize , UndoScaleBarBoxContentSpace , UndoArrowStrokeWidth , UndoArrowHeadWidth , UndoArrowHeadFillColor , UndoArrowHeadStrokeColor , UndoCustomCommand }
	Layout item undo commands, used for collapsing undo commands. More...

Public Types inherited from QgsLayoutObject
enum	DataDefinedProperty { NoProperty = 0 , AllProperties , TestProperty , PresetPaperSize , PaperWidth , PaperHeight , NumPages , PaperOrientation , PageNumber , PositionX , PositionY , ItemWidth , ItemHeight , ItemRotation , Transparency , Opacity , BlendMode , ExcludeFromExports , FrameColor , BackgroundColor , MapRotation , MapScale , MapXMin , MapYMin , MapXMax , MapYMax , MapAtlasMargin , MapLayers , MapStylePreset , MapLabelMargin , MapGridEnabled , MapGridIntervalX , MapGridIntervalY , MapGridOffsetX , MapGridOffsetY , MapGridFrameSize , MapGridFrameMargin , MapGridLabelDistance , MapGridCrossSize , MapGridFrameLineThickness , MapGridAnnotationDisplayLeft , MapGridAnnotationDisplayRight , MapGridAnnotationDisplayTop , MapGridAnnotationDisplayBottom , MapGridFrameDivisionsLeft , MapGridFrameDivisionsRight , MapGridFrameDivisionsTop , MapGridFrameDivisionsBottom , PictureSource , PictureSvgBackgroundColor , PictureSvgStrokeColor , PictureSvgStrokeWidth , SourceUrl , LegendTitle , LegendColumnCount , ScalebarFillColor , ScalebarFillColor2 , ScalebarLineColor , ScalebarLineWidth , AttributeTableSourceLayer , MapCrs , StartDateTime , EndDateTime }
	Data defined properties for different item types. More...

enum	PropertyValueType { EvaluatedValue = 0 , OriginalValue }
	Specifies whether the value returned by a function should be the original, user set value, or the current evaluated value for the property. More...

Public Slots
virtual void	invalidateCache ()
	Forces a deferred update of any cached image the item uses. More...

virtual void	redraw ()
	Triggers a redraw (update) of the item. More...

void	refresh () override
	Refreshes the item, causing a recalculation of any property overrides and recalculation of its position and size. More...

virtual void	refreshDataDefinedProperty (QgsLayoutObject::DataDefinedProperty property=QgsLayoutObject::AllProperties)
	Refreshes a data defined property for the item by reevaluating the property's value and redrawing the item with this new value. More...

virtual void	rotateItem (double angle, QPointF transformOrigin)
	Rotates the item by a specified angle in degrees clockwise around a specified reference point. More...

virtual void	setItemRotation (double rotation, bool adjustPosition=true)
	Sets the layout item's rotation, in degrees clockwise. More...

Public Slots inherited from QgsLayoutObject
virtual void	refresh ()
	Refreshes the object, causing a recalculation of any property overrides. More...

Signals
void	backgroundTaskCountChanged (int count)
	Emitted whenever the number of background tasks an item is executing changes. More...

void	clipPathChanged ()
	Emitted when the item's clipping path has changed. More...

void	frameChanged ()
	Emitted if the item's frame style changes. More...

void	lockChanged ()
	Emitted if the item's lock status changes. More...

void	rotationChanged (double newRotation)
	Emitted on item rotation change. More...

void	sizePositionChanged ()
	Emitted when the item's size or position changes. More...

Signals inherited from QgsLayoutObject
void	changed ()
	Emitted when the object's properties change. More...

Public Member Functions
	QgsLayoutItem (QgsLayout *layout, bool manageZValue=true)
	Constructor for QgsLayoutItem, with the specified parent layout. More...

	~QgsLayoutItem () override

virtual bool	accept (QgsStyleEntityVisitorInterface *visitor) const
	Accepts the specified style entity visitor, causing it to visit all style entities associated with the layout item. More...

virtual void	attemptMove (const QgsLayoutPoint &point, bool useReferencePoint=true, bool includesFrame=false, int page=-1)
	Attempts to move the item to a specified point. More...

void	attemptMoveBy (double deltaX, double deltaY)
	Attempts to shift the item's position by a specified deltaX and deltaY, in layout units. More...

virtual void	attemptResize (const QgsLayoutSize &size, bool includesFrame=false)
	Attempts to resize the item to a specified target size. More...

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

QColor	backgroundColor () const
	Returns the background color for this item. More...

void	beginCommand (const QString &commandText, UndoCommand command=UndoNone)
	Starts new undo command for this item. More...

QPainter::CompositionMode	blendMode () const
	Returns the item's composition blending mode. More...

void	cancelCommand ()
	Cancels the current item command and discards it. More...

virtual void	cleanup ()
	Called just before a batch of items are deleted, allowing them to run cleanup tasks. More...

virtual QgsGeometry	clipPath () const
	Returns the clipping path generated by this item, in layout coordinates. More...

virtual bool	containsAdvancedEffects () const
	Returns `true` if the item contains contents with blend modes or transparency effects which can only be reproduced by rastering the item. More...

QgsAbstractLayoutUndoCommand *	createCommand (const QString &text, int id, QUndoCommand *parent=nullptr) override
	Creates a new layout undo command with the specified text and parent. More...

QgsExpressionContext	createExpressionContext () const override
	This method needs to be reimplemented in all classes which implement this interface and return an expression context. More...

virtual QString	displayName () const
	Gets item display name. More...

void	endCommand ()
	Completes the current item command and push it onto the layout's undo stack. More...

virtual double	estimatedFrameBleed () const
	Returns the estimated amount the item's frame bleeds outside the item's actual rectangle. More...

bool	excludeFromExports () const
	Returns whether the item should be excluded from layout exports and prints. More...

virtual ExportLayerBehavior	exportLayerBehavior () const
	Returns the behavior of this item during exporting to layered exports (e.g. More...

virtual QgsLayoutItem::ExportLayerDetail	exportLayerDetails () const
	Returns the details for the specified current export layer. More...

virtual void	finalizeRestoreFromXml ()
	Called after all pending items have been restored from XML. More...

virtual QgsLayoutSize	fixedSize () const
	Returns the fixed size of the item, if applicable, or an empty size if item can be freely resized. More...

bool	frameEnabled () const
	Returns `true` if the item includes a frame. More...

Qt::PenJoinStyle	frameJoinStyle () const
	Returns the join style used for drawing the item's frame. More...

QColor	frameStrokeColor () const
	Returns the frame's stroke color. More...

QgsLayoutMeasurement	frameStrokeWidth () const
	Returns the frame's stroke width. More...

bool	hasBackground () const
	Returns `true` if the item has a background. More...

virtual QIcon	icon () const
	Returns the item's icon. More...

QString	id () const
	Returns the item's ID name. More...

bool	isGroupMember () const
	Returns `true` if the item is part of a QgsLayoutItemGroup group. More...

bool	isLocked () const
	Returns `true` if the item is locked, and cannot be interacted with using the mouse. More...

virtual Flags	itemFlags () const
	Returns the item's flags, which indicate how the item behaves. More...

double	itemOpacity () const
	Returns the item's opacity. More...

double	itemRotation () const
	Returns the current rotation for the item, in degrees clockwise. More...

virtual QgsLayoutSize	minimumSize () const
	Returns the minimum allowed size of the item, if applicable, or an empty size if item can be freely resized. More...

virtual void	moveContent (double dx, double dy)
	Moves the content of the item, by a specified dx and dy in layout units. More...

virtual bool	nextExportPart ()
	Moves to the next export part for a multi-layered export item, during a multi-layered export. More...

virtual Q_DECL_DEPRECATED int	numberExportLayers () const
	Returns the number of layers that this item requires for exporting during layered exports (e.g. More...

int	page () const
	Returns the page the item is currently on, with the first page returning 0. More...

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

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

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

QgsLayoutItemGroup *	parentGroup () const
	Returns the item's parent group, if the item is part of a QgsLayoutItemGroup group. More...

QgsLayoutPoint	positionWithUnits () const
	Returns the item's current position, including units. More...

bool	readXml (const QDomElement &itemElement, const QDomDocument &document, const QgsReadWriteContext &context)
	Sets the item state from a DOM element. More...

virtual QRectF	rectWithFrame () const
	Returns the item's rectangular bounds, including any bleed caused by the item's frame. More...

ReferencePoint	referencePoint () const
	Returns the reference point for positioning of the layout item. More...

virtual bool	requiresRasterization () const
	Returns `true` if the item is drawn in such a way that forces the whole layout to be rasterized when exporting to vector formats. More...

void	setBackgroundColor (const QColor &color)
	Sets the background color for this item. More...

void	setBackgroundEnabled (bool drawBackground)
	Sets whether this item has a background drawn under it or not. More...

void	setBlendMode (QPainter::CompositionMode mode)
	Sets the item's composition blending mode. More...

void	setExcludeFromExports (bool exclude)
	Sets whether the item should be excluded from layout exports and prints. More...

virtual void	setFrameEnabled (bool drawFrame)
	Sets whether this item has a frame drawn around it or not. More...

void	setFrameJoinStyle (Qt::PenJoinStyle style)
	Sets the join style used when drawing the item's frame. More...

void	setFrameStrokeColor (const QColor &color)
	Sets the frame stroke color. More...

virtual void	setFrameStrokeWidth (QgsLayoutMeasurement width)
	Sets the frame stroke width. More...

virtual void	setId (const QString &id)
	Set the item's id name. More...

void	setItemOpacity (double opacity)
	Sets the item's opacity. More...

void	setLocked (bool locked)
	Sets whether the item is locked, preventing mouse interactions with the item. More...

virtual void	setMoveContentPreviewOffset (double dx, double dy)
	Sets temporary offset for the item, by a specified dx and dy in layout units. More...

void	setParentGroup (QgsLayoutItemGroup *group)
	Sets the item's parent group. More...

void	setReferencePoint (ReferencePoint point)
	Sets the reference point for positioning of the layout item. More...

virtual void	setSelected (bool selected)
	Sets whether the item should be selected. More...

virtual void	setVisibility (bool visible)
	Sets whether the item is visible. More...

bool	shouldDrawItem () const
	Returns whether the item should be drawn in the current context. More...

QgsLayoutSize	sizeWithUnits () const
	Returns the item's current size, including units. More...

virtual void	startLayeredExport ()
	Starts a multi-layer export operation. More...

virtual void	stopLayeredExport ()
	Stops a multi-layer export operation. More...

int	type () const override
	Returns a unique graphics item type identifier. More...

virtual QString	uuid () const
	Returns the item identification string. More...

bool	writeXml (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context) const
	Stores the item state in a DOM element. More...

virtual void	zoomContent (double factor, QPointF point)
	Zooms content of item. More...

Public Member Functions inherited from QgsLayoutObject
	QgsLayoutObject (QgsLayout *layout)
	Constructor for QgsLayoutObject, with the specified parent layout. More...

QgsExpressionContext	createExpressionContext () const override
	Creates an expression context relating to the objects' current state. More...

QStringList	customProperties () const
	Returns list of keys stored in custom properties for the object. More...

QVariant	customProperty (const QString &key, const QVariant &defaultValue=QVariant()) const
	Read a custom property from the object. More...

QgsPropertyCollection &	dataDefinedProperties ()
	Returns a reference to the object's property collection, used for data defined overrides. More...

const QgsPropertyCollection &	dataDefinedProperties () const
	Returns a reference to the object's property collection, used for data defined overrides. More...

QgsLayout *	layout ()
	Returns the layout the object is attached to. More...

const QgsLayout *	layout () const
	Returns the layout the object is attached to. More...

void	removeCustomProperty (const QString &key)
	Remove a custom property from the object. More...

void	setCustomProperty (const QString &key, const QVariant &value)
	Set a custom property for the object. More...

void	setDataDefinedProperties (const QgsPropertyCollection &collection)
	Sets the objects's property collection, used for data defined overrides. More...

Public Member Functions inherited from QgsExpressionContextGenerator
virtual	~QgsExpressionContextGenerator ()=default

Public Member Functions inherited from QgsLayoutUndoObjectInterface
virtual	~QgsLayoutUndoObjectInterface ()=default
	Destructor for QgsLayoutUndoObjectInterface. More...

Protected Member Functions
QPointF	adjustPointForReferencePosition (QPointF point, QSizeF size, ReferencePoint reference) const
	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. More...

QgsLayoutSize	applyDataDefinedSize (const QgsLayoutSize &size)
	Applies any present data defined size overrides to the specified layout size. More...

virtual QSizeF	applyItemSizeConstraint (QSizeF targetSize)
	Applies any item-specific size constraint handling to a given targetSize in layout units. More...

virtual void	draw (QgsLayoutItemRenderContext &context)=0
	Draws the item's contents using the specified item render context. More...

virtual void	drawBackground (QgsRenderContext &context)
	Draws the background for the item. More...

virtual void	drawDebugRect (QPainter *painter)
	Draws a debugging rectangle of the item's current bounds within the specified painter. More...

virtual void	drawFrame (QgsRenderContext &context)
	Draws the frame around the item. More...

virtual QPainterPath	framePath () const
	Returns the path to use when drawing the item's frame or background. More...

QPointF	positionAtReferencePoint (ReferencePoint reference) const
	Returns the current position (in layout units) of a reference point for the item. More...

virtual bool	readPropertiesFromElement (const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context)
	Sets item state from a DOM element. More...

void	refreshBackgroundColor (bool updateItem=true)
	Refresh item's background color, considering data defined colors. More...

void	refreshBlendMode ()
	Refresh item's blend mode, considering data defined blend mode. More...

void	refreshFrame (bool updateItem=true)
	Refresh item's frame, considering data defined colors and frame size. More...

void	refreshItemPosition ()
	Refreshes an item's position by rechecking it against any possible overrides such as data defined positioning. More...

void	refreshItemRotation (QPointF *origin=nullptr)
	Refreshes an item's rotation by rechecking it against any possible overrides such as data defined rotation. More...

void	refreshItemSize ()
	Refreshes an item's size by rechecking it against any possible item fixed or minimum sizes. More...

void	refreshOpacity (bool updateItem=true)
	Refresh item's opacity, considering data defined opacity. More...

virtual void	setFixedSize (const QgsLayoutSize &size)
	Sets a fixed size for the layout item, which prevents it from being freely resized. More...

virtual void	setMinimumSize (const QgsLayoutSize &size)
	Sets the minimum allowed size for the layout item. More...

QgsLayoutPoint	topLeftToReferencePoint (const QgsLayoutPoint &point) const
	Returns the position for the reference point of the item, if the top-left of the item was placed at the specified point. More...

virtual bool	writePropertiesToElement (QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context) const
	Stores item state within an XML DOM element. More...

Protected Member Functions inherited from QgsLayoutObject
bool	readObjectPropertiesFromElement (const QDomElement &parentElement, const QDomDocument &document, const QgsReadWriteContext &context)
	Sets object properties from a DOM element. More...

bool	writeObjectPropertiesToElement (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context) const
	Stores object properties within an XML DOM element. More...

Properties
bool	locked

Friends
class	QgsCompositionConverter

class	QgsLayout

class	QgsLayoutItemGroup

class	TestQgsLayoutItem

class	TestQgsLayoutView

Additional Inherited Members
Static Public Member Functions inherited from QgsLayoutObject
static bool	propertyAssociatesWithParentMultiframe (DataDefinedProperty property)
	Returns `true` if the specified property key is normally associated with the parent QgsLayoutMultiFrame object instead of a child QgsLayoutFrame object. More...

static const QgsPropertiesDefinition &	propertyDefinitions ()
	Returns the layout object property definitions. More...

Protected Attributes inherited from QgsLayoutObject
QgsObjectCustomProperties	mCustomProperties
	Custom properties for object. More...

QgsPropertyCollection	mDataDefinedProperties

QPointer< QgsLayout >	mLayout

Detailed Description

Base class for graphical items within a QgsLayout.

Since: QGIS 3.0

Definition at line 112 of file qgslayoutitem.h.

Member Enumeration Documentation

◆ ExportLayerBehavior

enum QgsLayoutItem::ExportLayerBehavior

Behavior of item when exporting to layered outputs.

Since: QGIS 3.10

Enumerator
CanGroupWithAnyOtherItem	Item can be placed on a layer with any other item (default behavior)
CanGroupWithItemsOfSameType	Item can only be placed on layers with other items of the same type, but multiple items of this type can be grouped together.
MustPlaceInOwnLayer	Item must be placed in its own individual layer.
ItemContainsSubLayers	Item contains multiple sublayers which must be individually exported.

Definition at line 429 of file qgslayoutitem.h.

◆ Flag

enum QgsLayoutItem::Flag

Flags for controlling how an item behaves.

Since: QGIS 3.4.3

Enumerator
FlagOverridesPaint	Item overrides the default layout item painting method.
FlagProvidesClipPath	Item can act as a clipping path provider (see clipPath())

Definition at line 303 of file qgslayoutitem.h.

◆ ReferencePoint

enum QgsLayoutItem::ReferencePoint

Fixed position reference point.

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

Definition at line 201 of file qgslayoutitem.h.

◆ UndoCommand

enum QgsLayoutItem::UndoCommand

Layout item undo commands, used for collapsing undo commands.

Enumerator
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.
UndoMapGridIntervalRange	Grid interval range.
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.
UndoLegendMaxSymbolSize	Legend maximum symbol size.
UndoLegendMinSymbolSize	Legend minimum symbol size.
UndoLegendWmsLegendWidth	Legend WMS width.
UndoLegendWmsLegendHeight	Legend WMS height.
UndoLegendTitleSpaceBottom	Legend title space.
UndoLegendGroupSpace	Legend group spacing.
UndoLegendGroupIndent	Legend group indent.
UndoLegendSubgroupIndent	Legend subgroup indent.
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.
UndoScaleBarSubdivisions	Scalebar number of subdivisions.
UndoScaleBarSubdivisionsHeight	Scalebar subdivisions 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.

Definition at line 215 of file qgslayoutitem.h.

Constructor & Destructor Documentation

◆ QgsLayoutItem()

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.

Definition at line 47 of file qgslayoutitem.cpp.

◆ ~QgsLayoutItem()

QgsLayoutItem::~QgsLayoutItem ( )

override

Definition at line 94 of file qgslayoutitem.cpp.

Member Function Documentation

◆ accept()

bool QgsLayoutItem::accept ( QgsStyleEntityVisitorInterface * visitor ) const

virtual

Accepts the specified style entity visitor, causing it to visit all style entities associated with the layout item.

Returns true if the visitor should continue visiting other objects, or false if visiting should be canceled.

Since: QGIS 3.10

Reimplemented in QgsLayoutItemShape, QgsLayoutItemScaleBar, QgsLayoutItemPolyline, QgsLayoutItemPolygon, QgsLayoutItemPage, QgsLayoutItemMarker, QgsLayoutItemMap, and QgsLayoutItemLegend.

Definition at line 1166 of file qgslayoutitem.cpp.

◆ adjustPointForReferencePosition()

QPointF QgsLayoutItem::adjustPointForReferencePosition	(	QPointF	point,
		QSizeF	size,
		ReferencePoint	reference
	)		const

protected

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.

Definition at line 1306 of file qgslayoutitem.cpp.

◆ applyDataDefinedSize()

QgsLayoutSize QgsLayoutItem::applyDataDefinedSize ( const QgsLayoutSize & size )

protected

Applies any present data defined size overrides to the specified layout size.

Definition at line 1032 of file qgslayoutitem.cpp.

◆ applyItemSizeConstraint()

QSizeF QgsLayoutItem::applyItemSizeConstraint ( QSizeF targetSize )

protectedvirtual

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.

See also: setFixedSize(); setMinimumSize()

Reimplemented in QgsLayoutItemPicture.

Definition at line 1264 of file qgslayoutitem.cpp.

◆ attemptMove()

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.

See also: attemptMoveBy(); attemptResize(); referencePoint(); positionWithUnits()

Reimplemented in QgsLayoutItemGroup.

Definition at line 467 of file qgslayoutitem.cpp.

◆ attemptMoveBy()

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.

See also: attemptResize(); attemptMove(); referencePoint(); positionWithUnits()

Definition at line 527 of file qgslayoutitem.cpp.

◆ attemptResize()

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.

See also: minimumSize(); fixedSize(); attemptMove(); sizeWithUnits()

Reimplemented in QgsLayoutItemPage, and QgsLayoutItemGroup.

Definition at line 429 of file qgslayoutitem.cpp.

◆ attemptSetSceneRect()

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.

See also: attemptResize(); attemptMove(); referencePoint(); positionWithUnits()

Definition at line 511 of file qgslayoutitem.cpp.

◆ backgroundColor()

QColor QgsLayoutItem::backgroundColor ( ) const

inline

Returns the background color for this item.

This is only used if hasBackground() returns true.

See also: setBackgroundColor(); hasBackground()

Definition at line 817 of file qgslayoutitem.h.

◆ backgroundTaskCountChanged

void QgsLayoutItem::backgroundTaskCountChanged ( int count )

signal

Emitted whenever the number of background tasks an item is executing changes.

Since: QGIS 3.10

◆ beginCommand()

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.

See also: endCommand(); cancelCommand()

Definition at line 968 of file qgslayoutitem.cpp.

◆ blendMode()

QPainter::CompositionMode QgsLayoutItem::blendMode ( ) const

inline

Returns the item's composition blending mode.

See also: setBlendMode()

Definition at line 830 of file qgslayoutitem.h.

◆ cancelCommand()

void QgsLayoutItem::cancelCommand ( )

Cancels the current item command and discards it.

See also: beginCommand(); endCommand()

Definition at line 982 of file qgslayoutitem.cpp.

◆ cleanup()

void QgsLayoutItem::cleanup ( )

virtual

Called just before a batch of items are deleted, allowing them to run cleanup tasks.

Reimplemented in QgsLayoutItemGroup, and QgsLayoutFrame.

Definition at line 99 of file qgslayoutitem.cpp.

◆ clipPath()

QgsGeometry QgsLayoutItem::clipPath ( ) const

virtual

Returns the clipping path generated by this item, in layout coordinates.

Note: Not all items can function as clipping paths. The FlagProvidesClipPath flag indicates if a particular item can function as a clipping path provider.

Since: QGIS 3.16

Reimplemented in QgsLayoutItemShape, and QgsLayoutItemPolygon.

Definition at line 1172 of file qgslayoutitem.cpp.

◆ clipPathChanged

void QgsLayoutItem::clipPathChanged ( )

signal

Emitted when the item's clipping path has changed.

See also: clipPath()

Since: QGIS 3.16

◆ containsAdvancedEffects()

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.

See also: requiresRasterization()

Reimplemented in QgsLayoutItemMap.

Definition at line 926 of file qgslayoutitem.cpp.

◆ createCommand()

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

overridevirtual

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.

Implements QgsLayoutUndoObjectInterface.

Reimplemented in QgsLayoutItemPage.

Definition at line 829 of file qgslayoutitem.cpp.

◆ createExpressionContext()

QgsExpressionContext QgsLayoutItem::createExpressionContext ( ) const

overridevirtual

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

Since: QGIS 3.0

Implements QgsExpressionContextGenerator.

Reimplemented in QgsLayoutItemMap, and QgsLayoutItemLegend.

Definition at line 1159 of file qgslayoutitem.cpp.

◆ displayName()

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.

See also: id(); setId()

Reimplemented in QgsLayoutItemShape, QgsLayoutItemPolyline, QgsLayoutItemPolygon, QgsLayoutItemPage, QgsLayoutItemMap, QgsLayoutItemLegend, QgsLayoutItemLabel, QgsLayoutItemGroup, QgsLayoutFrame, and QgsLayoutItem3DMap.

Definition at line 107 of file qgslayoutitem.cpp.

◆ draw()

virtual void QgsLayoutItem::draw ( QgsLayoutItemRenderContext & context )

protectedpure virtual

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.

Implemented in QgsLayoutItemShape, QgsLayoutItemScaleBar, QgsLayoutItemPicture, QgsLayoutItemPage, QgsLayoutNodesItem, QgsLayoutItemMarker, QgsLayoutItemMap, QgsLayoutItemLegend, QgsLayoutItemLabel, QgsLayoutItemGroup, QgsLayoutFrame, and QgsLayoutItem3DMap.

◆ drawBackground()

void QgsLayoutItem::drawBackground ( QgsRenderContext & context )

protectedvirtual

Draws the background for the item.

See also: framePath()

Reimplemented in QgsLayoutItemPage, and QgsLayoutFrame.

Definition at line 1237 of file qgslayoutitem.cpp.

◆ drawDebugRect()

void QgsLayoutItem::drawDebugRect ( QPainter * painter )

protectedvirtual

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

Parameters

painter destination QPainter

Definition at line 1200 of file qgslayoutitem.cpp.

◆ drawFrame()

void QgsLayoutItem::drawFrame ( QgsRenderContext & context )

protectedvirtual

Draws the frame around the item.

See also: framePath()

Reimplemented in QgsLayoutItemPage, and QgsLayoutFrame.

Definition at line 1221 of file qgslayoutitem.cpp.

◆ endCommand()

void QgsLayoutItem::endCommand ( )

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

See also: beginCommand(); cancelCommand()

Definition at line 976 of file qgslayoutitem.cpp.

◆ estimatedFrameBleed()

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.

See also: rectWithFrame()

Reimplemented in QgsLayoutItemShape, and QgsLayoutNodesItem.

Definition at line 937 of file qgslayoutitem.cpp.

◆ excludeFromExports()

bool QgsLayoutItem::excludeFromExports ( ) const

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

See also: setExcludeFromExports()

Definition at line 915 of file qgslayoutitem.cpp.

◆ exportLayerBehavior()

QgsLayoutItem::ExportLayerBehavior QgsLayoutItem::exportLayerBehavior ( ) const

virtual

Returns the behavior of this item during exporting to layered exports (e.g.

SVG).

See also: numberExportLayers(); exportLayerDetails()

Since: QGIS 3.10

Reimplemented in QgsLayoutItemScaleBar, QgsLayoutItemPage, QgsLayoutItemMap, QgsLayoutItemLegend, QgsLayoutItemGroup, and QgsLayoutFrame.

Definition at line 247 of file qgslayoutitem.cpp.

◆ exportLayerDetails()

QgsLayoutItem::ExportLayerDetail QgsLayoutItem::exportLayerDetails ( ) const

virtual

Returns the details for the specified current export layer.

Only valid between calls to startLayeredExport() and stopLayeredExport()

Since: QGIS 3.10

Reimplemented in QgsLayoutItemMap.

Definition at line 280 of file qgslayoutitem.cpp.

◆ finalizeRestoreFromXml()

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.

See also: readXml()

Reimplemented in QgsLayoutItemScaleBar, QgsLayoutItemPicture, QgsLayoutItemMarker, QgsLayoutItemMap, QgsLayoutItemLegend, QgsLayoutItemGroup, and QgsLayoutItem3DMap.

Definition at line 825 of file qgslayoutitem.cpp.

◆ fixedSize()

virtual QgsLayoutSize QgsLayoutItem::fixedSize ( ) const

inlinevirtual

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

See also: setFixedSize(); minimumSize()

Reimplemented in QgsLayoutItemMarker, and QgsLayoutFrame.

Definition at line 554 of file qgslayoutitem.h.

◆ frameChanged

void QgsLayoutItem::frameChanged ( )

signal

Emitted if the item's frame style changes.

◆ frameEnabled()

bool QgsLayoutItem::frameEnabled ( ) const

inline

Returns true if the item includes a frame.

See also: setFrameEnabled(); frameStrokeWidth(); frameJoinStyle(); frameStrokeColor()

Definition at line 732 of file qgslayoutitem.h.

◆ frameJoinStyle()

Qt::PenJoinStyle QgsLayoutItem::frameJoinStyle ( ) const

inline

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

See also: frameEnabled(); setFrameJoinStyle(); frameStrokeWidth(); frameStrokeColor()

Definition at line 786 of file qgslayoutitem.h.

◆ framePath()

QPainterPath QgsLayoutItem::framePath ( ) const

protectedvirtual

Returns the path to use when drawing the item's frame or background.

See also: drawFrame(); drawBackground()

Since: QGIS 3.16

Reimplemented in QgsLayoutItemMap.

Definition at line 1214 of file qgslayoutitem.cpp.

◆ frameStrokeColor()

QColor QgsLayoutItem::frameStrokeColor ( ) const

inline

Returns the frame's stroke color.

This is only used if frameEnabled() returns true.

See also: frameEnabled(); setFrameStrokeColor(); frameJoinStyle(); setFrameStrokeColor()

Definition at line 759 of file qgslayoutitem.h.

◆ frameStrokeWidth()

QgsLayoutMeasurement QgsLayoutItem::frameStrokeWidth ( ) const

inline

Returns the frame's stroke width.

This is only used if frameEnabled() returns true.

See also: frameEnabled(); setFrameStrokeWidth(); frameJoinStyle(); frameStrokeColor()

Definition at line 777 of file qgslayoutitem.h.

◆ hasBackground()

bool QgsLayoutItem::hasBackground ( ) const

inline

Returns true if the item has a background.

See also: setBackgroundEnabled(); backgroundColor()

Definition at line 802 of file qgslayoutitem.h.

◆ icon()

virtual QIcon QgsLayoutItem::icon ( ) const

inlinevirtual

Returns the item's icon.

Reimplemented in QgsLayoutItemShape, QgsLayoutItemScaleBar, QgsLayoutItemPolyline, QgsLayoutItemPolygon, QgsLayoutItemPicture, QgsLayoutItemMarker, QgsLayoutItemMap, QgsLayoutItemLegend, QgsLayoutItemLabel, QgsLayoutFrame, and QgsLayoutItem3DMap.

Definition at line 336 of file qgslayoutitem.h.

◆ id()

QString QgsLayoutItem::id ( ) const

inline

Returns the item's ID name.

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

See also: setId(); uuid()

Definition at line 359 of file qgslayoutitem.h.

◆ invalidateCache

void QgsLayoutItem::invalidateCache ( )

virtualslot

Forces a deferred update of any cached image the item uses.

Definition at line 1185 of file qgslayoutitem.cpp.

◆ isGroupMember()

bool QgsLayoutItem::isGroupMember ( ) const

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

See also: parentGroup(); setParentGroup()

Definition at line 225 of file qgslayoutitem.cpp.

◆ isLocked()

bool QgsLayoutItem::isLocked ( ) const

inline

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

See also: setLocked(); lockChanged()

Definition at line 402 of file qgslayoutitem.h.

◆ itemFlags()

QgsLayoutItem::Flags QgsLayoutItem::itemFlags ( ) const

virtual

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

Since: QGIS 3.4.3

Reimplemented in QgsLayoutItemShape, QgsLayoutItemPolygon, QgsLayoutItemMap, and QgsLayoutItemLegend.

Definition at line 129 of file qgslayoutitem.cpp.

◆ itemOpacity()

double QgsLayoutItem::itemOpacity ( ) const

inline

Returns the item's opacity.

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

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

See also: setItemOpacity()

Definition at line 845 of file qgslayoutitem.h.

◆ itemRotation()

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.

See also: setItemRotation()

Definition at line 606 of file qgslayoutitem.cpp.

◆ lockChanged

void QgsLayoutItem::lockChanged ( )

signal

Emitted if the item's lock status changes.

See also: isLocked(); setLocked()

◆ minimumSize()

virtual QgsLayoutSize QgsLayoutItem::minimumSize ( ) const

inlinevirtual

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

See also: setMinimumSize(); fixedSize()

Reimplemented in QgsLayoutItemScaleBar, and QgsLayoutFrame.

Definition at line 562 of file qgslayoutitem.h.

◆ moveContent()

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.

See also: setMoveContentPreviewOffset(); zoomContent()

Reimplemented in QgsLayoutItemMap.

Definition at line 953 of file qgslayoutitem.cpp.

◆ nextExportPart()

bool QgsLayoutItem::nextExportPart ( )

virtual

Moves to the next export part for a multi-layered export item, during a multi-layered export.

See also: startLayeredExport(); stopLayeredExport()

Since: QGIS 3.10

Reimplemented in QgsLayoutItemMap.

Definition at line 267 of file qgslayoutitem.cpp.

◆ numberExportLayers()

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.

See also: exportLayerBehavior(); exportLayerDetails()

Deprecated:: Use nextExportPart() and exportLayerBehavior() instead.

Reimplemented in QgsLayoutItemMap.

Definition at line 252 of file qgslayoutitem.cpp.

◆ page()

int QgsLayoutItem::page ( ) const

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

See also: pagePos()

Definition at line 542 of file qgslayoutitem.cpp.

◆ pagePos()

QPointF QgsLayoutItem::pagePos ( ) const

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

See also: page(); pagePositionWithUnits()

Definition at line 550 of file qgslayoutitem.cpp.

◆ pagePositionWithUnits()

QgsLayoutPoint QgsLayoutItem::pagePositionWithUnits ( ) const

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

See also: page(); pagePos()

Definition at line 566 of file qgslayoutitem.cpp.

◆ paint()

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.

Definition at line 285 of file qgslayoutitem.cpp.

◆ parentGroup()

QgsLayoutItemGroup * QgsLayoutItem::parentGroup ( ) const

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

See also: isGroupMember(); setParentGroup()

Definition at line 230 of file qgslayoutitem.cpp.

◆ positionAtReferencePoint()

QPointF QgsLayoutItem::positionAtReferencePoint ( const QgsLayoutItem::ReferencePoint reference ) const

protected

Returns the current position (in layout units) of a reference point for the item.

Definition at line 1313 of file qgslayoutitem.cpp.

◆ positionWithUnits()

QgsLayoutPoint QgsLayoutItem::positionWithUnits ( ) const

inline

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.

See also: attemptMove(); referencePoint(); sizeWithUnits()

Definition at line 646 of file qgslayoutitem.h.

◆ readPropertiesFromElement()

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

protectedvirtual

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

See also: writePropertiesToElement(); readXml()

Reimplemented in QgsLayoutItemPage, QgsLayoutItemGroup, QgsLayoutFrame, QgsLayoutItemShape, QgsLayoutItemScaleBar, QgsLayoutItemPolyline, QgsLayoutItemPicture, QgsLayoutNodesItem, QgsLayoutItemMarker, QgsLayoutItemMap, QgsLayoutItemLegend, QgsLayoutItemLabel, and QgsLayoutItem3DMap.

Definition at line 1331 of file qgslayoutitem.cpp.

◆ readXml()

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

See also: writeXml(); finalizeRestoreFromXml()

Definition at line 692 of file qgslayoutitem.cpp.

◆ rectWithFrame()

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.

See also: estimatedFrameBleed()

Definition at line 947 of file qgslayoutitem.cpp.

◆ redraw

void QgsLayoutItem::redraw ( )

virtualslot

Triggers a redraw (update) of the item.

Definition at line 1195 of file qgslayoutitem.cpp.

◆ referencePoint()

ReferencePoint QgsLayoutItem::referencePoint ( ) const

inline

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.

See also: setReferencePoint()

Definition at line 546 of file qgslayoutitem.h.

◆ refresh

void QgsLayoutItem::refresh ( )

overrideslot

Refreshes the item, causing a recalculation of any property overrides and recalculation of its position and size.

Definition at line 1177 of file qgslayoutitem.cpp.

◆ refreshBackgroundColor()

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.

Definition at line 1494 of file qgslayoutitem.cpp.

◆ refreshBlendMode()

void QgsLayoutItem::refreshBlendMode ( )

protected

Refresh item's blend mode, considering data defined blend mode.

Definition at line 1513 of file qgslayoutitem.cpp.

◆ refreshDataDefinedProperty

void QgsLayoutItem::refreshDataDefinedProperty ( QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties )

virtualslot

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.

Reimplemented in QgsLayoutItemScaleBar.

Definition at line 1082 of file qgslayoutitem.cpp.

◆ refreshFrame()

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.

Definition at line 1459 of file qgslayoutitem.cpp.

◆ refreshItemPosition()

void QgsLayoutItem::refreshItemPosition ( )

protected

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

See also: refreshItemSize()

Definition at line 1274 of file qgslayoutitem.cpp.

◆ refreshItemRotation()

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.

See also: refreshItemSize(); refreshItemPosition()

Definition at line 1399 of file qgslayoutitem.cpp.

◆ refreshItemSize()

void QgsLayoutItem::refreshItemSize ( )

protected

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

See also: setFixedSize(); setMinimumSize(); refreshItemPosition()

Definition at line 1269 of file qgslayoutitem.cpp.

◆ refreshOpacity()

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.

Definition at line 1438 of file qgslayoutitem.cpp.

◆ requiresRasterization()

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.

See also: containsAdvancedEffects()

Reimplemented in QgsLayoutItemMap.

Definition at line 931 of file qgslayoutitem.cpp.

◆ rotateItem

void QgsLayoutItem::rotateItem	(	double	angle,
		QPointF	transformOrigin
	)

virtualslot

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

See also: setItemRotation(); itemRotation()

Definition at line 1148 of file qgslayoutitem.cpp.

◆ rotationChanged

void QgsLayoutItem::rotationChanged ( double newRotation )

signal

Emitted on item rotation change.

◆ setBackgroundColor()

void QgsLayoutItem::setBackgroundColor ( const QColor & color )

Sets the background color for this item.

See also: backgroundColor(); setBackgroundEnabled()

Definition at line 893 of file qgslayoutitem.cpp.

◆ setBackgroundEnabled()

void QgsLayoutItem::setBackgroundEnabled ( bool drawBackground )

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

See also: hasBackground(); setBackgroundColor()

Definition at line 887 of file qgslayoutitem.cpp.

◆ setBlendMode()

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

Sets the item's composition blending mode.

See also: blendMode()

Definition at line 900 of file qgslayoutitem.cpp.

◆ setExcludeFromExports()

void QgsLayoutItem::setExcludeFromExports ( bool exclude )

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

See also: excludeFromExports()

Definition at line 920 of file qgslayoutitem.cpp.

◆ setFixedSize()

void QgsLayoutItem::setFixedSize ( const QgsLayoutSize & size )

protectedvirtual

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.

See also: fixedSize(); setMinimumSize()

Definition at line 1252 of file qgslayoutitem.cpp.

◆ setFrameEnabled()

void QgsLayoutItem::setFrameEnabled ( bool drawFrame )

virtual

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

See also: frameEnabled(); setFrameStrokeWidth(); setFrameJoinStyle(); setFrameStrokeColor()

Reimplemented in QgsLayoutItemLabel.

Definition at line 834 of file qgslayoutitem.cpp.

◆ setFrameJoinStyle()

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

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

See also: setFrameEnabled(); frameJoinStyle(); setFrameStrokeWidth(); setFrameStrokeColor()

Definition at line 872 of file qgslayoutitem.cpp.

◆ setFrameStrokeColor()

void QgsLayoutItem::setFrameStrokeColor ( const QColor & color )

Sets the frame stroke color.

See also: frameStrokeColor(); setFrameEnabled(); setFrameJoinStyle(); setFrameStrokeWidth()

Definition at line 847 of file qgslayoutitem.cpp.

◆ setFrameStrokeWidth()

void QgsLayoutItem::setFrameStrokeWidth ( QgsLayoutMeasurement width )

virtual

Sets the frame stroke width.

See also: frameStrokeWidth(); setFrameEnabled(); setFrameJoinStyle(); setFrameStrokeColor()

Reimplemented in QgsLayoutItemMap, and QgsLayoutItemLabel.

Definition at line 860 of file qgslayoutitem.cpp.

◆ setId()

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.

See also: id(); uuid()

Definition at line 134 of file qgslayoutitem.cpp.

◆ setItemOpacity()

void QgsLayoutItem::setItemOpacity ( double opacity )

Sets the item's opacity.

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

Parameters

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

See also: itemOpacity()

Definition at line 907 of file qgslayoutitem.cpp.

◆ setItemRotation

void QgsLayoutItem::setItemRotation	(	double	rotation,
		bool	adjustPosition = `true`
	)

virtualslot

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.

See also: itemRotation(); rotateItem()

Definition at line 1127 of file qgslayoutitem.cpp.

◆ setLocked()

void QgsLayoutItem::setLocked ( bool locked )

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

See also: isLocked(); lockChanged()

Definition at line 200 of file qgslayoutitem.cpp.

◆ setMinimumSize()

void QgsLayoutItem::setMinimumSize ( const QgsLayoutSize & size )

protectedvirtual

Sets the minimum allowed size for the layout item.

Set an empty size if item can be freely resized.

See also: minimumSize(); setFixedSize()

Definition at line 1258 of file qgslayoutitem.cpp.

◆ setMoveContentPreviewOffset()

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.

See also: moveContent()

Reimplemented in QgsLayoutItemMap.

Definition at line 958 of file qgslayoutitem.cpp.

◆ setParentGroup()

void QgsLayoutItem::setParentGroup ( QgsLayoutItemGroup * group )

Sets the item's parent group.

See also: isGroupMember(); parentGroup()

Definition at line 238 of file qgslayoutitem.cpp.

◆ setReferencePoint()

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

See also: referencePoint()

Definition at line 415 of file qgslayoutitem.cpp.

◆ setSelected()

void QgsLayoutItem::setSelected ( bool selected )

virtual

Sets whether the item should be selected.

Definition at line 160 of file qgslayoutitem.cpp.

◆ setVisibility()

void QgsLayoutItem::setVisibility ( bool visible )

virtual

Sets whether the item is visible.

Note: QGraphicsItem::setVisible should not be called directly on a QgsLayoutItem, as some item types (e.g., groups) need to override the visibility toggle.

Reimplemented in QgsLayoutItemGroup.

Definition at line 170 of file qgslayoutitem.cpp.

◆ shouldDrawItem()

bool QgsLayoutItem::shouldDrawItem ( ) const

Returns whether the item should be drawn in the current context.

Definition at line 591 of file qgslayoutitem.cpp.

◆ sizePositionChanged

void QgsLayoutItem::sizePositionChanged ( )

signal

Emitted when the item's size or position changes.

◆ sizeWithUnits()

QgsLayoutSize QgsLayoutItem::sizeWithUnits ( ) const

inline

Returns the item's current size, including units.

See also: attemptResize(); positionWithUnits()

Definition at line 673 of file qgslayoutitem.h.

◆ startLayeredExport()

void QgsLayoutItem::startLayeredExport ( )

virtual

Starts a multi-layer export operation.

See also: stopLayeredExport(); nextExportPart()

Since: QGIS 3.10

Reimplemented in QgsLayoutItemMap.

Definition at line 257 of file qgslayoutitem.cpp.

◆ stopLayeredExport()

void QgsLayoutItem::stopLayeredExport ( )

virtual

Stops a multi-layer export operation.

See also: startLayeredExport(); nextExportPart()

Since: QGIS 3.10

Reimplemented in QgsLayoutItemMap.

Definition at line 262 of file qgslayoutitem.cpp.

◆ topLeftToReferencePoint()

QgsLayoutPoint QgsLayoutItem::topLeftToReferencePoint ( const QgsLayoutPoint & point ) const

protected

Returns the position for the reference point of the item, if the top-left of the item was placed at the specified point.

Definition at line 1319 of file qgslayoutitem.cpp.

◆ type()

int QgsLayoutItem::type ( ) const

override

Returns a unique graphics item type identifier.

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

Definition at line 124 of file qgslayoutitem.cpp.

◆ uuid()

virtual QString QgsLayoutItem::uuid ( ) const

inlinevirtual

Returns the item identification string.

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

Note: There is no corresponding setter for the uuid - it's created automatically.

See also: id(); setId()

Definition at line 345 of file qgslayoutitem.h.

◆ writePropertiesToElement()

bool QgsLayoutItem::writePropertiesToElement	(	QDomElement &	element,
		QDomDocument &	document,
		const QgsReadWriteContext &	context
	)		const

protectedvirtual

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

See also: writeXml(); readPropertiesFromElement()

Reimplemented in QgsLayoutItemPage, QgsLayoutItemGroup, QgsLayoutFrame, QgsLayoutItemShape, QgsLayoutItemScaleBar, QgsLayoutItemPolyline, QgsLayoutItemPicture, QgsLayoutNodesItem, QgsLayoutItemMarker, QgsLayoutItemMap, QgsLayoutItemLegend, QgsLayoutItemLabel, and QgsLayoutItem3DMap.

Definition at line 1326 of file qgslayoutitem.cpp.

◆ writeXml()

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

See also: readXml()

Definition at line 611 of file qgslayoutitem.cpp.

◆ zoomContent()

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

virtual

Zooms content of item.

Does nothing by default.

Parameters

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

See also: moveContent()

Reimplemented in QgsLayoutItemMap.

Definition at line 963 of file qgslayoutitem.cpp.

Friends And Related Function Documentation

◆ QgsCompositionConverter

friend class QgsCompositionConverter

friend

Definition at line 1323 of file qgslayoutitem.h.

◆ QgsLayout

friend class QgsLayout

friend

Definition at line 1321 of file qgslayoutitem.h.

◆ QgsLayoutItemGroup

friend class QgsLayoutItemGroup

friend

Definition at line 1322 of file qgslayoutitem.h.

◆ TestQgsLayoutItem

friend class TestQgsLayoutItem

friend

Definition at line 1319 of file qgslayoutitem.h.

◆ TestQgsLayoutView

friend class TestQgsLayoutView

friend

Definition at line 1320 of file qgslayoutitem.h.

Property Documentation

◆ locked

bool QgsLayoutItem::locked

readwrite

Definition at line 103 of file qgslayoutitem.h.

The documentation for this class was generated from the following files:

/build/qgis-3.22.4+99unstable/src/core/layout/qgslayoutitem.h
/build/qgis-3.22.4+99unstable/src/core/layout/qgslayoutitem.cpp

Classes

Public Types

Public Slots

Signals

Public Member Functions

Protected Member Functions

Properties

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ ExportLayerBehavior

◆ Flag

◆ ReferencePoint

◆ UndoCommand

Constructor & Destructor Documentation

◆ QgsLayoutItem()

◆ ~QgsLayoutItem()

Member Function Documentation

◆ accept()

◆ adjustPointForReferencePosition()

◆ applyDataDefinedSize()

◆ applyItemSizeConstraint()

◆ attemptMove()

◆ attemptMoveBy()

◆ attemptResize()

◆ attemptSetSceneRect()

◆ backgroundColor()

◆ backgroundTaskCountChanged

◆ beginCommand()

◆ blendMode()

◆ cancelCommand()

◆ cleanup()

◆ clipPath()

◆ clipPathChanged

◆ containsAdvancedEffects()

◆ createCommand()

◆ createExpressionContext()

◆ displayName()

◆ draw()

◆ drawBackground()

◆ drawDebugRect()

◆ drawFrame()

◆ endCommand()

◆ estimatedFrameBleed()

◆ excludeFromExports()

◆ exportLayerBehavior()

◆ exportLayerDetails()

◆ finalizeRestoreFromXml()

◆ fixedSize()

◆ frameChanged

◆ frameEnabled()

◆ frameJoinStyle()

◆ framePath()

◆ frameStrokeColor()

◆ frameStrokeWidth()

◆ hasBackground()

◆ icon()

◆ id()

◆ invalidateCache

◆ isGroupMember()

◆ isLocked()

◆ itemFlags()

◆ itemOpacity()

◆ itemRotation()

◆ lockChanged

◆ minimumSize()

◆ moveContent()

◆ nextExportPart()

◆ numberExportLayers()

◆ page()

◆ pagePos()

◆ pagePositionWithUnits()

◆ paint()

◆ parentGroup()

◆ positionAtReferencePoint()

◆ positionWithUnits()

◆ readPropertiesFromElement()

◆ readXml()

◆ rectWithFrame()