QgsLayoutItem Class Reference

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

#include <qgslayoutitem.h>

Inheritance diagram for QgsLayoutItem:

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 , FlagDisableSceneCaching = 1 << 3 }
	Flags for controlling how an item behaves. More...
typedef QFlags< Flag >	Flags
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 , UndoMarginLeft ,   UndoMarginTop , UndoMarginBottom , UndoMarginRight , UndoSetId ,   UndoRotation , UndoExportLayerName , 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 , UndoElevationProfileTolerance ,   UndoElevationProfileChartBackground , UndoElevationProfileChartBorder , UndoElevationProfileDistanceMajorGridlines , UndoElevationProfileDistanceMinorGridlines ,   UndoElevationProfileDistanceFormat , UndoElevationProfileDistanceFont , UndoElevationProfileDistanceLabels , UndoElevationProfileElevationMajorGridlines ,   UndoElevationProfileElevationMinorGridlines , UndoElevationProfileElevationFormat , UndoElevationProfileElevationFont , UndoElevationProfileElevationLabels ,   UndoElevationProfileMinimumDistance , UndoElevationProfileMaximumDistance , UndoElevationProfileMinimumElevation , UndoElevationProfileMaximumElevation ,   UndoCustomCommand }
	Layout item undo commands, used for collapsing undo commands. More...
Public Types inherited from QgsLayoutObject
enum class	DataDefinedProperty : int {   NoProperty = 0 , AllProperties , TestProperty , PresetPaperSize ,   PaperWidth , PaperHeight , NumPages , PaperOrientation ,   PageNumber , PositionX , PositionY , ItemWidth ,   ItemHeight , ItemRotation , Transparency , Opacity ,   BlendMode , ExcludeFromExports , FrameColor , BackgroundColor ,   MarginLeft , MarginTop , MarginRight , MarginBottom ,   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 ,   MapCrs , StartDateTime , EndDateTime , MapZRangeLower ,   MapZRangeUpper , PictureSource , PictureSvgBackgroundColor , PictureSvgStrokeColor ,   PictureSvgStrokeWidth , SourceUrl , LegendTitle , LegendColumnCount ,   ScalebarLeftSegments , ScalebarRightSegments , ScalebarSegmentWidth , ScalebarMinimumWidth ,   ScalebarMaximumWidth , ScalebarHeight , ScalebarRightSegmentSubdivisions , ScalebarSubdivisionHeight ,   ScalebarFillColor , ScalebarFillColor2 , ScalebarLineColor , ScalebarLineWidth ,   AttributeTableSourceLayer , ElevationProfileTolerance , ElevationProfileDistanceMajorInterval , ElevationProfileDistanceMinorInterval ,   ElevationProfileDistanceLabelInterval , ElevationProfileElevationMajorInterval , ElevationProfileElevationMinorInterval , ElevationProfileElevationLabelInterval ,   ElevationProfileMinimumDistance , ElevationProfileMaximumDistance , ElevationProfileMinimumElevation , ElevationProfileMaximumElevation }
	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.
virtual void	redraw ()
	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.
virtual void	refreshDataDefinedProperty (QgsLayoutObject::DataDefinedProperty property=QgsLayoutObject::DataDefinedProperty::AllProperties)
	Refreshes a data defined property for the item by reevaluating the property's value and redrawing the item with this new value.
virtual void	rotateItem (double angle, QPointF transformOrigin)
	Rotates the item by a specified angle in degrees clockwise around a specified reference point.
virtual void	setItemRotation (double rotation, bool adjustPosition=true)
	Sets the layout item's rotation, in degrees clockwise.
Public Slots inherited from QgsLayoutObject
virtual void	refresh ()
	Refreshes the object, causing a recalculation of any property overrides.

Signals
void	backgroundTaskCountChanged (int count)
	Emitted whenever the number of background tasks an item is executing changes.
void	clipPathChanged ()
	Emitted when the item's clipping path has changed.
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.
Signals inherited from QgsLayoutObject
void	changed ()
	Emitted when the object's properties change.

Public Member Functions
	QgsLayoutItem (QgsLayout *layout, bool manageZValue=true)
	Constructor for QgsLayoutItem, with the specified parent layout.
	~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.
virtual void	attemptMove (const QgsLayoutPoint &point, bool useReferencePoint=true, bool includesFrame=false, int page=-1)
	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.
