Class: QgsAuxiliaryLayer

class qgis.core.QgsAuxiliaryLayer

Bases: QgsVectorLayer

Class allowing to manage the auxiliary storage for a vector layer.

Such auxiliary data are data used mostly for the needs of QGIS (symbology) and have no real interest in being stored with the native raw geospatial data.

The need arises from the restrictions existing in the manual placement of labels. Manual placement of labels are possible in QGIS by setting some labeling properties (X and Y position, and rotation angle optionally) as being “data-defined”, meaning that values come from a column (or an expression). But setting this up on an existing layer requires either to add new columns to the source layer, while it is not always possible or desirable.

This QgsAuxiliaryLayer provides the solution to this limitation. Actually it’s an editable join to the original vector layer with some synchronisation mechanisms activated such as “Upsert On Edit” or “Delete Cascade”. Thus, auxiliary fields are editable even if the source layer is not and edition of a joined field is also possible.

New in version 3.0.

QgsAuxiliaryLayer(pkField: str, filename: str, table: str, vlayer: QgsVectorLayer) Constructor

Parameters:
addAuxiliaryField(self, definition: QgsPropertyDefinition) → bool

Adds an auxiliary field for the given property. Setup for widget editors are updated in the target layer as well as the attribute table config to hide auxiliary fields by default.

Parameters:

definition (QgsPropertyDefinition) – The definition of the property to add

Return type:

bool

Returns:

True if the auxiliary field is well added, False otherwise

appendError(self, error: QgsErrorMessage)

Add error message

auxiliaryFields(self) → QgsFields

Returns a list of all auxiliary fields currently managed by the layer.

Return type:

QgsFields

childEvent(self, QChildEvent)
clear(self) → bool

Deletes all features from the layer. Changes are automatically committed and the layer remains editable.

Return type:

bool

Returns:

True if changes are committed without error, False otherwise.

clone(self, layer: QgsVectorLayer) → QgsAuxiliaryLayer

Returns a new instance equivalent to this one. The underlying table is duplicate for the layer given in parameter. Note that the current auxiliary layer should be saved to have a proper duplicated table.

Parameters:

layer (QgsVectorLayer) – The layer for which the clone is made

Return type:

QgsAuxiliaryLayer

connectNotify(self, QMetaMethod)
createAuxiliaryField(definition: QgsPropertyDefinition) → QgsField

Creates a new auxiliary field from a property definition.

Parameters:

definition (QgsPropertyDefinition) – The property definition of the auxiliary field to create

createAuxiliaryField(field: QgsField) -> QgsField Creates a new auxiliary field from a field.

Parameters:

field – The field to use to create the auxiliary field

Return type:

QgsField

createProperty(property: QgsPalLayerSettings.Property, vlayer: QgsVectorLayer, overwriteExisting: bool = True) → int

Creates if necessary a new auxiliary field for a PAL property and activates this property in settings.

Parameters:

  • property (QgsPalLayerSettings.Property) – The property to create

  • vlayer (QgsVectorLayer) – The vector layer

  • overwriteExisting (bool = True) – since QGIS 3.22, controls whether an existing property should be completely overwritten or upgraded to a coalesce(“new aux field”, ‘existing’ || ‘property’ || ‘expression’) type property

Returns:

The index of the auxiliary field or -1

createProperty(property: QgsDiagramLayerSettings.Property, vlayer: QgsVectorLayer, overwriteExisting: bool = True) -> int Creates if necessary a new auxiliary field for a diagram’s property and activates this property in settings.

Parameters:

  • property – The property to create

  • vlayer – The vector layer

  • overwriteExisting – since QGIS 3.22, controls whether an existing property should be completely overwritten or upgraded to a coalesce(“new aux field”, ‘existing’ || ‘property’ || ‘expression’) type property

Returns:

The index of the auxiliary field or -1

createProperty(property: QgsCallout.Property, vlayer: QgsVectorLayer, overwriteExisting: bool = True) -> int Creates if necessary a new auxiliary field for a callout’s property and activates this property in settings.

Parameters:

  • property – The property to create

  • vlayer – The vector layer

  • overwriteExisting – since QGIS 3.22, controls whether an existing property should be completely overwritten or upgraded to a coalesce(“new aux field”, ‘existing’ || ‘property’ || ‘expression’) type property

Return type:

int

Returns:

The index of the auxiliary field or -1

New in version 3.20.

customEvent(self, QEvent)
deleteAttribute(self, attr: int) → bool

