QGIS API Documentation 3.28.0-Firenze (ed3ad0430f)
Classes | Public Member Functions | Static Public Member Functions | Properties | List of all members
QgsRelation Class Reference

#include <qgsrelation.h>

Classes

class  FieldPair
 Defines a relation between matching fields of the two involved tables of a relation. More...
 

Public Member Functions

 QgsRelation ()
 Default constructor. More...
 
 QgsRelation (const QgsRelation &other)
 Copies a relation. More...
 
 QgsRelation (const QgsRelationContext &context)
 Constructor with context. More...
 
 ~QgsRelation ()
 
void addFieldPair (const FieldPair &fieldPair)
 Add a field pair which is part of this relation The first element of each pair are the field names of the foreign key. More...
 
void addFieldPair (const QString &referencingField, const QString &referencedField)
 Add a field pair which is part of this relation The first element of each pair are the field names of the foreign key. More...
 
QList< QgsRelation::FieldPairfieldPairs () const
 Returns the field pairs which form this relation The first element of each pair are the field names of the foreign key. More...
 
void generateId ()
 Generate a (project-wide) unique id for this relation. More...
 
QgsFeature getReferencedFeature (const QgsFeature &feature) const
 Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature. More...
 
QgsFeatureRequest getReferencedFeatureRequest (const QgsAttributes &attributes) const
 Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature. More...
 
QgsFeatureRequest getReferencedFeatureRequest (const QgsFeature &feature) const
 Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature. More...
 
QgsFeatureIterator getRelatedFeatures (const QgsFeature &feature) const
 Creates an iterator which returns all the features on the referencing (child) layer which have a foreign key pointing to the provided feature. More...
 
QString getRelatedFeaturesFilter (const QgsFeature &feature) const
 Returns a filter expression which returns all the features on the referencing (child) layer which have a foreign key pointing to the provided feature. More...
 
QgsFeatureRequest getRelatedFeaturesRequest (const QgsFeature &feature) const
 Creates a request to return all the features on the referencing (child) layer which have a foreign key pointing to the provided feature. More...
 
bool hasEqualDefinition (const QgsRelation &other) const
 Compares the two QgsRelation, ignoring the name and the ID. More...
 
QString id () const
 A (project-wide) unique id for this relation. More...
 
bool isValid () const
 Returns the validity of this relation. More...
 
QString name () const
 Returns a human readable name for this relation. More...
 
QgsRelationoperator= (const QgsRelation &other)
 Copies a relation. More...
 
QgsPolymorphicRelation polymorphicRelation () const
 Returns the parent polymorphic relation. More...
 
QString polymorphicRelationId () const
 Returns the parent polymorphic relation id. More...
 
QgsAttributeList referencedFields () const
 Returns a list of attributes used to form the referenced fields (most likely primary key) on the referenced (parent) layer. More...
 
QgsVectorLayerreferencedLayer () const
 Access the referenced (parent) layer. More...
 
QString referencedLayerId () const
 Access the referenced (parent) layer's id. More...
 
QgsAttributeList referencingFields () const
 Returns a list of attributes used to form the referencing fields (foreign key) on the referencing (child) layer. More...
 
QgsVectorLayerreferencingLayer () const
 Access the referencing (child) layer This is the layer which has the field(s) which point to another layer. More...
 
QString referencingLayerId () const
 Access the referencing (child) layer's id This is the layer which has the field(s) which point to another layer. More...
 
Q_INVOKABLE QString resolveReferencedField (const QString &referencingField) const
 Gets the referenced field counterpart given a referencing field. More...
 
Q_INVOKABLE QString resolveReferencingField (const QString &referencedField) const
 Gets the referencing field counterpart given a referenced field. More...
 
void setId (const QString &id)
 Set an id for this relation. More...
 
void setName (const QString &name)
 Set a name for this relation. More...
 
void setPolymorphicRelationId (const QString &polymorphicRelationId)
 Sets the parent polymorphic relation id. More...
 
void setReferencedLayer (const QString &id)
 Set the referenced (parent) layer id. More...
 
void setReferencingLayer (const QString &id)
 Set the referencing (child) layer id. More...
 
void setStrength (Qgis::RelationshipStrength strength)
 Set a strength for this relation. More...
 
Qgis::RelationshipStrength strength () const
 Returns the relation strength as a string. More...
 
Qgis::RelationshipType type () const
 Returns the type of the relation. More...
 
void updateRelationStatus ()
 Updates the validity status of this relation. More...
 
QString validationError () const
 Returns a user-friendly explanation for why the relationship is invalid. More...
 
