Class: QgsPropertyOverrideButton

A button for controlling property overrides which may apply to a widget.

QgsPropertyOverrideButton is designed to be used alongside the QGIS properties framework (QgsProperty, QgsPropertyDefinition and QgsPropertyCollection).

It allows users to specify field or expression based overrides which should be applied to a property of an object. Eg, this widget is used for controlling data defined overrides in symbology, labeling and layouts.

Class Hierarchy

Base classes

QToolButton
QAbstractButton
QWidget
QObject
QPaintDevice

Methods

aboutToShowMenu
fullDescription	Returns the full definition description and current definition (internally generated on a contextual basis).
init	Initialize a newly constructed property button (useful if button was included in a UI layout).
isActive	Returns True if the button has an active property.
menuActionTriggered
propertyKey	Returns the property key linked to the button.
registerCheckedWidget	Register a sibling widget that gets checked when the property is active.
registerEnabledWidget	Register a sibling widget that gets enabled when the property is active, and disabled when the property is inactive.
registerExpressionContextGenerator	Register an expression context generator class that will be used to retrieve an expression context for the button when required.
registerExpressionWidget	Register a sibling widget (line edit, text edit) that will receive the property as an expression
registerLinkedWidget	Registers a widget which is linked to this button.
registerVisibleWidget	Register a sibling widget that gets visible when the property is active, and hidden when the property is inactive.
setActive	Set whether the current property override definition is to be used
setToProperty	Sets the widget to reflect the current state of a QgsProperty.
setUsageInfo	Set the usage information for the property.
setVectorLayer	Sets the vector layer associated with the button.
toProperty	Returns a QgsProperty object encapsulating the current state of the widget.
updateFieldLists	Updates list of fields.
usageInfo	Returns usage information for the property.
validDataType	Returns the data type which the widget will accept.
vectorLayer	Returns the vector layer associated with the button.

Signals

activated	Emitted when the activated status of the widget changes
changed	Emitted when property definition changes
createAuxiliaryField	Emitted when creating a new auxiliary field

class qgis.gui.QgsPropertyOverrideButton

Bases: QToolButton

__init__(parent: QWidget | None = None, layer: QgsVectorLayer | None = None)

Constructor for QgsPropertyOverrideButton.

Parameters:

• parent (Optional[QWidget] = None) – parent widget

• layer (Optional[QgsVectorLayer] = None) – associated vector layer

aboutToShowMenu(self)

signal activated(isActive: bool)

Emitted when the activated status of the widget changes

Parameters:

isActive (bool)

signal changed

Emitted when property definition changes

signal createAuxiliaryField

Emitted when creating a new auxiliary field

fullDescription(self) → str

Returns the full definition description and current definition (internally generated on a contextual basis).

Return type:

str

init(self, propertyKey: int, property: QgsProperty, definitions: Dict[int, QgsPropertyDefinition], layer: QgsVectorLayer | None = None, auxiliaryStorageEnabled: bool = False)

Initialize a newly constructed property button (useful if button was included in a UI layout).

Parameters:

• propertyKey (int) – key for corresponding property

• property (QgsProperty) – initial value of associated property to show in widget

• definitions (Dict[int, QgsPropertyDefinition]) – properties definitions for corresponding collection

• layer (Optional[QgsVectorLayer] = None) – associated vector layer

• auxiliaryStorageEnabled (bool = False) – If True, activate the button to store data defined in auxiliary storage

init(self, propertyKey: int, property: QgsProperty, definition: QgsPropertyDefinition, layer: QgsVectorLayer | None = None, auxiliaryStorageEnabled: bool = False)

Initialize a newly constructed property button (useful if button was included in a UI layout).

Parameters:

• propertyKey (int) – key for corresponding property

• property (QgsProperty) – initial value of associated property to show in widget

• definition (QgsPropertyDefinition) – properties definition for button

• layer (Optional[QgsVectorLayer] = None) – associated vector layer

• auxiliaryStorageEnabled (bool = False) – If True, activate the button to store data defined in auxiliary storage

