Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :     qgsrelation.h
       3                 :            :      --------------------------------------
       4                 :            :     Date                 : 29.4.2013
       5                 :            :     Copyright            : (C) 2013 Matthias Kuhn
       6                 :            :     Email                : matthias at opengis dot ch
       7                 :            :  ***************************************************************************
       8                 :            :  *                                                                         *
       9                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      10                 :            :  *   it under the terms of the GNU General Public License as published by  *
      11                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      12                 :            :  *   (at your option) any later version.                                   *
      13                 :            :  *                                                                         *
      14                 :            :  ***************************************************************************/
      15                 :            : 
      16                 :            : #ifndef QGSRELATION_H
      17                 :            : #define QGSRELATION_H
      18                 :            : 
      19                 :            : #include <QList>
      20                 :            : #include <QDomNode>
      21                 :            : #include <QPair>
      22                 :            : 
      23                 :            : #include "qgis_core.h"
      24                 :            : #include "qgsfields.h"
      25                 :            : #include "qgsreadwritecontext.h"
      26                 :            : #include "qgsrelationcontext.h"
      27                 :            : 
      28                 :            : #include "qgis_sip.h"
      29                 :            : 
      30                 :            : class QgsFeatureIterator;
      31                 :            : class QgsFeature;
      32                 :            : class QgsFeatureRequest;
      33                 :            : class QgsAttributes;
      34                 :            : class QgsVectorLayer;
      35                 :            : class QgsRelationPrivate;
      36                 :            : class QgsPolymorphicRelation;
      37                 :            : 
      38                 :            : /**
      39                 :            :  * \ingroup core
      40                 :            :  * \class QgsRelation
      41                 :            :  */
      42                 :            : class CORE_EXPORT QgsRelation
      43                 :            : {
      44                 :            :     Q_GADGET
      45                 :            : 
      46                 :            :     Q_PROPERTY( QString id READ id WRITE setId )
      47                 :            :     Q_PROPERTY( QgsVectorLayer *referencingLayer READ referencingLayer )
      48                 :            :     Q_PROPERTY( QgsVectorLayer *referencedLayer READ referencedLayer )
      49                 :            :     Q_PROPERTY( QString name READ name WRITE setName )
      50                 :            :     Q_PROPERTY( bool isValid READ isValid )
      51                 :            :     Q_PROPERTY( QString polymorphicRelationId READ polymorphicRelationId WRITE setPolymorphicRelationId )
      52                 :            :     Q_PROPERTY( QgsPolymorphicRelation polymorphicRelation READ polymorphicRelation )
      53                 :            : 
      54                 :            :   public:
      55                 :            : 
      56                 :            :     /**
      57                 :            :      * Enum holding the relations type
      58                 :            :      */
      59                 :            :     enum RelationType
      60                 :            :     {
      61                 :            :       Normal, //!< A normal relation
      62                 :            :       Generated, //!< A generated relation is a child of a polymorphic relation
      63                 :            :     };
      64                 :            :     Q_ENUM( RelationType )
      65                 :            : 
      66                 :            :     /**
      67                 :            :     * enum for the relation strength
      68                 :            :     * Association, Composition
      69                 :            :     */
      70                 :            :     enum RelationStrength
      71                 :            :     {
      72                 :            :       Association, //!< Loose relation, related elements are not part of the parent and a parent copy will not copy any children.
      73                 :            :       Composition  //!< Fix relation, related elements are part of the parent and a parent copy will copy any children or delete of parent will delete children
      74                 :            :     };
      75                 :          0 :     Q_ENUM( RelationStrength )
      76                 :            : 
      77                 :            : #ifndef SIP_RUN
      78                 :            : 
      79                 :            :     /**
      80                 :            :      * \ingroup core
      81                 :            :      * \brief Defines a relation between matching fields of the two involved tables of a relation.
      82                 :            :      *
      83                 :            :      * Often, a relation is only defined by just one FieldPair with the name of the foreign key
      84                 :            :      * column of the referencing (child) table as first element and the name of the primary key column
      85                 :            :      * of the referenced (parent) table as the second element.
      86                 :            :      * \note not available in Python bindings
      87                 :            :      */
      88                 :          0 :     class FieldPair : public QPair< QString, QString >
      89                 :            :     {
      90                 :            :       public:
      91                 :            :         //! Default constructor: NULL strings
      92                 :            :         FieldPair() = default;
      93                 :            : 
      94                 :            :         //! Constructor which takes two fields
      95                 :          0 :         FieldPair( const QString &referencingField, const QString &referencedField )
      96                 :          0 :           : QPair< QString, QString >( referencingField, referencedField ) {}
      97                 :            : 
      98                 :            :         //! Gets the name of the referencing (child) field
      99                 :          0 :         QString referencingField() const { return first; }
     100                 :            :         //! Gets the name of the referenced (parent) field
     101                 :          0 :         QString referencedField() const { return second; }
     102                 :            : 
     103                 :          0 :         bool operator==( const FieldPair &other ) const { return first == other.first && second == other.second; }
     104                 :            :     };
     105                 :            : #endif
     106                 :            : 
     107                 :            :     /**
     108                 :            :      * Default constructor. Creates an invalid relation.
     109                 :            :      */
     110                 :            :     QgsRelation();
     111                 :            :     ~QgsRelation();
     112                 :            : 
     113                 :            :     /**
     114                 :            :      * Constructor with context. Creates an invalid relation.
     115                 :            :      */
     116                 :            :     QgsRelation( const QgsRelationContext &context );
     117                 :            : 
     118                 :            :     /**
     119                 :            :      * Copies a relation.
     120                 :            :      * This makes a shallow copy, relations are implicitly shared and only duplicated when the copy is
     121                 :            :      * changed.
     122                 :            :      */
     123                 :            :     QgsRelation( const QgsRelation &other );
     124                 :            : 
     125                 :            :     /**
     126                 :            :      * Copies a relation.
     127                 :            :      * This makes a shallow copy, relations are implicitly shared and only duplicated when the copy is
     128                 :            :      * changed.
     129                 :            :      */
     130                 :            :     QgsRelation &operator=( const QgsRelation &other );
     131                 :            : 
     132                 :            :     /**
     133                 :            :      * Creates a relation from an XML structure. Used for reading .qgs projects.
     134                 :            :      *
     135                 :            :      * \param node The dom node containing the relation information
     136                 :            :      * \param context to pass project translator
     137                 :            :      * \param relationContext a relation context
     138                 :            :      *
     139                 :            :      * \returns A relation
     140                 :            :      */
     141                 :            :     static QgsRelation createFromXml( const QDomNode &node, QgsReadWriteContext &context, const QgsRelationContext &relationContext = QgsRelationContext() );
     142                 :            : 
     143                 :            :     /**
     144                 :            :      * Writes a relation to an XML structure. Used for saving .qgs projects
     145                 :            :      *
     146                 :            :      * \param node The parent node in which the relation will be created
     147                 :            :      * \param doc  The document in which the relation will be saved
     148                 :            :      */
     149                 :            :     void writeXml( QDomNode &node, QDomDocument &doc ) const;
     150                 :            : 
     151                 :            :     /**
     152                 :            :      * Set an id for this relation
     153                 :            :      */
     154                 :            :     void setId( const QString &id );
     155                 :            : 
     156                 :            :     /**
     157                 :            :      * Set a name for this relation
     158                 :            :      */
     159                 :            :     void setName( const QString &name );
     160                 :            : 
     161                 :            :     /**
     162                 :            :      * Set a strength for this relation
     163                 :            :      * \since QGIS 3.0
     164                 :            :      */
     165                 :            :     void setStrength( RelationStrength strength );
     166                 :            : 
     167                 :            :     /**
     168                 :            :      * Set the referencing (child) layer id. This layer will be searched in the registry.
     169                 :            :      */
     170                 :            :     void setReferencingLayer( const QString &id );
     171                 :            : 
     172                 :            :     /**
     173                 :            :      * Set the referenced (parent) layer id. This layer will be searched in the registry.
     174                 :            :      */
     175                 :            :     void setReferencedLayer( const QString &id );
     176                 :            : 
     177                 :            :     /**
     178                 :            :      * Add a field pair which is part of this relation
     179                 :            :      * The first element of each pair are the field names of the foreign key.
     180                 :            :      * The second element of each pair are the field names of the matching primary key.
     181                 :            :      *
     182                 :            :      * \param referencingField  The field name on the referencing (child) layer (FK)
     183                 :            :      * \param referencedField   The field name on the referenced (parent) layer  (PK)
     184                 :            :      */
     185                 :            :     void addFieldPair( const QString &referencingField, const QString &referencedField );
     186                 :            : 
     187                 :            :     /**
     188                 :            :      * Add a field pair which is part of this relation
     189                 :            :      * The first element of each pair are the field names of the foreign key.
     190                 :            :      * The second element of each pair are the field names of the matching primary key.
     191                 :            :      *
     192                 :            :      * \param fieldPair A pair of two strings
     193                 :            :      * \note not available in Python bindings
     194                 :            :      */
     195                 :            :     void addFieldPair( const FieldPair &fieldPair ) SIP_SKIP;
     196                 :            : 
     197                 :            :     /**
     198                 :            :      * Creates an iterator which returns all the features on the referencing (child) layer
     199                 :            :      * which have a foreign key pointing to the provided feature.
     200                 :            :      *
     201                 :            :      * \param feature A feature from the referenced (parent) layer
     202                 :            :      *
     203                 :            :      * \returns An iterator with all the referenced features
     204                 :            :      * \see getRelatedFeaturesRequest()
     205                 :            :      * \see getRelatedFeaturesFilter()
     206                 :            :      */
     207                 :            :     QgsFeatureIterator getRelatedFeatures( const QgsFeature &feature ) const;
     208                 :            : 
     209                 :            :     /**
     210                 :            :      * Creates a request to return all the features on the referencing (child) layer
     211                 :            :      * which have a foreign key pointing to the provided feature.
     212                 :            :      *
     213                 :            :      * \param feature A feature from the referenced (parent) layer
     214                 :            :      *
     215                 :            :      * \returns A request for all the referencing features
     216                 :            :      * \see getRelatedFeatures()
     217                 :            :      * \see getRelatedFeaturesFilter()
     218                 :            :      */
     219                 :            :     QgsFeatureRequest getRelatedFeaturesRequest( const QgsFeature &feature ) const;
     220                 :            : 
     221                 :            :     /**
     222                 :            :      * Returns a filter expression which returns all the features on the referencing (child) layer
     223                 :            :      * which have a foreign key pointing to the provided feature.
     224                 :            :      * \param feature A feature from the referenced (parent) layer
     225                 :            :      * \returns expression filter string for all the referencing features
     226                 :            :      * \see getRelatedFeatures()
     227                 :            :      * \see getRelatedFeaturesRequest()
     228                 :            :      * \since QGIS 2.16
     229                 :            :      */
     230                 :            :     QString getRelatedFeaturesFilter( const QgsFeature &feature ) const;
     231                 :            : 
     232                 :            :     /**
     233                 :            :      * Creates a request to return the feature on the referenced (parent) layer
     234                 :            :      * which is referenced by the provided feature.
     235                 :            :      *
     236                 :            :      * \param attributes An attribute vector containing the foreign key
     237                 :            :      *
     238                 :            :      * \returns A request the referenced feature
     239                 :            :      */
     240                 :            :     QgsFeatureRequest getReferencedFeatureRequest( const QgsAttributes &attributes ) const;
     241                 :            : 
     242                 :            :     /**
     243                 :            :      * Creates a request to return the feature on the referenced (parent) layer
     244                 :            :      * which is referenced by the provided feature.
     245                 :            :      *
     246                 :            :      * \param feature A feature from the referencing (child) layer
     247                 :            :      *
     248                 :            :      * \returns A request the referenced feature
     249                 :            :      */
     250                 :            :     QgsFeatureRequest getReferencedFeatureRequest( const QgsFeature &feature ) const;
     251                 :            : 
     252                 :            :     /**
     253                 :            :      * Creates a request to return the feature on the referenced (parent) layer
     254                 :            :      * which is referenced by the provided feature.
     255                 :            :      *
     256                 :            :      * \param feature A feature from the referencing (child) layer
     257                 :            :      *
     258                 :            :      * \returns A request the referenced feature
     259                 :            :      */
     260                 :            :     QgsFeature getReferencedFeature( const QgsFeature &feature ) const;
     261                 :            : 
     262                 :            :     /**
     263                 :            :      * Returns a human readable name for this relation. Mostly used as title for the children.
     264                 :            :      *
     265                 :            :      * \see id()
     266                 :            :      *
     267                 :            :      * \returns A name
     268                 :            :      */
     269                 :            :     QString name() const;
     270                 :            : 
     271                 :            :     /**
     272                 :            :      * Returns the relation strength as a string
     273                 :            :      *
     274                 :            :      * \returns strength
     275                 :            :      * \since QGIS 3.0
     276                 :            :      */
     277                 :            :     RelationStrength strength() const;
     278                 :            : 
     279                 :            :     /**
     280                 :            :      * A (project-wide) unique id for this relation
     281                 :            :      *
     282                 :            :      * \returns The id
     283                 :            :      */
     284                 :            :     QString id() const;
     285                 :            : 
     286                 :            :     /**
     287                 :            :      * Generate a (project-wide) unique id for this relation
     288                 :            :      * \since QGIS 3.0
     289                 :            :      */
     290                 :            :     void generateId();
     291                 :            : 
     292                 :            :     /**
     293                 :            :      * Access the referencing (child) layer's id
     294                 :            :      * This is the layer which has the field(s) which point to another layer
     295                 :            :      *
     296                 :            :      * \returns The id of the referencing layer
     297                 :            :      */
     298                 :            :     QString referencingLayerId() const;
     299                 :            : 
     300                 :            :     /**
     301                 :            :      * Access the referencing (child) layer
     302                 :            :      * This is the layer which has the field(s) which point to another layer
     303                 :            :      *
     304                 :            :      * \returns The referencing layer
     305                 :            :      */
     306                 :            :     QgsVectorLayer *referencingLayer() const;
     307                 :            : 
     308                 :            :     /**
     309                 :            :      * Access the referenced (parent) layer's id
     310                 :            :      *
     311                 :            :      * \returns The id of the referenced layer
     312                 :            :      */
     313                 :            :     QString referencedLayerId() const;
     314                 :            : 
     315                 :            :     /**
     316                 :            :      * Access the referenced (parent) layer
     317                 :            :      *
     318                 :            :      * \returns referenced layer
     319                 :            :      */
     320                 :            :     QgsVectorLayer *referencedLayer() const;
     321                 :            : 
     322                 :            :     /**
     323                 :            :      * Returns the field pairs which form this relation
     324                 :            :      * The first element of each pair are the field names of the foreign key.
     325                 :            :      * The second element of each pair are the field names of the matching primary key.
     326                 :            :      *
     327                 :            :      * \returns The fields forming the relation
     328                 :            :      */
     329                 :            : #ifndef SIP_RUN
     330                 :            :     QList< QgsRelation::FieldPair > fieldPairs() const;
     331                 :            : #else
     332                 :            :     QMap< QString, QString > fieldPairs() const;
     333                 :            :     % MethodCode
     334                 :            :     const QList< QgsRelation::FieldPair > &pairs = sipCpp->fieldPairs();
     335                 :            :     sipRes = new QMap< QString, QString >();
     336                 :            :     for ( const QgsRelation::FieldPair &pair : pairs )
     337                 :            :     {
     338                 :            :       sipRes->insert( pair.first, pair.second );
     339                 :            :     }
     340                 :            :     % End
     341                 :            : #endif
     342                 :            : 
     343                 :            :     /**
     344                 :            :      * Returns a list of attributes used to form the referenced fields
     345                 :            :      * (most likely primary key) on the referenced (parent) layer.
     346                 :            :      *
     347                 :            :      * \returns A list of attributes
     348                 :            :      */
     349                 :            :     QgsAttributeList referencedFields() const;
     350                 :            : 
     351                 :            :     /**
     352                 :            :      * Returns a list of attributes used to form the referencing fields
     353                 :            :      * (foreign key) on the referencing (child) layer.
     354                 :            :      *
     355                 :            :      * \returns A list of attributes
     356                 :            :      */
     357                 :            :     QgsAttributeList referencingFields() const;
     358                 :            : 
     359                 :            :     /**
     360                 :            :      * Returns the validity of this relation. Don't use the information if it's not valid.
     361                 :            :      * A relation is considered valid if both referenced and referencig layers are valid.
     362                 :            :      *
     363                 :            :      * \returns TRUE if the relation is valid
     364                 :            :      */
     365                 :            :     bool isValid() const;
     366                 :            : 
     367                 :            :     /**
     368                 :            :      * Compares the two QgsRelation, ignoring the name and the ID.
     369                 :            :      *
     370                 :            :      * \param other The other relation
     371                 :            :      * \returns TRUE if they are similar
     372                 :            :      * \since QGIS 3.0
     373                 :            :      */
     374                 :            :     bool hasEqualDefinition( const QgsRelation &other ) const;
     375                 :            : 
     376                 :            :     /**
     377                 :            :      * Gets the referenced field counterpart given a referencing field.
     378                 :            :      *
     379                 :            :      * \since QGIS 3.0
     380                 :            :      */
     381                 :            :     Q_INVOKABLE QString resolveReferencedField( const QString &referencingField ) const;
     382                 :            : 
     383                 :            :     /**
     384                 :            :      * Gets the referencing field counterpart given a referenced field.
     385                 :            :      *
     386                 :            :      * \since QGIS 3.0
     387                 :            :      */
     388                 :            :     Q_INVOKABLE QString resolveReferencingField( const QString &referencedField ) const;
     389                 :            : 
     390                 :            :     /**
     391                 :            :      * Updates the validity status of this relation.
     392                 :            :      * Will be called internally whenever a member is changed.
     393                 :            :      *
     394                 :            :      * \since QGIS 3.6
     395                 :            :      */
     396                 :            :     void updateRelationStatus();
     397                 :            : 
     398                 :            :     /**
     399                 :            :      * Sets the parent polymorphic relation id.
     400                 :            :      * \since QGIS 3.18
     401                 :            :      */
     402                 :            :     void setPolymorphicRelationId( const QString &polymorphicRelationId );
     403                 :            : 
     404                 :            :     /**
     405                 :            :      * Returns the parent polymorphic relation id. If the relation is a normal relation, a null string is returned.
     406                 :            :      * \since QGIS 3.18
     407                 :            :      */
     408                 :            :     QString polymorphicRelationId() const;
     409                 :            : 
     410                 :            :     /**
     411                 :            :      * Returns the parent polymorphic relation. If the relation is a normal relation, an invalid polymorphic relation is returned.
     412                 :            :      * \since QGIS 3.18
     413                 :            :      */
     414                 :            :     QgsPolymorphicRelation polymorphicRelation() const;
     415                 :            : 
     416                 :            :     /**
     417                 :            :      * Returns the type of the relation
     418                 :            :      * \since QGIS 3.18
     419                 :            :      */
     420                 :            :     RelationType type() const;
     421                 :            : 
     422                 :            :   private:
     423                 :            : 
     424                 :            :     mutable QExplicitlySharedDataPointer<QgsRelationPrivate> d;
     425                 :            : 
     426                 :            :     QgsRelationContext mContext;
     427                 :            : };
     428                 :            : 
     429                 :            : // Register QgsRelation for usage with QVariant
     430                 :            : Q_DECLARE_METATYPE( QgsRelation )
     431                 :            : Q_DECLARE_METATYPE( QgsRelation::RelationStrength )
     432                 :            : 
     433                 :            : #endif // QGSRELATION_H