void writeXml (QDomNode &node, QDomDocument &doc) const
 Writes a relation to an XML structure. More...
 

Static Public Member Functions

static QString cardinalityToDisplayString (Qgis::RelationshipCardinality cardinality)
 Returns a user-friendly translated string representing a relationship cardinality. More...
 
static QgsRelation createFromXml (const QDomNode &node, QgsReadWriteContext &context, const QgsRelationContext &relationContext=QgsRelationContext())
 Creates a relation from an XML structure. More...
 
static QString strengthToDisplayString (Qgis::RelationshipStrength strength)
 Returns a user-friendly translated string representing a relationship strength. More...
 

Properties

Q_GADGET QString id
 
bool isValid
 
QString name
 
QgsPolymorphicRelation polymorphicRelation
 
QString polymorphicRelationId
 
QgsVectorLayerreferencedLayer
 
QgsVectorLayerreferencingLayer
 

Detailed Description

Definition at line 41 of file qgsrelation.h.

Constructor & Destructor Documentation

◆ QgsRelation() [1/3]

QgsRelation::QgsRelation ( )

Default constructor.

Creates an invalid relation.

Definition at line 27 of file qgsrelation.cpp.

◆ ~QgsRelation()

QgsRelation::~QgsRelation ( )
default

◆ QgsRelation() [2/3]

QgsRelation::QgsRelation ( const QgsRelationContext context)

Constructor with context.

Creates an invalid relation.

Definition at line 32 of file qgsrelation.cpp.

◆ QgsRelation() [3/3]

QgsRelation::QgsRelation ( const QgsRelation other)

Copies a relation.

This makes a shallow copy, relations are implicitly shared and only duplicated when the copy is changed.

Definition at line 40 of file qgsrelation.cpp.

Member Function Documentation

◆ addFieldPair() [1/2]

void QgsRelation::addFieldPair ( const FieldPair fieldPair)

Add a field pair which is part of this relation The first element of each pair are the field names of the foreign key.

The second element of each pair are the field names of the matching primary key.

Parameters
fieldPairA pair of two strings
Note
not available in Python bindings

Definition at line 181 of file qgsrelation.cpp.

◆ addFieldPair() [2/2]

void QgsRelation::addFieldPair ( const QString &  referencingField,
const QString &  referencedField 
)

Add a field pair which is part of this relation The first element of each pair are the field names of the foreign key.

The second element of each pair are the field names of the matching primary key.

Parameters
referencingFieldThe field name on the referencing (child) layer (FK)
referencedFieldThe field name on the referenced (parent) layer (PK)

Definition at line 174 of file qgsrelation.cpp.

◆ cardinalityToDisplayString()

QString QgsRelation::cardinalityToDisplayString ( Qgis::RelationshipCardinality  cardinality)
static

Returns a user-friendly translated string representing a relationship cardinality.

Since
QGIS 3.28

Definition at line 502 of file qgsrelation.cpp.

◆ createFromXml()

QgsRelation QgsRelation::createFromXml ( const QDomNode &  node,
QgsReadWriteContext context,
const QgsRelationContext relationContext = QgsRelationContext() 
)
static

Creates a relation from an XML structure.

Used for reading .qgs projects.

Parameters
nodeThe dom node containing the relation information
contextto pass project translator
relationContexta relation context
Returns
A relation

Definition at line 53 of file qgsrelation.cpp.

◆ fieldPairs()

QList< QgsRelation::FieldPair > QgsRelation::fieldPairs ( ) const

Returns the field pairs which form this relation The first element of each pair are the field names of the foreign key.

The second element of each pair are the field names of the matching primary key.

Returns
The fields forming the relation

Definition at line 330 of file qgsrelation.cpp.

◆ generateId()

void QgsRelation::generateId ( )

Generate a (project-wide) unique id for this relation.

Since
QGIS 3.0

Definition at line 296 of file qgsrelation.cpp.

◆ getReferencedFeature()

QgsFeature QgsRelation::getReferencedFeature ( const QgsFeature feature) const

Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature.

Parameters
featureA feature from the referencing (child) layer
Returns
A request the referenced feature

Definition at line 272 of file qgsrelation.cpp.

◆ getReferencedFeatureRequest() [1/2]

QgsFeatureRequest QgsRelation::getReferencedFeatureRequest ( const QgsAttributes attributes) const

Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature.

Parameters
attributesAn attribute vector containing the foreign key
Returns
A request the referenced feature

Definition at line 239 of file qgsrelation.cpp.

◆ getReferencedFeatureRequest() [2/2]

QgsFeatureRequest QgsRelation::getReferencedFeatureRequest ( const QgsFeature feature) const

