QgsLayoutObject Class Reference

A base class for objects which belong to a layout. More...

#include <qgslayoutobject.h>

Inheritance diagram for QgsLayoutObject:

Public Types
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 ,   LegendAutoWrapWidth , 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	refresh ()
	Refreshes the object, causing a recalculation of any property overrides.

Signals
void	changed ()
	Emitted when the object's properties change.

Public Member Functions
	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

Static Public Member Functions
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 Member Functions
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.

Protected Attributes
QgsObjectCustomProperties	mCustomProperties
	Custom properties for object.
QgsPropertyCollection	mDataDefinedProperties
QPointer< QgsLayout >	mLayout

Friends
class	QgsCompositionConverter
class	TestQgsLayoutObject

Detailed Description

A base class for objects which belong to a layout.

Definition at line 38 of file qgslayoutobject.h.

Member Enumeration Documentation

DataDefinedProperty

enum class QgsLayoutObject::DataDefinedProperty : int

strong

Data defined properties for different item types.

Enumerator
NoProperty	No property.
AllProperties	All properties for item.
TestProperty	Dummy property with no effect on item.
PresetPaperSize	Preset paper size for composition.
PaperWidth	Paper width (deprecated)
PaperHeight	Paper height (deprecated)
NumPages	Number of pages in composition (deprecated)
PaperOrientation	Paper orientation.
PageNumber	Page number for item placement.
PositionX	X position on page.
PositionY	Y position on page.
ItemWidth	Width of item.
ItemHeight	Height of item.
ItemRotation	Rotation of item.
Transparency	Item transparency (deprecated)
Opacity	Item opacity.
BlendMode	Item blend mode.
ExcludeFromExports	Exclude item from exports.
FrameColor	Item frame color.
BackgroundColor	Item background color.
MarginLeft	Left margin. Since QGIS 3.30
MarginTop	Top margin. Since QGIS 3.30
MarginRight	Right margin. Since QGIS 3.30
MarginBottom	Bottom margin. Since QGIS 3.30
MapRotation	Map rotation.
MapScale	Map scale.
MapXMin	Map extent x minimum.
MapYMin	Map extent y minimum.
MapXMax	Map extent x maximum.
MapYMax	Map extent y maximum.
MapAtlasMargin	Map atlas margin.
MapLayers	Map layer set.
MapStylePreset	Layer and style map theme.
MapLabelMargin	Map label margin.
MapGridEnabled	Map grid enabled.
MapGridIntervalX	Map grid interval X.
MapGridIntervalY	Map grid interval Y.
MapGridOffsetX	Map grid offset X.
MapGridOffsetY	Map grid offset Y.
MapGridFrameSize	Map grid frame size.
MapGridFrameMargin	Map grid frame margin.
MapGridLabelDistance	Map grid label distance.
MapGridCrossSize	Map grid cross size.
MapGridFrameLineThickness	Map grid frame line thickness.
MapGridAnnotationDisplayLeft	Map annotation display left.
MapGridAnnotationDisplayRight	Map annotation display right.
MapGridAnnotationDisplayTop	Map annotation display top.
MapGridAnnotationDisplayBottom	Map annotation display bottom.
MapGridFrameDivisionsLeft	Map frame division display left.
MapGridFrameDivisionsRight	Map frame division display right.
MapGridFrameDivisionsTop	Map frame division display top.
MapGridFrameDivisionsBottom	Map frame division display bottom.
MapCrs	Map CRS.
StartDateTime	Temporal range's start DateTime.
EndDateTime	Temporal range's end DateTime.
MapZRangeLower	Map frame Z-range lower value. Since QGIS 3.38
MapZRangeUpper	Map frame Z-range lower value. Since QGIS 3.38
PictureSource	Picture source url.
PictureSvgBackgroundColor	SVG background color.
PictureSvgStrokeColor	SVG stroke color.
PictureSvgStrokeWidth	SVG stroke width.
SourceUrl	Html source url.
LegendTitle	Legend title.
LegendColumnCount	Legend column count.
LegendAutoWrapWidth	Legend text automatic wrapping width. Since QGIS 3.44
ScalebarLeftSegments	Number of segments on the left of 0. Since QGIS 3.26
ScalebarRightSegments	Number of segments on the right of 0. Since QGIS 3.26
ScalebarSegmentWidth	Scalebar width in map units of a single segment. Since QGIS 3.26
ScalebarMinimumWidth	Scalebar segment minimum width. Since QGIS 3.26
ScalebarMaximumWidth	Scalebar segment maximum width. Since QGIS 3.26
ScalebarHeight	Scalebar height. Since QGIS 3.26
ScalebarRightSegmentSubdivisions	Number of subdivisions per segment on right of 0. Since QGIS 3.26
ScalebarSubdivisionHeight	Scalebar subdivision height. Since QGIS 3.26
ScalebarFillColor	Scalebar fill color (deprecated, use data defined properties on scalebar fill symbol 1 instead)
ScalebarFillColor2	Scalebar secondary fill color (deprecated, use data defined properties on scalebar fill symbol 2 instead)
ScalebarLineColor	Scalebar line color (deprecated, use data defined properties on scalebar line symbol instead)
ScalebarLineWidth	Scalebar line width (deprecated, use data defined properties on scalebar line symbol instead)
AttributeTableSourceLayer	Attribute table source layer.
ElevationProfileTolerance	Tolerance distance for elevation profiles. Since QGIS 3.30
ElevationProfileDistanceMajorInterval	Major grid line interval for elevation profile distance axis. Since QGIS 3.30
ElevationProfileDistanceMinorInterval	Minor grid line interval for elevation profile distance axis. Since QGIS 3.30
ElevationProfileDistanceLabelInterval	Label interval for elevation profile distance axis. Since QGIS 3.30
ElevationProfileElevationMajorInterval	Major grid line interval for elevation profile elevation axis. Since QGIS 3.30
ElevationProfileElevationMinorInterval	Minor grid line interval for elevation profile elevation axis. Since QGIS 3.30
ElevationProfileElevationLabelInterval	Label interval for elevation profile elevation axis. Since QGIS 3.30
ElevationProfileMinimumDistance	Minimum distance value for elevation profile. Since QGIS 3.30
ElevationProfileMaximumDistance	Maximum distance value for elevation profile. Since QGIS 3.30
ElevationProfileMinimumElevation	Minimum elevation value for elevation profile. Since QGIS 3.30
ElevationProfileMaximumElevation	Maximum elevation value for elevation profile. Since QGIS 3.30