virtual void	attemptResize (const QgsLayoutSize &size, bool includesFrame=false)
	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.
QColor	backgroundColor (bool useDataDefined=true) const
	Returns the background color for this item.
void	beginCommand (const QString &commandText, UndoCommand command=UndoNone)
	Starts new undo command for this item.
QPainter::CompositionMode	blendMode () const
	Returns the item's composition blending mode.
void	cancelCommand ()
	Cancels the current item command and discards it.
virtual void	cleanup ()
	Called just before a batch of items are deleted, allowing them to run cleanup tasks.
virtual QgsGeometry	clipPath () const
	Returns the clipping path generated by this item, in layout coordinates.
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.
QgsAbstractLayoutUndoCommand *	createCommand (const QString &text, int id, QUndoCommand *parent=nullptr) override
	Creates a new layout undo command with the specified text and parent.
QgsExpressionContext	createExpressionContext () const override
	This method needs to be reimplemented in all classes which implement this interface and return an expression context.
virtual QString	displayName () const
	Gets item display name.
void	endCommand ()
	Completes the current item command and push it onto the layout's undo stack.
virtual double	estimatedFrameBleed () const
	Returns the estimated amount the item's frame bleeds outside the item's actual rectangle.
bool	excludeFromExports () const
	Returns whether the item should be excluded from layout exports and prints.