Creates a request to return the feature on the referenced (parent) layer which is referenced by the provided feature.

Parameters
featureA feature from the referencing (child) layer
Returns
A request the referenced feature

Definition at line 267 of file qgsrelation.cpp.

◆ getRelatedFeatures()

QgsFeatureIterator QgsRelation::getRelatedFeatures ( const QgsFeature feature) const

Creates an iterator which returns all the features on the referencing (child) layer which have a foreign key pointing to the provided feature.

Parameters
featureA feature from the referenced (parent) layer
Returns
An iterator with all the referenced features
See also
getRelatedFeaturesRequest()
getRelatedFeaturesFilter()

Definition at line 188 of file qgsrelation.cpp.

◆ getRelatedFeaturesFilter()

QString QgsRelation::getRelatedFeaturesFilter ( const QgsFeature feature) const

Returns a filter expression which returns all the features on the referencing (child) layer which have a foreign key pointing to the provided feature.

Parameters
featureA feature from the referenced (parent) layer
Returns
expression filter string for all the referencing features
See also
getRelatedFeatures()
getRelatedFeaturesRequest()
Since
QGIS 2.16

Definition at line 203 of file qgsrelation.cpp.

◆ getRelatedFeaturesRequest()

QgsFeatureRequest QgsRelation::getRelatedFeaturesRequest ( const QgsFeature feature) const

Creates a request to return all the features on the referencing (child) layer which have a foreign key pointing to the provided feature.

Parameters
featureA feature from the referenced (parent) layer
Returns
A request for all the referencing features
See also
getRelatedFeatures()
getRelatedFeaturesFilter()

Definition at line 193 of file qgsrelation.cpp.

◆ hasEqualDefinition()

bool QgsRelation::hasEqualDefinition ( const QgsRelation other) const

Compares the two QgsRelation, ignoring the name and the ID.

Parameters
otherThe other relation
Returns
true if they are similar
Since
QGIS 3.0

Definition at line 390 of file qgsrelation.cpp.

◆ id()

QString QgsRelation::id ( ) const

A (project-wide) unique id for this relation.

Returns
The id

Definition at line 291 of file qgsrelation.cpp.

◆ isValid()

bool QgsRelation::isValid ( ) const

Returns the validity of this relation.

Don't use the information if it's not valid. A relation is considered valid if both referenced and referencig layers are valid.

Returns
true if the relation is valid
See also
validationError()

Definition at line 358 of file qgsrelation.cpp.

◆ name()

QString QgsRelation::name ( ) const

Returns a human readable name for this relation.

Mostly used as title for the children.

See also
id()
Returns
A name

Definition at line 281 of file qgsrelation.cpp.

◆ operator=()

QgsRelation & QgsRelation::operator= ( const QgsRelation other)

Copies a relation.

This makes a shallow copy, relations are implicitly shared and only duplicated when the copy is changed.

Definition at line 46 of file qgsrelation.cpp.

◆ polymorphicRelation()

QgsPolymorphicRelation QgsRelation::polymorphicRelation ( ) const

Returns the parent polymorphic relation.

If the relation is a normal relation, an invalid polymorphic relation is returned.

Since
QGIS 3.18

Definition at line 486 of file qgsrelation.cpp.

◆ polymorphicRelationId()

QString QgsRelation::polymorphicRelationId ( ) const

Returns the parent polymorphic relation id.

If the relation is a normal relation, a null string is returned.

Since
QGIS 3.18

Definition at line 481 of file qgsrelation.cpp.

◆ referencedFields()

QgsAttributeList QgsRelation::referencedFields ( ) const

Returns a list of attributes used to form the referenced fields (most likely primary key) on the referenced (parent) layer.

Returns
A list of attributes

Definition at line 335 of file qgsrelation.cpp.

◆ referencedLayer()

QgsVectorLayer * QgsRelation::referencedLayer ( ) const

Access the referenced (parent) layer.

Returns
referenced layer

Definition at line 325 of file qgsrelation.cpp.

◆ referencedLayerId()

QString QgsRelation::referencedLayerId ( ) const

Access the referenced (parent) layer's id.

Returns
The id of the referenced layer

Definition at line 320 of file qgsrelation.cpp.

◆ referencingFields()

QgsAttributeList QgsRelation::referencingFields ( ) const

Returns a list of attributes used to form the referencing fields (foreign key) on the referencing (child) layer.

Returns
A list of attributes

Definition at line 346 of file qgsrelation.cpp.

◆ referencingLayer()

QgsVectorLayer * QgsRelation::referencingLayer ( ) const