Definition at line 141 of file qgslayoutobject.h.

PropertyValueType

enum QgsLayoutObject::PropertyValueType

Specifies whether the value returned by a function should be the original, user set value, or the current evaluated value for the property.

This may differ if a property has a data defined expression active.

Enumerator
EvaluatedValue	Return the current evaluated value for the property.
OriginalValue	Return the original, user set value.

Definition at line 249 of file qgslayoutobject.h.

Constructor & Destructor Documentation

QgsLayoutObject()

QgsLayoutObject::QgsLayoutObject ( QgsLayout *  layout )

explicit

Constructor for QgsLayoutObject, with the specified parent layout.

Note

While ownership of a QgsLayoutObject is not passed to the layout, classes which are derived from QgsLayoutObject (such as QgsLayoutItem) may transfer their ownership to a layout upon construction.

Definition at line 237 of file qgslayoutobject.cpp.

Member Function Documentation

changed

void QgsLayoutObject::changed ( )

signal

Emitted when the object's properties change.

createExpressionContext()

QgsExpressionContext QgsLayoutObject::createExpressionContext ( ) const

overridevirtual

Creates an expression context relating to the objects' current state.

The context includes scopes for global, project and layout properties.

Implements QgsExpressionContextGenerator.

Definition at line 280 of file qgslayoutobject.cpp.

customProperties()

QStringList QgsLayoutObject::customProperties

(

)

const

Returns list of keys stored in custom properties for the object.

See also

setCustomProperty()

customProperty()

removeCustomProperty()

Definition at line 275 of file qgslayoutobject.cpp.

customProperty()

QVariant QgsLayoutObject::customProperty	(	const QString &	key,
		const QVariant &	defaultValue = QVariant()
	)		const

Read a custom property from the object.

Parameters

key	property key
defaultValue	default value to return if property with matching key does not exist

Returns

value of matching property

See also

setCustomProperty()

removeCustomProperty()

customProperties()

Definition at line 265 of file qgslayoutobject.cpp.

dataDefinedProperties() [1/2]

QgsPropertyCollection & QgsLayoutObject::dataDefinedProperties ( )

inline

Returns a reference to the object's property collection, used for data defined overrides.

See also

setDataDefinedProperties()

Definition at line 294 of file qgslayoutobject.h.

dataDefinedProperties() [2/2]

const QgsPropertyCollection & QgsLayoutObject::dataDefinedProperties ( ) const

inline

Returns a reference to the object's property collection, used for data defined overrides.

See also

setDataDefinedProperties()

DataDefinedProperty

Definition at line 301 of file qgslayoutobject.h.

layout() [1/2]

QgsLayout * QgsLayoutObject::layout

(

)

Returns the layout the object is attached to.

