Class: QgsLayoutObject¶

A base class for objects which belong to a layout.

Class Hierarchy¶

Base classes¶

QObject
`QgsExpressionContextGenerator`	Abstract interface for generating an expression context.

Subclasses¶

`QgsLayoutItem`	Base class for graphical items within a `QgsLayout`.
`QgsLayoutMultiFrame`	Abstract base class for layout items with the ability to distribute the content to several frames (`QgsLayoutFrame` items).
`QgsLayoutItemMapItem`	An item which is drawn inside a `QgsLayoutItemMap`, e.g., a grid or map overview.

Enums

DataDefinedProperty

Data defined properties for different item types

Abstract Methods

createExpressionContext

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

Methods

`customProperties`	Returns list of keys stored in custom properties for the object.
`customProperty`	Read a custom property from the object.
`dataDefinedProperties`	Returns a reference to the object's property collection, used for data defined overrides.
`layout`	Returns the layout the object is attached to.
`propertyDefinitions`	Returns the layout object property definitions.
`readObjectPropertiesFromElement`	Sets object properties from a DOM element
`removeCustomProperty`	Remove a custom property from the object.
`setCustomProperty`	Set a custom property for the object.
`setDataDefinedProperties`	Sets the objects's property collection, used for data defined overrides.
`writeObjectPropertiesToElement`	Stores object properties within an XML DOM element.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsLayoutObject. See the FAQ for more details.

refresh

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

Static Methods

propertyAssociatesWithParentMultiframe

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

Signals

changed

Emitted when the object's properties change.

Attributes

`EvaluatedValue`
`OriginalValue`

class qgis.core.QgsLayoutObject[source]¶

Bases: QObject, QgsExpressionContextGenerator

__init__(layout: QgsLayout | None)

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.

Parameters:: layout (Optional[QgsLayout])

class DataDefinedProperty(*values)¶

Bases: IntEnum

Data defined properties for different item types

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

Added in version 3.30.
MarginTop: Top margin

Added in version 3.30.
MarginRight: Right margin

Added in version 3.30.
MarginBottom: Bottom margin

Added in version 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

Added in version 3.38.
MapZRangeUpper: Map frame Z-range lower value

Added in version 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

Added in version 3.44.
ScalebarLeftSegments: Number of segments on the left of 0

Added in version 3.26.
ScalebarRightSegments: Number of segments on the right of 0

Added in version 3.26.
ScalebarSegmentWidth: Scalebar width in map units of a single segment

Added in version 3.26.
ScalebarMinimumWidth: Scalebar segment minimum width

Added in version 3.26.
ScalebarMaximumWidth: Scalebar segment maximum width

Added in version 3.26.
ScalebarHeight: Scalebar height

Added in version 3.26.
ScalebarRightSegmentSubdivisions: Number of subdivisions per segment on right of 0

Added in version 3.26.
ScalebarSubdivisionHeight: Scalebar subdivision height

Added in version 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

Added in version 3.30.
ElevationProfileDistanceMajorInterval: Major grid line interval for elevation profile distance axis

Added in version 3.30.
ElevationProfileDistanceMinorInterval: Minor grid line interval for elevation profile distance axis

Added in version 3.30.
ElevationProfileDistanceLabelInterval: Label interval for elevation profile distance axis

Added in version 3.30.
ElevationProfileElevationMajorInterval: Major grid line interval for elevation profile elevation axis

Added in version 3.30.
ElevationProfileElevationMinorInterval: Minor grid line interval for elevation profile elevation axis

Added in version 3.30.
ElevationProfileElevationLabelInterval: Label interval for elevation profile elevation axis

Added in version 3.30.
ElevationProfileMinimumDistance: Minimum distance value for elevation profile

Added in version 3.30.
ElevationProfileMaximumDistance: Maximum distance value for elevation profile

Added in version 3.30.
ElevationProfileMinimumElevation: Minimum elevation value for elevation profile

Added in version 3.30.
ElevationProfileMaximumElevation: Maximum elevation value for elevation profile

Added in version 3.30.

EvaluatedValue = 0¶

OriginalValue = 1¶

class PropertyValueType¶: Bases: int

signal changed[source]¶: Emitted when the object’s properties change.

abstract createExpressionContext(self) → QgsExpressionContext[source]¶

Creates an expression context relating to the objects’ current state. The context includes scopes for global, project and layout properties.

Return type:: QgsExpressionContext

customProperties(self) → List[str][source]¶

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

See also

setCustomProperty()

See also

customProperty()

See also

removeCustomProperty()

Return type:: List[str]

customProperty(self, key: str | None, defaultValue: Any = None) → Any[source]¶

Read a custom property from the object.

Parameters:

key (Optional[str]) – property key
defaultValue (Any = None) – default value to return if property with matching key does not exist

Return type:

Any

Returns:

value of matching property

See also

setCustomProperty()

See also

removeCustomProperty()

See also

customProperties()

dataDefinedProperties(self) → QgsPropertyCollection¶

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

See also

setDataDefinedProperties()

Return type:: QgsPropertyCollection

layout(self) → QgsLayout | None[source]¶

Returns the layout the object is attached to.

Return type:: Optional[QgsLayout]

static propertyAssociatesWithParentMultiframe(property: QgsLayoutObject.DataDefinedProperty) → bool[source]¶

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

Added in version 3.18.1.

Parameters:: property (QgsLayoutObject.DataDefinedProperty)
Return type:: bool

propertyDefinitions() → Dict[int, QgsPropertyDefinition]¶

Returns the layout object property definitions.

Return type:: Dict[int, QgsPropertyDefinition]

readObjectPropertiesFromElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool[source]¶

Sets object properties from a DOM element

Parameters:

parentElement (QDomElement) – is the parent DOM element for the object
document (QDomDocument) – DOM document
context (QgsReadWriteContext) – read write context

Return type:

bool

Returns:

True if read was successful

See also

writeObjectPropertiesToElement()

virtual refresh(self)[source]¶: Refreshes the object, causing a recalculation of any property overrides.

removeCustomProperty(self, key: str | None)[source]¶

Remove a custom property from the object.

Parameters:: key (Optional[str]) – property key

See also

setCustomProperty()

See also

customProperty()

See also

customProperties()

setCustomProperty(self, key: str | None, value: Any)[source]¶

Set a custom property for the object.

Parameters:

key (Optional[str]) – property key. If a property with the same key already exists it will be overwritten.
value (Any) – property value

See also

customProperty()

See also

removeCustomProperty()

See also

customProperties()

setDataDefinedProperties(self, collection: QgsPropertyCollection)[source]¶

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

Parameters:: collection (QgsPropertyCollection) – property collection. Existing properties will be replaced.

See also

dataDefinedProperties()

See also

DataDefinedProperty

writeObjectPropertiesToElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool[source]¶

Stores object properties within an XML DOM element.

Parameters:

parentElement (QDomElement) – is the parent DOM element to store the object’s properties in
document (QDomDocument) – DOM document
context (QgsReadWriteContext) – read write context

Return type:

bool

Returns:

True if write was successful

See also

readObjectPropertiesFromElement()