Removes attribute from the layer and commits changes. The layer remains editable.

Parameters:

attr (int) – The index of the attribute to remove

Return type:

bool

Returns:

True if the attribute is well deleted, False otherwise

disconnectNotify(self, QMetaMethod)
exists(self, definition: QgsPropertyDefinition) → bool

Returns True if the property is stored in the layer already, False otherwise.

Parameters:

definition (QgsPropertyDefinition) – The property definition to check

Return type:

bool

Returns:

True if the property is stored, False otherwise

hasDependencyCycle(self, Iterable[QgsMapLayerDependency]) → bool

Checks whether a new set of dependencies will introduce a cycle this method is now deprecated and always return False, because circular dependencies are now correctly managed.

Deprecated since version QGIS: 3.10

indexOfPropertyDefinition(self, definition: QgsPropertyDefinition) → int

Returns the index of the auxiliary field for a specific property definition.

Parameters:

definition (QgsPropertyDefinition) – The property definition

Return type:

int

Returns:

The index of the field corresponding to the property or -1

invalidateWgs84Extent(self)

Invalidates the WGS84 extent. If FlagTrustLayerMetadata is enabled, the extent is not invalidated because we want to trust metadata whatever happens.

New in version 3.20.

isHiddenProperty(self, index: int) → bool

Returns True if the underlying field has to be hidden from editing tools like attribute table, False otherwise.

Parameters:

index (int) – The index of the field for which visibility is checked

Return type:

bool

isSignalConnected(self, QMetaMethod) → bool
joinInfo(self) → QgsVectorLayerJoinInfo

Returns information to use for joining with primary key and so on.

Return type:

QgsVectorLayerJoinInfo

nameFromProperty(def_: QgsPropertyDefinition, joined: bool = False) → str

Returns the name of the auxiliary field for a property definition.

Parameters:

  • def (QgsPropertyDefinition) – The property definition

  • joined (bool = False) – The join prefix is taken into account if True

  • def –

Return type:

str

propertyDefinitionFromField(field: QgsField) → QgsPropertyDefinition

Returns the property definition from an auxiliary field.

Parameters:

field (QgsField) – The auxiliary field

Return type:

QgsPropertyDefinition

propertyDefinitionFromIndex(self, index: int) → QgsPropertyDefinition

Returns the property definition for the underlying field index.

Parameters:

index (int) – The index of the field

Return type:

QgsPropertyDefinition

propertyFromIndex(self, index: int) → int

Returns the underlying property key for the field index. The key may be a PAL, diagram or symbology property according to the underlying property definition of the field. The key -1 is returned if an error happened.

Parameters:

index (int) – The index of the field

Return type:

int

readCommonStyle(self, layerElement: QDomElement, context: QgsReadWriteContext, categories: QgsMapLayer.StyleCategories | QgsMapLayer.StyleCategory = QgsMapLayer.AllStyleCategories)

Read style data common to all layer types

New in version 3.0.

readCustomProperties(self, layerNode: QDomNode, keyStartsWith: str = '')

Read custom properties from project file.

Parameters:

  • layerNode – note to read from

  • keyStartsWith – reads only properties starting with the specified string (or all if the string is empty)

readStyleManager(self, layerNode: QDomNode)

Read style manager’s configuration (if any). To be called by subclasses.

receivers(self, PYQT_SIGNAL) → int
save(self) → bool

Commits changes and starts editing then.

Return type:

bool

Returns:

True if commit step passed, False otherwise

sender(self) → QObject
senderSignalIndex(self) → int
setError(self, error: QgsError)

Sets error message

setExtent(self, rect: QgsRectangle)

Sets the extent

setProviderType(self, providerType: str)

Sets the providerType (provider key)

setValid(self, valid: bool)

Sets whether layer is valid or not

timerEvent(self, QTimerEvent)
toSpatialLayer(self) → QgsVectorLayer

An auxiliary layer is not spatial. This method returns a spatial representation of auxiliary data.

Return type:

QgsVectorLayer

Returns:

A new spatial vector layer

writeCommonStyle(self, layerElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext, categories: QgsMapLayer.StyleCategories | QgsMapLayer.StyleCategory = QgsMapLayer.AllStyleCategories)

Write style data common to all layer types

New in version 3.0.

writeCustomProperties(self, layerNode: QDomNode, doc: QDomDocument)

Write custom properties to project file.

writeStyleManager(self, layerNode: QDomNode, doc: QDomDocument)

Write style manager’s configuration (if exists). To be called by subclasses.