virtual ExportLayerBehavior	exportLayerBehavior () const
	Returns the behavior of this item during exporting to layered exports (e.g.
virtual QgsLayoutItem::ExportLayerDetail	exportLayerDetails () const
	Returns the details for the specified current export layer.
virtual void	finalizeRestoreFromXml ()
	Called after all pending items have been restored from XML.
virtual QgsLayoutSize	fixedSize () const
	Returns the fixed size of the item, if applicable, or an empty size if item can be freely resized.
bool	frameEnabled () const
	Returns true if the item includes a frame.
Qt::PenJoinStyle	frameJoinStyle () const
	Returns the join style used for drawing the item's frame.
QColor	frameStrokeColor () const
	Returns the frame's stroke color.
QgsLayoutMeasurement	frameStrokeWidth () const
	Returns the frame's stroke width.
bool	hasBackground () const
	Returns true if the item has a background.
virtual QIcon	icon () const
	Returns the item's icon.
QString	id () const
	Returns the item's ID name.
bool	isGroupMember () const
	Returns true if the item is part of a QgsLayoutItemGroup group.
bool	isLocked () const
	Returns true if the item is locked, and cannot be interacted with using the mouse.
virtual bool	isRefreshing () const
	Returns true if the item is currently refreshing content in the background.
virtual Flags	itemFlags () const
	Returns the item's flags, which indicate how the item behaves.
double	itemOpacity () const
	Returns the item's opacity.
double	itemRotation () const
	Returns the current rotation for the item, in degrees clockwise.
virtual QgsLayoutSize	minimumSize () const
	Returns the minimum allowed size of the item, if applicable, or an empty size if item can be freely resized.
virtual void	moveContent (double dx, double dy)
	Moves the content of the item, by a specified dx and dy in layout units.
virtual bool	nextExportPart ()
	Moves to the next export part for a multi-layered export item, during a multi-layered export.
virtual Q_DECL_DEPRECATED int	numberExportLayers () const
	Returns the number of layers that this item requires for exporting during layered exports (e.g.
int	page () const
	Returns the page the item is currently on, with the first page returning 0.
QPointF	pagePos () const
	Returns the item's position (in layout units) relative to the top left corner of its current page.
QgsLayoutPoint	pagePositionWithUnits () const
	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.
QgsLayoutItemGroup *	parentGroup () const
	Returns the item's parent group, if the item is part of a QgsLayoutItemGroup group.
QgsLayoutPoint	positionWithUnits () const
	Returns the item's current position, including units.
bool	readXml (const QDomElement &itemElement, const QDomDocument &document, const QgsReadWriteContext &context)
	Sets the item state from a DOM element.
virtual QRectF	rectWithFrame () const
	Returns the item's rectangular bounds, including any bleed caused by the item's frame.
ReferencePoint	referencePoint () const
	Returns the reference point for positioning of the layout item.
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.
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.
virtual void	setFrameEnabled (bool drawFrame)
	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.
virtual void	setFrameStrokeWidth (QgsLayoutMeasurement width)
	Sets the frame stroke width.
virtual void	setId (const QString &id)
	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.
virtual void	setMoveContentPreviewOffset (double dx, double dy)
	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.
virtual void	setSelected (bool selected)
	Sets whether the item should be selected.
virtual void	setVisibility (bool visible)
	Sets whether the item is visible.
bool	shouldDrawItem () const
	Returns whether the item should be drawn in the current context.
QgsLayoutSize	sizeWithUnits () const
	Returns the item's current size, including units.
virtual void	startLayeredExport ()
	Starts a multi-layer export operation.
virtual void	stopLayeredExport ()
	Stops a multi-layer export operation.
int	type () const override
	Returns a unique graphics item type identifier.
virtual QString	uuid () const
	Returns the item identification string.
bool	writeXml (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context) const
	Stores the item state in a DOM element.
virtual void	zoomContent (double factor, QPointF point)
	Zooms content of item.
Public Member Functions inherited from QgsLayoutObject
	QgsLayoutObject (QgsLayout *layout)
	Constructor for QgsLayoutObject, with the specified parent layout.
QgsExpressionContext	createExpressionContext () const override
	Creates an expression context relating to the objects' current state.
QStringList	customProperties () const
	Returns list of keys stored in custom properties for the object.
QVariant	customProperty (const QString &key, const QVariant &defaultValue=QVariant()) const
	Read a custom property from the object.
QgsPropertyCollection &	dataDefinedProperties ()
	Returns a reference to the object's property collection, used for data defined overrides.
const QgsPropertyCollection &	dataDefinedProperties () const
	Returns a reference to the object's property collection, used for data defined overrides.
QgsLayout *	layout ()
	Returns the layout the object is attached to.
const QgsLayout *	layout () const
	Returns the layout the object is attached to.
void	removeCustomProperty (const QString &key)
	Remove a custom property from the object.
void	setCustomProperty (const QString &key, const QVariant &value)
	Set a custom property for the object.
void	setDataDefinedProperties (const QgsPropertyCollection &collection)
	Sets the objects's property collection, used for data defined overrides.
Public Member Functions inherited from QgsExpressionContextGenerator
virtual	~QgsExpressionContextGenerator ()=default
Public Member Functions inherited from QgsLayoutUndoObjectInterface
virtual	~QgsLayoutUndoObjectInterface ()=default

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.
QgsLayoutSize	applyDataDefinedSize (const QgsLayoutSize &size)
	Applies any present data defined size overrides to the specified layout size.
virtual QSizeF	applyItemSizeConstraint (QSizeF targetSize)
	Applies any item-specific size constraint handling to a given targetSize in layout units.
virtual void	draw (QgsLayoutItemRenderContext &context)=0
	Draws the item's contents using the specified item render context.
virtual void	drawBackground (QgsRenderContext &context)
	Draws the background for the item.
virtual void	drawDebugRect (QPainter *painter)
	Draws a debugging rectangle of the item's current bounds within the specified painter.
virtual void	drawFrame (QgsRenderContext &context)
	Draws the frame around the item.
void	drawRefreshingOverlay (QPainter *painter, const QStyleOptionGraphicsItem *itemStyle)
	Draws a "refreshing" overlay icon on the item.
virtual QPainterPath	framePath () const
	Returns the path to use when drawing the item's frame or background.
QPointF	positionAtReferencePoint (ReferencePoint reference) const
	Returns the current position (in layout units) of a reference point for the item.
virtual bool	readPropertiesFromElement (const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context)
	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.
virtual void	setFixedSize (const QgsLayoutSize &size)
	Sets a fixed size for the layout item, which prevents it from being freely resized.
virtual void	setMinimumSize (const QgsLayoutSize &size)
	Sets the minimum allowed size for the layout item.
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.
virtual bool	writePropertiesToElement (QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context) const
	Stores item state within an XML DOM element.
Protected Member Functions inherited from QgsLayoutObject
bool	readObjectPropertiesFromElement (const QDomElement &parentElement, const QDomDocument &document, const QgsReadWriteContext &context)
	Sets object properties from a DOM element.
bool	writeObjectPropertiesToElement (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context) const
	Stores object properties within an XML DOM element.

Properties
bool	locked

Friends
class	QgsCompositionConverter
class	QgsLayout
class	QgsLayoutItemElevationProfile
class	QgsLayoutItemGroup
class	QgsLayoutItemLegend
class	QgsLayoutItemMap
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.
static const QgsPropertiesDefinition &	propertyDefinitions ()
	Returns the layout object property definitions.
Protected Attributes inherited from QgsLayoutObject
QgsObjectCustomProperties	mCustomProperties
	Custom properties for object.
QgsPropertyCollection	mDataDefinedProperties
QPointer< QgsLayout >	mLayout

Detailed Description

Base class for graphical items within a QgsLayout.

Definition at line 106 of file qgslayoutitem.h.

Member Typedef Documentation

Flags

typedef QFlags< Flag > QgsLayoutItem::Flags

Definition at line 335 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 456 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())
FlagDisableSceneCaching	Item should not have QGraphicsItem caching enabled.

Definition at line 329 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 205 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.
UndoMarginLeft	Left margin. Since QGIS 3.30
UndoMarginTop	Top margin. Since QGIS 3.30
UndoMarginBottom	Bottom margin. Since QGIS 3.30
UndoMarginRight	Right margin. Since QGIS 3.30
UndoSetId	Change item ID.
UndoRotation	Rotation adjustment.
UndoExportLayerName	Export layer name. Since QGIS 3.40
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.
UndoElevationProfileTolerance	Change elevation profile distance tolerance.
UndoElevationProfileChartBackground	Change elevation profile chart background.
UndoElevationProfileChartBorder	Change elevation profile chart border.
UndoElevationProfileDistanceMajorGridlines	Change elevation profile distance axis major gridlines.
UndoElevationProfileDistanceMinorGridlines	Change elevation profile distance axis minor gridlines.
UndoElevationProfileDistanceFormat	Change elevation profile distance axis number format.
UndoElevationProfileDistanceFont	Change elevation profile distance axis number font.
UndoElevationProfileDistanceLabels	Change elevation profile distance axis label interval.
UndoElevationProfileElevationMajorGridlines	Change elevation profile elevation axis major gridlines.
UndoElevationProfileElevationMinorGridlines	Change elevation profile elevation axis minor gridlines.
UndoElevationProfileElevationFormat	Change elevation profile elevation axis number format.
UndoElevationProfileElevationFont	Change elevation profile elevation axis number font.
UndoElevationProfileElevationLabels	Change elevation profile elevation axis label interval.
UndoElevationProfileMinimumDistance	Change elevation profile minimum distance.
UndoElevationProfileMaximumDistance	Change elevation profile maximum distance.
UndoElevationProfileMinimumElevation	Change elevation profile minimum elevation.
UndoElevationProfileMaximumElevation	Change elevation profile maximum elevation.
UndoCustomCommand	Base id for plugin based item undo commands.

Definition at line 219 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 49 of file qgslayoutitem.cpp.

~QgsLayoutItem()

QgsLayoutItem::~QgsLayoutItem ( )

override

Definition at line 84 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 QgsLayoutItemLegend, QgsLayoutItemMap, QgsLayoutItemMarker, QgsLayoutItemPage, QgsLayoutItemPolygon, QgsLayoutItemPolyline, QgsLayoutItemScaleBar, and QgsLayoutItemShape.

Definition at line 1202 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 1354 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 1045 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 1312 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 479 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 539 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 QgsLayoutItemGroup, and QgsLayoutItemPage.

Definition at line 441 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 523 of file qgslayoutitem.cpp.

backgroundColor()

QColor QgsLayoutItem::backgroundColor

(

bool

useDataDefined = true

)

const

Returns the background color for this item.

This is only used if hasBackground() returns true.

Parameters

useDataDefined

If true, then returns the data defined override for the background color

See also

setBackgroundColor()

hasBackground()

Definition at line 1540 of file qgslayoutitem.cpp.

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 981 of file qgslayoutitem.cpp.

blendMode()

QPainter::CompositionMode QgsLayoutItem::blendMode ( ) const

inline

Returns the item's composition blending mode.

See also

setBlendMode()

Definition at line 867 of file qgslayoutitem.h.

cancelCommand()

void QgsLayoutItem::cancelCommand

(

)

Cancels the current item command and discards it.

See also

beginCommand()

endCommand()

Definition at line 995 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 QgsLayoutFrame, and QgsLayoutItemGroup.

Definition at line 89 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 QgsLayoutItemPolygon, and QgsLayoutItemShape.

Definition at line 1208 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 QgsLayoutItemElevationProfile, QgsLayoutItemLegend, and QgsLayoutItemMap.

Definition at line 939 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 841 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.

Implements QgsExpressionContextGenerator.

Reimplemented in QgsLayoutItemLegend, and QgsLayoutItemMap.

Definition at line 1195 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 QgsLayoutItem3DMap, QgsLayoutFrame, QgsLayoutItemGroup, QgsLayoutItemLabel, QgsLayoutItemLegend, QgsLayoutItemMap, QgsLayoutItemPage, QgsLayoutItemPolygon, QgsLayoutItemPolyline, and QgsLayoutItemShape.

Definition at line 97 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 QgsLayoutItem3DMap, QgsLayoutFrame, QgsLayoutItemElevationProfile, QgsLayoutItemGroup, QgsLayoutItemLabel, QgsLayoutItemLegend, QgsLayoutItemMap, QgsLayoutItemMarker, QgsLayoutNodesItem, QgsLayoutItemPage, QgsLayoutItemPicture, QgsLayoutItemScaleBar, and QgsLayoutItemShape.

drawBackground()

void QgsLayoutItem::drawBackground ( QgsRenderContext &  context )

protectedvirtual

Draws the background for the item.

See also

framePath()

Reimplemented in QgsLayoutFrame, and QgsLayoutItemPage.

Definition at line 1273 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 1236 of file qgslayoutitem.cpp.

drawFrame()

void QgsLayoutItem::drawFrame ( QgsRenderContext &  context )

protectedvirtual

Draws the frame around the item.

See also

framePath()

Reimplemented in QgsLayoutFrame, and QgsLayoutItemPage.

Definition at line 1257 of file qgslayoutitem.cpp.

drawRefreshingOverlay()

void QgsLayoutItem::drawRefreshingOverlay ( QPainter *  painter, const QStyleOptionGraphicsItem *  itemStyle  )

protected

Draws a "refreshing" overlay icon on the item.

Since

QGIS 3.32

Definition at line 1288 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 989 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 QgsLayoutItemMap, QgsLayoutNodesItem, and QgsLayoutItemShape.

Definition at line 950 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 928 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 or geospatial PDF).