Definition at line 255 of file qgslayoutobject.cpp.

layout() [2/2]

const QgsLayout * QgsLayoutObject::layout

(

)

const

Returns the layout the object is attached to.

Definition at line 250 of file qgslayoutobject.cpp.

propertyAssociatesWithParentMultiframe()

bool QgsLayoutObject::propertyAssociatesWithParentMultiframe ( QgsLayoutObject::DataDefinedProperty  property )

static

Returns true if the specified property key is normally associated with the parent QgsLayoutMultiFrame object instead of a child QgsLayoutFrame object.

While some properties like QgsLayoutObject::DataDefinedProperty::PositionX and QgsLayoutObject::DataDefinedProperty::ItemWidth are typically associated with a direct QgsLayoutItem subclass (including QgsLayoutFrame objects), other properties are instead associated with a QgsLayoutMultiFrame object (such as QgsLayoutObject::DataDefinedProperty::SourceUrl or QgsLayoutObject::DataDefinedProperty::AttributeTableSourceLayer).

Since

QGIS 3.18.1

Definition at line 137 of file qgslayoutobject.cpp.

propertyDefinitions()

const QgsPropertiesDefinition & QgsLayoutObject::propertyDefinitions ( )

static

Returns the layout object property definitions.

Definition at line 131 of file qgslayoutobject.cpp.

readObjectPropertiesFromElement()

bool QgsLayoutObject::readObjectPropertiesFromElement ( const QDomElement &  parentElement, const QDomDocument &  document, const QgsReadWriteContext &  context  )

protected

Sets object properties from a DOM element.

Parameters

parentElement	is the parent DOM element for the object
document	DOM document
context	read write context

Returns

true if read was successful

See also

writeObjectPropertiesToElement()

Definition at line 313 of file qgslayoutobject.cpp.

refresh

virtual void QgsLayoutObject::refresh ( )

inlinevirtualslot

Refreshes the object, causing a recalculation of any property overrides.

Reimplemented in QgsLayoutItemMapGrid.

Definition at line 361 of file qgslayoutobject.h.

removeCustomProperty()

void QgsLayoutObject::removeCustomProperty

(

const QString &

key

)

Remove a custom property from the object.

Parameters

key	property key

See also

setCustomProperty()

customProperty()

customProperties()

Definition at line 270 of file qgslayoutobject.cpp.

setCustomProperty()

void QgsLayoutObject::setCustomProperty	(	const QString &	key,
		const QVariant &	value
	)

Set a custom property for the object.

Parameters

key	property key. If a property with the same key already exists it will be overwritten.
value	property value

See also

customProperty()

removeCustomProperty()

customProperties()

Definition at line 260 of file qgslayoutobject.cpp.

setDataDefinedProperties()

void QgsLayoutObject::setDataDefinedProperties ( const QgsPropertyCollection &  collection )

inline

Sets the objects's property collection, used for data defined overrides.

Parameters

collection

property collection. Existing properties will be replaced.

See also

dataDefinedProperties()

DataDefinedProperty

Definition at line 309 of file qgslayoutobject.h.

writeObjectPropertiesToElement()

bool QgsLayoutObject::writeObjectPropertiesToElement ( QDomElement &  parentElement, QDomDocument &  document, const QgsReadWriteContext &  context  ) const

protected

Stores object properties within an XML DOM element.

Parameters

parentElement	is the parent DOM element to store the object's properties in
document	DOM document
context	read write context

Returns

true if write was successful

See also

readObjectPropertiesFromElement()

Definition at line 292 of file qgslayoutobject.cpp.

Friends And Related Symbol Documentation

QgsCompositionConverter

friend class QgsCompositionConverter

friend

Definition at line 407 of file qgslayoutobject.h.

TestQgsLayoutObject

friend class TestQgsLayoutObject

friend

Definition at line 406 of file qgslayoutobject.h.

Member Data Documentation

mCustomProperties

QgsObjectCustomProperties QgsLayoutObject::mCustomProperties

protected

Custom properties for object.

Definition at line 397 of file qgslayoutobject.h.

mDataDefinedProperties

QgsPropertyCollection QgsLayoutObject::mDataDefinedProperties

protected

Definition at line 394 of file qgslayoutobject.h.

mLayout

QPointer< QgsLayout > QgsLayoutObject::mLayout

protected

Definition at line 392 of file qgslayoutobject.h.

---

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

• /build/qgis-3.99.0+git20250718+f78f5286a64+99sid/src/core/layout/qgslayoutobject.h
• /build/qgis-3.99.0+git20250718+f78f5286a64+99sid/src/core/layout/qgslayoutobject.cpp