Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :                          qgsmaplayerstore.h
       3                 :            :                          ------------------
       4                 :            :     begin                : May 2017
       5                 :            :     copyright            : (C) 2017 by Nyall Dawson
       6                 :            :     email                : nyall dot dawson at gmail dot com
       7                 :            :  ***************************************************************************/
       8                 :            : 
       9                 :            : /***************************************************************************
      10                 :            :  *                                                                         *
      11                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      12                 :            :  *   it under the terms of the GNU General Public License as published by  *
      13                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      14                 :            :  *   (at your option) any later version.                                   *
      15                 :            :  *                                                                         *
      16                 :            :  ***************************************************************************/
      17                 :            : 
      18                 :            : 
      19                 :            : #ifndef QGSMAPLAYERSTORE_H
      20                 :            : #define QGSMAPLAYERSTORE_H
      21                 :            : 
      22                 :            : #include "qgis_core.h"
      23                 :            : #include "qgis_sip.h"
      24                 :            : #include "qgsmaplayer.h"
      25                 :            : #include <QObject>
      26                 :            : 
      27                 :            : /**
      28                 :            :  * \class QgsMapLayerStore
      29                 :            :  * \ingroup core
      30                 :            :  * \brief A storage object for map layers, in which the layers are owned by the
      31                 :            :  * store and have their lifetime bound to the store.
      32                 :            :  * \since QGIS 3.0
      33                 :            : */
      34                 :            : 
      35                 :            : class CORE_EXPORT QgsMapLayerStore : public QObject
      36                 :            : {
      37                 :            :     Q_OBJECT
      38                 :            : 
      39                 :            :   public:
      40                 :            : 
      41                 :            :     /**
      42                 :            :      * Constructor for QgsMapLayerStore.
      43                 :            :      */
      44                 :            :     explicit QgsMapLayerStore( QObject *parent SIP_TRANSFERTHIS = nullptr );
      45                 :            : 
      46                 :            :     ~QgsMapLayerStore() override;
      47                 :            : 
      48                 :            :     /**
      49                 :            :      * Returns the number of layers contained in the store.
      50                 :            :      */
      51                 :            :     int count() const;
      52                 :            : 
      53                 :            :     /**
      54                 :            :      * Returns the number of valid layers contained in the store.
      55                 :            :      * \since QGIS 3.6
      56                 :            :      */
      57                 :            :     int validCount() const;
      58                 :            : 
      59                 :            : #ifdef SIP_RUN
      60                 :            : 
      61                 :            :     /**
      62                 :            :      * Returns the number of layers contained in the store.
      63                 :            :      */
      64                 :            :     int __len__() const;
      65                 :            :     % MethodCode
      66                 :            :     sipRes = sipCpp->count();
      67                 :            :     % End
      68                 :            : 
      69                 :            :     //! Ensures that bool(obj) returns TRUE (otherwise __len__() would be used)
      70                 :            :     int __bool__() const;
      71                 :            :     % MethodCode
      72                 :            :     sipRes = true;
      73                 :            :     % End
      74                 :            : #endif
      75                 :            : 
      76                 :            :     /**
      77                 :            :      * Retrieve a pointer to a layer by layer \a id.
      78                 :            :      * \param id ID of layer to retrieve
      79                 :            :      * \returns matching layer, or NULLPTR if no matching layer found
      80                 :            :      * \see mapLayersByName()
      81                 :            :      * \see mapLayers()
      82                 :            :      */
      83                 :            :     QgsMapLayer *mapLayer( const QString &id ) const;
      84                 :            : 
      85                 :            :     /**
      86                 :            :      * Retrieve a list of matching layers by layer \a name.
      87                 :            :      * \param name name of layers to match
      88                 :            :      * \returns list of matching layers
      89                 :            :      * \see mapLayer()
      90                 :            :      * \see mapLayers()
      91                 :            :      */
      92                 :            :     QList<QgsMapLayer *> mapLayersByName( const QString &name ) const;
      93                 :            : 
      94                 :            :     /**
      95                 :            :      * Returns a map of all layers by layer ID.
      96                 :            :      * \see mapLayer()
      97                 :            :      * \see mapLayersByName()
      98                 :            :      * \see layers()
      99                 :            :      */
     100                 :            :     QMap<QString, QgsMapLayer *> mapLayers() const;
     101                 :            : 
     102                 :            :     /**
     103                 :            :      * Returns a map of all valid layers by layer ID.
     104                 :            :      * \see mapLayer()
     105                 :            :      * \see mapLayersByName()
     106                 :            :      * \see layers()
     107                 :            :      * \since QGIS 3.6
     108                 :            :      */
     109                 :            :     QMap<QString, QgsMapLayer *> validMapLayers() const;
     110                 :            : 
     111                 :            : #ifndef SIP_RUN
     112                 :            : 
     113                 :            :     /**
     114                 :            :      * Returns a list of registered map layers with a specified layer type.
     115                 :            :      *
     116                 :            :      * ### Example
     117                 :            :      *
     118                 :            :      *     QVector<QgsVectorLayer*> vectorLayers = store->layers<QgsVectorLayer*>();
     119                 :            :      *
     120                 :            :      * \note not available in Python bindings
     121                 :            :      * \see mapLayers()
     122                 :            :      */
     123                 :            :     template <typename T>
     124                 :          0 :     QVector<T> layers() const
     125                 :            :     {
     126                 :          0 :       QVector<T> layers;
     127                 :          0 :       QMap<QString, QgsMapLayer *>::const_iterator layerIt = mMapLayers.constBegin();
     128                 :          0 :       for ( ; layerIt != mMapLayers.constEnd(); ++layerIt )
     129                 :            :       {
     130                 :          0 :         T tLayer = qobject_cast<T>( layerIt.value() );
     131                 :          0 :         if ( tLayer )
     132                 :            :         {
     133                 :          0 :           layers << tLayer;
     134                 :          0 :         }
     135                 :          0 :       }
     136                 :          0 :       return layers;
     137                 :          0 :     }
     138                 :            : #endif
     139                 :            : 
     140                 :            :     /**
     141                 :            :      * \brief
     142                 :            :      * Add a list of \a layers to the store. Ownership of the layers is transferred
     143                 :            :      * to the store.
     144                 :            :      *
     145                 :            :      * The layersAdded() and layerWasAdded() signals will always be emitted.
     146                 :            :      *
     147                 :            :      * \param layers A list of layer which should be added to the store.
     148                 :            :      * \param takeOwnership Ownership will be transferred to the layer store.
     149                 :            :      *                      If you specify FALSE here you have take care of deleting
     150                 :            :      *                      the layers yourself. Not available in Python.
     151                 :            :      *
     152                 :            :      *
     153                 :            :      * \note If a layer with the same id is already in the store it is not added again,
     154                 :            :      *       but if the validity of the layer has changed from FALSE to TRUE, the
     155                 :            :      *       layer data source is updated to the new one.
     156                 :            :      *
     157                 :            :      * \returns a list of the map layers that were added
     158                 :            :      *         successfully. If a layer already exists in the store,
     159                 :            :      *         it will not be part of the returned list.
     160                 :            :      *
     161                 :            :      * \see addMapLayer()
     162                 :            :      */
     163                 :            :     QList<QgsMapLayer *> addMapLayers( const QList<QgsMapLayer *> &layers SIP_TRANSFER,
     164                 :            :                                        bool takeOwnership SIP_PYARGREMOVE = true );
     165                 :            : 
     166                 :            :     /**
     167                 :            :      * \brief
     168                 :            :      * Add a \a layer to the store. Ownership of the layer is transferred to the
     169                 :            :      * store.
     170                 :            :      *
     171                 :            :      * The layersAdded() and layerWasAdded() signals will always be emitted.
     172                 :            :      * If you are adding multiple layers at once, you should use
     173                 :            :      * addMapLayers() instead.
     174                 :            :      *
     175                 :            :      * \param layer A layer to add to the store
     176                 :            :      * \param takeOwnership Ownership will be transferred to the layer store.
     177                 :            :      *                      If you specify FALSE here you have take care of deleting
     178                 :            :      *                      the layers yourself. Not available in Python.
     179                 :            :      *
     180                 :            :      * \returns NULLPTR if unable to add layer, otherwise pointer to newly added layer
     181                 :            :      *
     182                 :            :      * \see addMapLayers
     183                 :            :      *
     184                 :            :      * \note Use addMapLayers() if adding more than one layer at a time.
     185                 :            :      * \see addMapLayers()
     186                 :            :      */
     187                 :            :     QgsMapLayer *addMapLayer( QgsMapLayer *layer SIP_TRANSFER,
     188                 :            :                               bool takeOwnership SIP_PYARGREMOVE = true );
     189                 :            : 
     190                 :            :     /**
     191                 :            :      * \brief
     192                 :            :      * Remove a set of layers from the store by layer ID.
     193                 :            :      *
     194                 :            :      * The specified layers will be removed from the store.
     195                 :            :      * These layers will also be deleted.
     196                 :            :      *
     197                 :            :      * \param layerIds list of IDs of the layers to remove
     198                 :            :      *
     199                 :            :      * \see takeMapLayer()
     200                 :            :      * \see removeMapLayer()
     201                 :            :      * \see removeAllMapLayers()
     202                 :            :      * \note available in Python bindings as removeMapLayersById.
     203                 :            :      */
     204                 :            :     void removeMapLayers( const QStringList &layerIds ) SIP_PYNAME( removeMapLayersById );
     205                 :            : 
     206                 :            :     /**
     207                 :            :      * \brief
     208                 :            :      * Remove a set of \a layers from the store.
     209                 :            :      *
     210                 :            :      * The specified layers will be removed from the store.
     211                 :            :      * These layers will also be deleted.
     212                 :            :      *
     213                 :            :      * \param layers A list of layers to remove. NULLPTR values are ignored.
     214                 :            :      *
     215                 :            :      * \see takeMapLayer()
     216                 :            :      * \see removeMapLayer()
     217                 :            :      * \see removeAllMapLayers()
     218                 :            :      */
     219                 :            :     void removeMapLayers( const QList<QgsMapLayer *> &layers );
     220                 :            : 
     221                 :            :     /**
     222                 :            :      * \brief
     223                 :            :      * Remove a layer from the store by layer \a id.
     224                 :            :      *
     225                 :            :      * The specified layer will be removed from the store. The layer will also be deleted.
     226                 :            :      *
     227                 :            :      * \param id ID of the layer to remove
     228                 :            :      *
     229                 :            :      * \see takeMapLayer()
     230                 :            :      * \see removeMapLayers()
     231                 :            :      * \see removeAllMapLayers()
     232                 :            :      */
     233                 :            :     void removeMapLayer( const QString &id );
     234                 :            : 
     235                 :            :     /**
     236                 :            :      * \brief
     237                 :            :      * Remove a \a layer from the store.
     238                 :            :      *
     239                 :            :      * The specified layer will be removed from the store. The layer will also be deleted.
     240                 :            :      *
     241                 :            :      * \param layer The layer to remove. NULLPTR values are ignored.
     242                 :            :      *
     243                 :            :      * \see takeMapLayer()
     244                 :            :      * \see removeMapLayers()
     245                 :            :      * \see removeAllMapLayers()
     246                 :            :      */
     247                 :            :     void removeMapLayer( QgsMapLayer *layer );
     248                 :            : 
     249                 :            :     /**
     250                 :            :      * Takes a \a layer from the store. If the layer was owned by the store, the
     251                 :            :      * layer will be returned without deleting it. The caller takes ownership of
     252                 :            :      * the layer and is responsible for deleting it.
     253                 :            :      * \see removeMapLayer()
     254                 :            :      */
     255                 :            :     QgsMapLayer *takeMapLayer( QgsMapLayer *layer ) SIP_TRANSFERBACK;
     256                 :            : 
     257                 :            :     /**
     258                 :            :      * Removes all registered layers. These layers will also be deleted.
     259                 :            :      *
     260                 :            :      * \note Calling this method will cause the removeAll() signal to
     261                 :            :      * be emitted.
     262                 :            :      * \see removeMapLayer()
     263                 :            :      * \see removeMapLayers()
     264                 :            :      */
     265                 :            :     void removeAllMapLayers();
     266                 :            : 
     267                 :            :     /**
     268                 :            :      * Transfers all the map layers contained within another map layer store and adds
     269                 :            :      * them to this store.
     270                 :            :      * Note that \a other and this store must have the same thread affinity.
     271                 :            :      */
     272                 :            :     void transferLayersFromStore( QgsMapLayerStore *other );
     273                 :            : 
     274                 :            :   signals:
     275                 :            : 
     276                 :            :     /**
     277                 :            :      * Emitted when one or more layers are about to be removed from the store.
     278                 :            :      *
     279                 :            :      * \param layerIds A list of IDs for the layers which are to be removed.
     280                 :            :      * \see layerWillBeRemoved()
     281                 :            :      * \see layersRemoved()
     282                 :            :      */
     283                 :            :     void layersWillBeRemoved( const QStringList &layerIds );
     284                 :            : 
     285                 :            :     /**
     286                 :            :      * Emitted when one or more layers are about to be removed from the store.
     287                 :            :      *
     288                 :            :      * \param layers A list of layers which are to be removed.
     289                 :            :      * \see layerWillBeRemoved()
     290                 :            :      * \see layersRemoved()
     291                 :            :      */
     292                 :            :     void layersWillBeRemoved( const QList<QgsMapLayer *> &layers );
     293                 :            : 
     294                 :            :     /**
     295                 :            :      * Emitted when a layer is about to be removed from the store.
     296                 :            :      *
     297                 :            :      * \param layerId The ID of the layer to be removed.
     298                 :            :      *
     299                 :            :      * \note Consider using layersWillBeRemoved() instead.
     300                 :            :      * \see layersWillBeRemoved()
     301                 :            :      * \see layerRemoved()
     302                 :            :      */
     303                 :            :     void layerWillBeRemoved( const QString &layerId );
     304                 :            : 
     305                 :            :     /**
     306                 :            :      * Emitted when a layer is about to be removed from the store.
     307                 :            :      *
     308                 :            :      * \param layer The layer to be removed.
     309                 :            :      *
     310                 :            :      * \note Consider using layersWillBeRemoved() instead.
     311                 :            :      * \see layersWillBeRemoved()
     312                 :            :      * \see layerRemoved()
     313                 :            :      */
     314                 :            :     void layerWillBeRemoved( QgsMapLayer *layer );
     315                 :            : 
     316                 :            :     /**
     317                 :            :      * Emitted after one or more layers were removed from the store.
     318                 :            :      *
     319                 :            :      * \param layerIds  A list of IDs of the layers which were removed.
     320                 :            :      * \see layersWillBeRemoved()
     321                 :            :      */
     322                 :            :     void layersRemoved( const QStringList &layerIds );
     323                 :            : 
     324                 :            :     /**
     325                 :            :      * Emitted after a layer was removed from the store.
     326                 :            :      *
     327                 :            :      * \param layerId The ID of the layer removed.
     328                 :            :      *
     329                 :            :      * \note Consider using layersRemoved() instead
     330                 :            :      * \see layerWillBeRemoved()
     331                 :            :      */
     332                 :            :     void layerRemoved( const QString &layerId );
     333                 :            : 
     334                 :            :     /**
     335                 :            :      * Emitted when all layers are removed, before layersWillBeRemoved() and
     336                 :            :      * layerWillBeRemoved() signals are emitted. The layersWillBeRemoved() and
     337                 :            :      * layerWillBeRemoved() signals will still be emitted following this signal.
     338                 :            :      * You can use this signal to do easy (and fast) cleanup.
     339                 :            :      */
     340                 :            :     void allLayersRemoved();
     341                 :            : 
     342                 :            :     /**
     343                 :            :      * Emitted when one or more layers were added to the store.
     344                 :            :      *
     345                 :            :      * \param layers List of layers which have been added.
     346                 :            :      *
     347                 :            :      * \see layerWasAdded()
     348                 :            :      */
     349                 :            :     void layersAdded( const QList<QgsMapLayer *> &layers );
     350                 :            : 
     351                 :            :     /**
     352                 :            :      * Emitted when a \a layer was added to the store.
     353                 :            :      *
     354                 :            :      * \note Consider using layersAdded() instead
     355                 :            :      * \see layersAdded()
     356                 :            :      */
     357                 :            :     void layerWasAdded( QgsMapLayer *layer );
     358                 :            : 
     359                 :            :   private slots:
     360                 :            : 
     361                 :            :     void onMapLayerDeleted( QObject *obj );
     362                 :            : 
     363                 :            :   private:
     364                 :            : 
     365                 :            :     QMap<QString, QgsMapLayer *> mMapLayers;
     366                 :            : 
     367                 :            : };
     368                 :            : 
     369                 :            : #endif //QGSMAPLAYERSTORE_H