See also

numberExportLayers()

exportLayerDetails()

Since

QGIS 3.10

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

Definition at line 242 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 275 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 QgsLayoutItem3DMap, QgsLayoutItemGroup, QgsLayoutItemLegend, QgsLayoutItemMap, QgsLayoutItemMarker, QgsLayoutItemPicture, and QgsLayoutItemScaleBar.

Definition at line 837 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 QgsLayoutFrame, and QgsLayoutItemMarker.

Definition at line 590 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 768 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 822 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 1250 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 795 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 813 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 838 of file qgslayoutitem.h.

icon()

QIcon QgsLayoutItem::icon ( ) const

virtual

Returns the item's icon.

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

Definition at line 119 of file qgslayoutitem.cpp.

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 386 of file qgslayoutitem.h.

invalidateCache

void QgsLayoutItem::invalidateCache ( )

virtualslot

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

Definition at line 1221 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 220 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 429 of file qgslayoutitem.h.

isRefreshing()

bool QgsLayoutItem::isRefreshing ( ) const

virtual

Returns true if the item is currently refreshing content in the background.

Since

QGIS 3.32

Reimplemented in QgsLayoutItemLegend.

Definition at line 1190 of file qgslayoutitem.cpp.

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 QgsLayoutItemElevationProfile, QgsLayoutItemLegend, QgsLayoutItemMap, QgsLayoutNodesItem, QgsLayoutItemPolygon, and QgsLayoutItemShape.