Access the referencing (child) layer This is the layer which has the field(s) which point to another layer.

Returns
The referencing layer

Definition at line 315 of file qgsrelation.cpp.

◆ referencingLayerId()

QString QgsRelation::referencingLayerId ( ) const

Access the referencing (child) layer's id This is the layer which has the field(s) which point to another layer.

Returns
The id of the referencing layer

Definition at line 310 of file qgsrelation.cpp.

◆ resolveReferencedField()

QString QgsRelation::resolveReferencedField ( const QString &  referencingField) const

Gets the referenced field counterpart given a referencing field.

Since
QGIS 3.0

Definition at line 395 of file qgsrelation.cpp.

◆ resolveReferencingField()

QString QgsRelation::resolveReferencingField ( const QString &  referencedField) const

Gets the referencing field counterpart given a referenced field.

Since
QGIS 3.0

Definition at line 405 of file qgsrelation.cpp.

◆ setId()

void QgsRelation::setId ( const QString &  id)

Set an id for this relation.

Definition at line 137 of file qgsrelation.cpp.

◆ setName()

void QgsRelation::setName ( const QString &  name)

Set a name for this relation.

Definition at line 145 of file qgsrelation.cpp.

◆ setPolymorphicRelationId()

void QgsRelation::setPolymorphicRelationId ( const QString &  polymorphicRelationId)

Sets the parent polymorphic relation id.

Since
QGIS 3.18

Definition at line 475 of file qgsrelation.cpp.

◆ setReferencedLayer()

void QgsRelation::setReferencedLayer ( const QString &  id)

Set the referenced (parent) layer id.

This layer will be searched in the registry.

Definition at line 166 of file qgsrelation.cpp.

◆ setReferencingLayer()

void QgsRelation::setReferencingLayer ( const QString &  id)

Set the referencing (child) layer id.

This layer will be searched in the registry.

Definition at line 158 of file qgsrelation.cpp.

◆ setStrength()

void QgsRelation::setStrength ( Qgis::RelationshipStrength  strength)

Set a strength for this relation.

Since
QGIS 3.0

Definition at line 152 of file qgsrelation.cpp.

◆ strength()

Qgis::RelationshipStrength QgsRelation::strength ( ) const

Returns the relation strength as a string.

Returns
strength
Since
QGIS 3.0

Definition at line 286 of file qgsrelation.cpp.

◆ strengthToDisplayString()

QString QgsRelation::strengthToDisplayString ( Qgis::RelationshipStrength  strength)
static

Returns a user-friendly translated string representing a relationship strength.

Since
QGIS 3.28

Definition at line 518 of file qgsrelation.cpp.

◆ type()

Qgis::RelationshipType QgsRelation::type ( ) const

Returns the type of the relation.

Since
QGIS 3.18

Definition at line 494 of file qgsrelation.cpp.

◆ updateRelationStatus()

void QgsRelation::updateRelationStatus ( )

Updates the validity status of this relation.

Will be called internally whenever a member is changed.

Since
QGIS 3.6

Definition at line 415 of file qgsrelation.cpp.

◆ validationError()

QString QgsRelation::validationError ( ) const

Returns a user-friendly explanation for why the relationship is invalid.

Returns an empty string if the relationship isValid().

See also
isValid()
Since
QGIS 3.28

Definition at line 363 of file qgsrelation.cpp.

◆ writeXml()

void QgsRelation::writeXml ( QDomNode &  node,
QDomDocument &  doc 
) const

Writes a relation to an XML structure.

Used for saving .qgs projects

Parameters
nodeThe parent node in which the relation will be created
docThe document in which the relation will be saved

Definition at line 117 of file qgsrelation.cpp.

Property Documentation

◆ id

Q_GADGET QString QgsRelation::id
readwrite

Definition at line 43 of file qgsrelation.h.

◆ isValid

bool QgsRelation::isValid
read

Definition at line 43 of file qgsrelation.h.

◆ name

QString QgsRelation::name
readwrite

Definition at line 43 of file qgsrelation.h.

◆ polymorphicRelation

QgsPolymorphicRelation QgsRelation::polymorphicRelation
read

Definition at line 43 of file qgsrelation.h.

◆ polymorphicRelationId

QString QgsRelation::polymorphicRelationId
readwrite

Definition at line 43 of file qgsrelation.h.

◆ referencedLayer

QgsVectorLayer * QgsRelation::referencedLayer
read

Definition at line 43 of file qgsrelation.h.

◆ referencingLayer

QgsVectorLayer * QgsRelation::referencingLayer
read

Definition at line 43 of file qgsrelation.h.


The documentation for this class was generated from the following files: