Subgroup: Auxiliary

Class: QgsAuxiliaryLayer

class qgis.core.QgsAuxiliaryLayer(pkField: str, filename: str, table: str, vlayer: QgsVectorLayer)

Bases: qgis._core.QgsVectorLayer

Constructor

Parameters:
  • pkField – The primary key to use for joining
  • filename – The database path
  • table – The table name
  • vlayer – The target vector layer in join definition

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: Methods

addAuxiliaryField Adds an auxiliary field for the given property.
appendError
auxiliaryFields Returns a list of all auxiliary fields currently managed by the layer.
childEvent
clear Deletes all features from the layer.
clone Returns a new instance equivalent to this one.
connectNotify
createAuxiliaryField Creates a new auxiliary field from a property definition.
createProperty Creates if necessary a new auxiliary field for a PAL property and activates this property in settings.
customEvent
deleteAttribute Removes attribute from the layer and commits changes.
disconnectNotify
exists Returns true if the property is stored in the layer already, false otherwise.
hasDependencyCycle
indexOfPropertyDefinition Returns the index of the auxiliary field for a specific property definition.
isHiddenProperty Returns true if the underlying field has to be hidden from editing tools like attribute table, false otherwise.
isSignalConnected
joinInfo Returns information to use for joining with primary key and so on.
nameFromProperty Returns the name of the auxiliary field for a property definition.
propertyDefinitionFromField Returns the property definition from an auxiliary field.
propertyDefinitionFromIndex Returns the property definition for the underlying field index.
propertyFromIndex Returns the underlying property key for the field index.
readCommonStyle
readCustomProperties
readStyleManager
receivers
save Commits changes and starts editing then.
sender
senderSignalIndex
setError
setExtent
setValid
timerEvent
toSpatialLayer An auxiliary layer is not spatial.
writeCommonStyle
writeCustomProperties
writeStyleManager

Signals

Attributes

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 – The definition of the property to add
Returns:true if the auxiliary field is well added, false otherwise
appendError()
auxiliaryFields(self) → QgsFields

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

childEvent()
clear(self) → bool

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

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 – The layer for which the clone is made
connectNotify()
createAuxiliaryField(definition: QgsPropertyDefinition) → QgsField

Creates a new auxiliary field from a property definition.

Parameters:definition – 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
createProperty(property: QgsPalLayerSettings.Property, vlayer: QgsVectorLayer) → int

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

Parameters:
  • property – The property to create
  • vlayer – The vector layer
Returns:

The index of the auxiliary field or -1

createProperty(property: QgsDiagramLayerSettings.Property, vlayer: QgsVectorLayer) -> 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
Returns:

The index of the auxiliary field or -1

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

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

Parameters:attr – The index of the attribute to remove
Returns:true if the attribute is well deleted, false otherwise
disconnectNotify()
exists(self, definition: QgsPropertyDefinition) → bool

Returns true if the property is stored in the layer already, false otherwise.

Parameters:definition – The property definition to check
Returns:true if the property is stored, false otherwise
hasDependencyCycle()
indexOfPropertyDefinition(self, definition: QgsPropertyDefinition) → int

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

Parameters:definition – The property definition
Returns:The index of the field corresponding to the property or -1
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 – The index of the field for which visibility is checked
isSignalConnected()
joinInfo(self) → QgsVectorLayerJoinInfo

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

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

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

Parameters:
  • def – The property definition
  • joined – The join prefix is taken into account if true
propertyDefinitionFromField(field: QgsField) → QgsPropertyDefinition

Returns the property definition from an auxiliary field.

Parameters:field – The auxiliary field
propertyDefinitionFromIndex(self, index: int) → QgsPropertyDefinition

Returns the property definition for the underlying field index.

Parameters:index – The index of the field
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 – The index of the field
readCommonStyle()
readCustomProperties()
readStyleManager()
receivers()
save(self) → bool

Commits changes and starts editing then.

Returns:true if commit step passed, false otherwise
sender()
senderSignalIndex()
setError()
setExtent()
setValid()
timerEvent()
toSpatialLayer(self) → QgsVectorLayer

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

Returns:A new spatial vector layer
writeCommonStyle()
writeCustomProperties()
writeStyleManager()