QgsAuxiliaryLayer class

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

Reference

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.

Base classes

class QgsVectorLayer: Represents a vector layer which manages a vector based data sets.

Public static functions

static auto createAuxiliaryField(const QgsPropertyDefinition& definition) -> QgsField: Creates a new auxiliary field from a property definition.
static auto createAuxiliaryField(const QgsField& field) -> QgsField: Creates a new auxiliary field from a field.
static auto createProperty(QgsPalLayerSettings::Property property, QgsVectorLayer* vlayer) -> int: Creates if necessary a new auxiliary field for a PAL property and activates this property in settings.
static auto createProperty(QgsDiagramLayerSettings::Property property, QgsVectorLayer* vlayer) -> int: Creates if necessary a new auxiliary field for a diagram's property and activates this property in settings.
static auto nameFromProperty(const QgsPropertyDefinition& def, bool joined = false) -> QString: Returns the name of the auxiliary field for a property definition.
static auto propertyDefinitionFromField(const QgsField& field) -> QgsPropertyDefinition: Returns the property definition from an auxiliary field.

Constructors, destructors, conversion operators

QgsAuxiliaryLayer(const QString& pkField, const QString& filename, const QString& table, QgsVectorLayer* vlayer): Constructor.
QgsAuxiliaryLayer(const QgsAuxiliaryLayer& rhs) deleted: Copy constructor deactivated.

Public functions

auto addAuxiliaryField(const QgsPropertyDefinition& definition) -> bool: Adds an auxiliary field for the given property.
auto auxiliaryFields() const -> QgsFields: Returns a list of all auxiliary fields currently managed by the layer.
auto clear() -> bool: Deletes all features from the layer.
auto clone(QgsVectorLayer* layer) const -> QgsAuxiliaryLayer*: Returns a new instance equivalent to this one.
auto deleteAttribute(int attr) -> bool override: Removes attribute from the layer and commits changes.
auto exists(const QgsPropertyDefinition& definition) const -> bool: Returns true if the property is stored in the layer already, false otherwise.
auto indexOfPropertyDefinition(const QgsPropertyDefinition& definition) const -> int: Returns the index of the auxiliary field for a specific property definition.
auto isHiddenProperty(int index) const -> bool: Returns true if the underlying field has to be hidden from editing tools like attribute table, false otherwise.
auto joinInfo() const -> QgsVectorLayerJoinInfo: Returns information to use for joining with primary key and so on.
auto propertyDefinitionFromIndex(int index) const -> QgsPropertyDefinition: Returns the property definition for the underlying field index.
auto propertyFromIndex(int index) const -> int: Returns the underlying property key for the field index.
auto save() -> bool: Commits changes and starts editing then.
auto toSpatialLayer() const -> QgsVectorLayer*: An auxiliary layer is not spatial.

Function documentation

static QgsField QgsAuxiliaryLayer::createAuxiliaryField(const QgsPropertyDefinition& definition)

Creates a new auxiliary field from a property definition.

Parameters
definition	The property definition of the auxiliary field to create

static QgsField QgsAuxiliaryLayer::createAuxiliaryField(const QgsField& field)

Creates a new auxiliary field from a field.

Parameters
field	The field to use to create the auxiliary field

static int QgsAuxiliaryLayer::createProperty(QgsPalLayerSettings::Property property, QgsVectorLayer* vlayer)

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

static int QgsAuxiliaryLayer::createProperty(QgsDiagramLayerSettings::Property property, QgsVectorLayer* vlayer)

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

static QString QgsAuxiliaryLayer::nameFromProperty(const QgsPropertyDefinition& def, bool joined = false)

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

static QgsPropertyDefinition QgsAuxiliaryLayer::propertyDefinitionFromField(const QgsField& field)

Returns the property definition from an auxiliary field.

Parameters
field	The auxiliary field

QgsAuxiliaryLayer::QgsAuxiliaryLayer(const QString& pkField, const QString& filename, const QString& table, QgsVectorLayer* vlayer)

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

bool QgsAuxiliaryLayer::addAuxiliaryField(const QgsPropertyDefinition& definition)

Adds an auxiliary field for the given property.

Parameters
definition	The definition of the property to add
Returns	true if the auxiliary field is well added, false otherwise

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

bool QgsAuxiliaryLayer::clear()

Deletes all features from the layer.

Returns	true if changes are committed without error, false otherwise.

Changes are automatically committed and the layer remains editable.

QgsAuxiliaryLayer* QgsAuxiliaryLayer::clone(QgsVectorLayer* layer) const

Returns a new instance equivalent to this one.

Parameters
layer	The layer for which the clone is made

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.

bool QgsAuxiliaryLayer::deleteAttribute(int attr) override

Removes attribute from the layer and commits changes.

Parameters
attr	The index of the attribute to remove
Returns	true if the attribute is well deleted, false otherwise

The layer remains editable.

bool QgsAuxiliaryLayer::exists(const QgsPropertyDefinition& definition) const

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

int QgsAuxiliaryLayer::indexOfPropertyDefinition(const QgsPropertyDefinition& definition) const

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

bool QgsAuxiliaryLayer::isHiddenProperty(int index) const

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

QgsPropertyDefinition QgsAuxiliaryLayer::propertyDefinitionFromIndex(int index) const

Returns the property definition for the underlying field index.

Parameters
index	The index of the field

int QgsAuxiliaryLayer::propertyFromIndex(int index) const

Returns the underlying property key for the field index.

Parameters
index	The index of the field

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.

bool QgsAuxiliaryLayer::save()

Commits changes and starts editing then.

Returns	true if commit step passed, false otherwise

QgsVectorLayer* QgsAuxiliaryLayer::toSpatialLayer() const

An auxiliary layer is not spatial.

Returns	A new spatial vector layer

This method returns a spatial representation of auxiliary data.