Definition at line 124 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 882 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 618 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 QgsLayoutFrame, and QgsLayoutItemScaleBar.

Definition at line 598 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 966 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 262 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:

QGIS 3.40. Use nextExportPart() and exportLayerBehavior() instead.

Reimplemented in QgsLayoutItemMap.

Definition at line 247 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 554 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 562 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 578 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 280 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 225 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 1361 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 682 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 QgsLayoutItem3DMap, QgsLayoutItemElevationProfile, QgsLayoutItemLabel, QgsLayoutItemLegend, QgsLayoutItemMap, QgsLayoutItemMarker, QgsLayoutNodesItem, QgsLayoutItemPicture, QgsLayoutItemPolyline, QgsLayoutItemScaleBar, QgsLayoutItemShape, QgsLayoutFrame, QgsLayoutItemGroup, and QgsLayoutItemPage.

Definition at line 1379 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 704 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()

Reimplemented in QgsLayoutItemGroup.

Definition at line 960 of file qgslayoutitem.cpp.

redraw

void QgsLayoutItem::redraw ( )

virtualslot

Triggers a redraw (update) of the item.

Definition at line 1231 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 582 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 1213 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 1546 of file qgslayoutitem.cpp.

refreshBlendMode()

void QgsLayoutItem::refreshBlendMode ( )