init(self, propertyKey: int, collection: QgsAbstractPropertyCollection, definitions: Dict[int, QgsPropertyDefinition], layer: QgsVectorLayer | None = None, auxiliaryStorageEnabled: bool = False)

Initialize a newly constructed property button (useful if button was included in a UI layout).

Parameters:

• propertyKey (int) – key for corresponding property

• collection (QgsAbstractPropertyCollection) – associated property collection

• definitions (Dict[int, QgsPropertyDefinition]) – properties definitions for collection

• layer (Optional[QgsVectorLayer] = None) – associated vector layer

• auxiliaryStorageEnabled (bool = False) – If True, activate the button to store data defined in auxiliary storage

isActive(self) → bool

Returns True if the button has an active property.

Return type:

bool

menuActionTriggered(self, action: QAction | None)

Parameters:

action (Optional[QAction])

propertyKey(self) → int

Returns the property key linked to the button.

Return type:

int

registerCheckedWidget(self, widget: QWidget | None, natural: bool = True)

Register a sibling widget that gets checked when the property is active. if natural is False, widget gets unchecked when the property is active.

Note

this should be called after calling init() to be correctly initialized.

Parameters:

• widget (Optional[QWidget])

• natural (bool = True)

registerEnabledWidget(self, widget: QWidget | None, natural: bool = True)

Register a sibling widget that gets enabled when the property is active, and disabled when the property is inactive. if natural is False, widget gets disabled when the property is active, and enabled when the property is inactive.

Note

this should be called after calling init() to be correctly initialized.

Parameters:

• widget (Optional[QWidget])

• natural (bool = True)

registerExpressionContextGenerator(self, generator: QgsExpressionContextGenerator | None)

Register an expression context generator class that will be used to retrieve an expression context for the button when required.

Parameters:

generator (Optional[QgsExpressionContextGenerator])

registerExpressionWidget(self, widget: QWidget | None)

Register a sibling widget (line edit, text edit) that will receive the property as an expression

Note

this should be called after calling init() to be correctly initialized.

Parameters:

widget (Optional[QWidget])

registerLinkedWidget(self, widget: QWidget | None)

Registers a widget which is linked to this button. The meaning of linked widgets depends on the property type, and the type of linked widget.

For color properties, linking a QgsColorButton allows the color button to correctly reflect the status of the property when it’s set to follow a project color.

Added in version 3.6.

Parameters:

widget (Optional[QWidget])

registerVisibleWidget(self, widget: QWidget | None, natural: bool = True)

Register a sibling widget that gets visible when the property is active, and hidden when the property is inactive. if natural is False, widget gets hidden when the property is active, and visible when the property is inactive.

Note

this should be called after calling init() to be correctly initialized.

Parameters:

• widget (Optional[QWidget])

• natural (bool = True)

setActive(self, active: bool)

Set whether the current property override definition is to be used

Parameters:

active (bool)

setToProperty(self, property: QgsProperty)

Sets the widget to reflect the current state of a QgsProperty.

Parameters:

property (QgsProperty)

setUsageInfo(self, info: str | None)

Set the usage information for the property.

See also

usageInfo()

Parameters:

info (Optional[str])

setVectorLayer(self, layer: QgsVectorLayer | None)

Sets the vector layer associated with the button. This controls which fields are displayed within the widget’s pop up menu.

See also

vectorLayer()

Parameters:

layer (Optional[QgsVectorLayer])

toProperty(self) → QgsProperty

Returns a QgsProperty object encapsulating the current state of the widget.

See also

setToProperty()

Return type:

QgsProperty

updateFieldLists(self)

Updates list of fields.

usageInfo(self) → str

Returns usage information for the property.

See also

setUsageInfo()

Return type:

str

validDataType(self) → QgsPropertyDefinition.DataType

Returns the data type which the widget will accept. This is used to filter out fields from the associated vector layer to only show fields which are compatible with the property.

Return type:

QgsPropertyDefinition.DataType

vectorLayer(self) → QgsVectorLayer | None

Returns the vector layer associated with the button. This controls which fields are displayed within the widget’s pop up menu.

See also

setVectorLayer()

Return type:

Optional[QgsVectorLayer]