protected

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

Definition at line 1565 of file qgslayoutitem.cpp.

refreshDataDefinedProperty

void QgsLayoutItem::refreshDataDefinedProperty ( QgsLayoutObject::DataDefinedProperty  property = QgsLayoutObject::DataDefinedProperty::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 QgsLayoutItemElevationProfile, and QgsLayoutItemScaleBar.

Definition at line 1113 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 1505 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 1322 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 1445 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 1317 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 1484 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 QgsLayoutItemElevationProfile, QgsLayoutItemLegend, and QgsLayoutItemMap.

Definition at line 944 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 1179 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 905 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 899 of file qgslayoutitem.cpp.

setBlendMode()

void QgsLayoutItem::setBlendMode

(

QPainter::CompositionMode

mode

)

Sets the item's composition blending mode.

See also

blendMode()

Definition at line 912 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 933 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 1300 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 846 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 884 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 859 of file qgslayoutitem.cpp.

setFrameStrokeWidth()

void QgsLayoutItem::setFrameStrokeWidth ( QgsLayoutMeasurement  width )

virtual

Sets the frame stroke width.

See also

frameStrokeWidth()

setFrameEnabled()

setFrameJoinStyle()

setFrameStrokeColor()

Reimplemented in QgsLayoutItemLabel, and QgsLayoutItemMap.

Definition at line 872 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 129 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 920 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 1158 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 195 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 1306 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 971 of file qgslayoutitem.cpp.

setParentGroup()

void QgsLayoutItem::setParentGroup

(

QgsLayoutItemGroup *

group

)

Sets the item's parent group.

See also

isGroupMember()

parentGroup()

Definition at line 233 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 427 of file qgslayoutitem.cpp.

setSelected()

void QgsLayoutItem::setSelected ( bool  selected )

virtual

Sets whether the item should be selected.

Definition at line 155 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 165 of file qgslayoutitem.cpp.

shouldDrawItem()

bool QgsLayoutItem::shouldDrawItem

(

)

const

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

Definition at line 603 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 709 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 252 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 257 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 1367 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 114 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 372 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 QgsLayoutItem3DMap, QgsLayoutItemElevationProfile, QgsLayoutItemLabel, QgsLayoutItemLegend, QgsLayoutItemMap, QgsLayoutItemMarker, QgsLayoutNodesItem, QgsLayoutItemPicture, QgsLayoutItemPolyline, QgsLayoutItemScaleBar, QgsLayoutItemShape, QgsLayoutFrame, QgsLayoutItemGroup, and QgsLayoutItemPage.

Definition at line 1374 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 623 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 976 of file qgslayoutitem.cpp.

Friends And Related Symbol Documentation

QgsCompositionConverter

friend class QgsCompositionConverter

friend

Definition at line 1380 of file qgslayoutitem.h.

QgsLayout

friend class QgsLayout

friend

Definition at line 1375 of file qgslayoutitem.h.

QgsLayoutItemElevationProfile

friend class QgsLayoutItemElevationProfile

friend

Definition at line 1379 of file qgslayoutitem.h.

QgsLayoutItemGroup

friend class QgsLayoutItemGroup

friend

Definition at line 1376 of file qgslayoutitem.h.

QgsLayoutItemLegend

friend class QgsLayoutItemLegend

friend

Definition at line 1378 of file qgslayoutitem.h.

QgsLayoutItemMap

friend class QgsLayoutItemMap

friend

Definition at line 1377 of file qgslayoutitem.h.

TestQgsLayoutItem

friend class TestQgsLayoutItem

friend

Definition at line 1373 of file qgslayoutitem.h.

TestQgsLayoutView

friend class TestQgsLayoutView

friend

Definition at line 1374 of file qgslayoutitem.h.

Property Documentation

locked

bool QgsLayoutItem::locked

readwrite

Definition at line 200 of file qgslayoutitem.h.

---

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

• /build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/layout/qgslayoutitem.h
• /build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/layout/qgslayoutitem.cpp