Skip to content

Commit

Permalink
Cleanups to QgsMapLayerRegistry
Browse files Browse the repository at this point in the history 
- const correctness
- improve and clarify docs, remove outdated notes
- add some QGIS 3.0 todos
  • Loading branch information
@nyalldawson
nyalldawson committed Jul 4, 2016
1 parent 15c2f0a commit 6b3cb24
Show file tree
Hide file tree
Showing 3 changed files with 281 additions and 190 deletions.
216 changes: 133 additions & 83 deletions python/core/qgsmaplayerregistry.sip
View file
@@ -1,6 +1,7 @@
/** \ingroup core
* \class QgsMapLayerRegistry
* This class tracks map layers that are currently loaded and provides
* a means to fetch a pointer to a map layer and delete it.
* various methods to retrieve matching layers from the registry.
*/
class QgsMapLayerRegistry : QObject
{
Expand All @@ -12,60 +13,78 @@ class QgsMapLayerRegistry : QObject
//! Returns the instance pointer, creating the object on the first call
static QgsMapLayerRegistry * instance();

//! Return the number of registered layers.
int count();

~QgsMapLayerRegistry();

//! Retrieve a pointer to a loaded layer by id
QgsMapLayer *mapLayer( const QString& theLayerId );
//! Returns the number of registered layers.
int count() const;

//! Retrieve a pointer to a loaded layer by name
QList<QgsMapLayer *> mapLayersByName( const QString& layerName );
/** Retrieve a pointer to a registered layer by layer ID.
* @param theLayerId ID of layer to retrieve
* @returns matching layer, or nullptr if no matching layer found
* @see mapLayersByName()
* @see mapLayers()
*/
//TODO QGIS 3.0 - rename theLayerId to layerId
QgsMapLayer* mapLayer( const QString& theLayerId ) const;

//! Retrieve the mapLayers collection (mainly intended for use by projection)
const QMap<QString, QgsMapLayer*> & mapLayers();
/** Retrieve a list of matching registered layers by layer name.
* @param layerName name of layers to match
* @returns list of matching layers
* @see mapLayer()
* @see mapLayers()
*/
QList<QgsMapLayer *> mapLayersByName( const QString& layerName ) const;

/** Returns a list of all registered layers.
* @see mapLayer()
* @see mapLayersByName()
* @see layers()
*/
QMap<QString, QgsMapLayer*> mapLayers() const;

/**
* @brief
* Add a list of layers to the map of loaded layers
* Add a list of layers to the map of loaded layers.
*
* The layersAdded() and layersWasAdded() signals will be emitted in any case.
* The legendLayersAdded() signal only if addToLegend is true.
* The layersAdded() and layerWasAdded() signals will always be emitted.
* The legendLayersAdded() signal is emitted only if addToLegend is true.
*
* @param theMapLayers A list of layer which should be added to the registry
* @param addToLegend If true (by default), the layers will be added to the
* legend and to the main canvas. If you have a private
* layer, you can set this parameter to false to hide it.
* layer you can set this parameter to false to hide it.
* @param takeOwnership Ownership will be transferred to the layer registry.
* If you specify false here, you have take care of deleting
* If you specify false here you have take care of deleting
* the layers yourself. Not available in python.
*
* @return QList<QgsMapLayer *> - a list of the map layers that were added
* @return a list of the map layers that were added
* successfully. If a layer is invalid, or already exists in the registry,
* it will not be part of the returned QList.
*
* @note As a side-effect QgsProject is made dirty.
* @note takeOwnership not available in python binding - always takes ownership
* @note takeOwnership is not available in the Python bindings - the registry will always
* take ownership
* @note added in QGIS 1.8
* @see addMapLayer()
*/
QList<QgsMapLayer *> addMapLayers( const QList<QgsMapLayer *>& theMapLayers /Transfer/,
bool addToLegend = true );

/**
* @brief
* Add a layer to the map of loaded layers
* Add a layer to the map of loaded layers.
*
* The layersAdded() and layersWasAdded() signals will be emitted in any case.
* The legendLayersAdded() signal only if addToLegend is true.
* The layersAdded() and layerWasAdded() signals will always be emitted.
* The legendLayersAdded() signal is emitted only if addToLegend is true.
* If you are adding multiple layers at once, you should use
* {@link addMapLayers()} instead.
* addMapLayers() instead.
*
* @param theMapLayer A layer to add to the registry
* @param theMapLayer A layer to add to the registry
* @param addToLegend If true (by default), the layer will be added to the
* legend and to the main canvas. If you have a private
* you can set this parameter to false to hide it.
* layer you can set this parameter to false to hide it.
* @param takeOwnership Ownership will be transferred to the layer registry.
* If you specify false here, you have take care of deleting
* If you specify false here you have take care of deleting
* the layer yourself. Not available in python.
*
* @return nullptr if unable to add layer, otherwise pointer to newly added layer
Expand All @@ -74,75 +93,84 @@ class QgsMapLayerRegistry : QObject
*
* @note As a side-effect QgsProject is made dirty.
* @note Use addMapLayers if adding more than one layer at a time
* @note takeOwner not available in python binding - always takes ownership
* @note takeOwnership is not available in the Python bindings - the registry will always
* take ownership
* @see addMapLayers()
*/
QgsMapLayer* addMapLayer( QgsMapLayer * theMapLayer /Transfer/, bool addToLegend = true );

/**
* @brief
* Remove a set of layers from the registry
* Remove a set of layers from the registry by layer ID.
*
* Any canvases using the affected layers will need to remove them
* The specified layers will be removed from the registry. If the registry has ownership
* of any layers these layers will also be deleted.
*
* The layers being removed are deleted as well as the registry
* table entries.
* @param theLayerIds list of IDs of the layers to remove
*
* @param theLayerIds The ids of the layers to remove
*
* @note As a side-effect QgsProject is made dirty.
* @note As a side-effect the QgsProject instance is marked dirty.
* @note added in QGIS 1.8
* @see removeMapLayer()
* @see removeAllMapLayers()
*/
// TODO QGIS 3.0 - rename theLayerIds to layerIds
void removeMapLayers( const QStringList& theLayerIds );

/**
* @brief
* Remove a set of layers from the registry
* Remove a set of layers from the registry.
*
* Any canvases using the affected layers will need to remove them
* The specified layers will be removed from the registry. If the registry has ownership
* of any layers these layers will also be deleted.
*
* The layers being removed are deleted as well as the registry
* table entries.
* @param layers A list of layers to remove. Null pointers are ignored.
*
* @param layers The layers to remove. Null pointers are ignored
*
* @note As a side-effect QgsProject is made dirty.
* @note As a side-effect the QgsProject instance is marked dirty.
* @see removeMapLayer()
* @see removeAllMapLayers()
*/
void removeMapLayers( const QList<QgsMapLayer*>& layers );

/**
* @brief
* Remove a layer from qgis
* Remove a layer from the registry by layer ID.
*
* Any canvases using the affected layers will need to remove them
* The specified layer will be removed from the registry. If the registry has ownership
* of the layer then it will also be deleted.
*
* The layer being removed is deleted as well as the registry
* table entry.
* @param theLayerId ID of the layer to remove
*
* @param theLayerId The id of the layer to remove
*
* @note As a side-effect QgsProject is made dirty.
* @note As a side-effect the QgsProject instance is marked dirty.
* @see removeMapLayers()
* @see removeAllMapLayers()
*/
// TODO QGIS 3.0 - rename theLayerId to layerId
void removeMapLayer( const QString& theLayerId );

/**
* @brief
* Remove a layer from qgis
* Remove a layer from the registry.
*
* Any canvases using the affected layers will need to remove them
* The specified layer will be removed from the registry. If the registry has ownership
* of the layer then it will also be deleted.
*
* The layer being removed is deleted as well as the registry
* table entry.
* @param layer The layer to remove. Null pointers are ignored.
*
* @param layer The layer to remove. Nothing happens if the pointer is null
*
* @note As a side-effect QgsProject is made dirty.
* @note As a side-effect the QgsProject instance is marked dirty.
* @see removeMapLayers()
* @see removeAllMapLayers()
*/
void removeMapLayer( QgsMapLayer* layer );

/**
* Remove all registered layers
*
* @note As a side-effect QgsProject is made dirty.
* @note The layers are deleted as the registry is cleared!
* Removes all registered layers. If the registry has ownership
* of any layers these layers will also be deleted.
*
* @note As a side-effect the QgsProject instance is marked dirty.
* @note Calling this method will cause the removeAll() signal to
* be emitted.
* @see removeMapLayer()
* @see removeMapLayers()
*/
void removeAllMapLayers();

Expand All @@ -156,101 +184,123 @@ class QgsMapLayerRegistry : QObject
void clearAllLayerCaches() /Deprecated/;

/**
* Reload all provider data caches (currently used for WFS and WMS providers)
* Reload all registered layer's provider data caches, synchronising the layer
* with any changes in the datasource.
* @see QgsMapLayer::reload()
*/
void reloadAllLayers();

signals:

/**
* Emitted when one or more layers are removed from the registry
* Emitted when one or more layers are about to be removed from the registry.
*
* @param theLayerIds A list of ids of the layers which are removed.
* @param theLayerIds A list of IDs for the layers which are to be removed.
* @see layerWillBeRemoved()
* @see layersRemoved()
*/
// TODO QGIS 3.0 - rename theLayerIds to layerIds
void layersWillBeRemoved( const QStringList& theLayerIds );

/**
* Emitted when one or more layers are removed from the registry
* Emitted when one or more layers are about to be removed from the registry.
*
* @param layers A list of layers which are removed.
* @param layers A list of layers which are to be removed.
* @see layerWillBeRemoved()
* @see layersRemoved()
*/
void layersWillBeRemoved( const QList<QgsMapLayer*>& layers );

/**
* Emitted when an owned layer is removed from the registry
* Emitted when a layer is about to be removed from the registry.
*
* @param theLayerId The id of the layer being removed
* @param theLayerId The ID of the layer to be removed.
*
* @note Consider using {@link layersWillBeRemoved()} instead
* @see layersWillBeRemoved()
* @see layerRemoved()
*/
//TODO QGIS 3.0 - rename theLayerId to layerId
void layerWillBeRemoved( const QString& theLayerId );

/**
* Emitted when an owned layer is removed from the registry
* Emitted when a layer is about to be removed from the registry.
*
* @param layer The layer being removed
* @param layer The layer to be removed.
*
* @note Consider using {@link layersWillBeRemoved()} instead
* @see layersWillBeRemoved()
* @see layerRemoved()
*/
void layerWillBeRemoved( QgsMapLayer* layer );

/**
* Emitted after one or more layers were removed from the registry
* Emitted after one or more layers were removed from the registry.
*
* @param theLayerIds A list of ids of the layers which were removed.
* @param theLayerIds A list of IDs of the layers which were removed.
* @see layersWillBeRemoved()
*/
//TODO QGIS 3.0 - rename theLayerIds to layerIds
void layersRemoved( const QStringList& theLayerIds );

/**
* Emitted after a layer was removed from the registry
* Emitted after a layer was removed from the registry.
*
* @param theLayerId The id of the layer removed
* @param theLayerId The ID of the layer removed.
*
* @note Consider using {@link layersRemoved()} instead
* @see layerWillBeRemoved()
*/
//TODO QGIS 3.0 - rename theLayerId to layerId
void layerRemoved( const QString& theLayerId );


/**
* Emitted, when all layers are removed, before {@link layersWillBeRemoved()} and
* {@link layerWillBeRemoved()} signals are emitted. You will still get these signals
* in any case.
* Emitted when all layers are removed, before {@link layersWillBeRemoved()} and
* {@link layerWillBeRemoved()} signals are emitted. The layersWillBeRemoved() and
* layerWillBeRemoved() signals will still be emitted following this signal.
* You can use this signal to do easy (and fast) cleanup.
*/
//TODO QGIS 3.0 - rename to past tense
void removeAll();

/**
* Emitted when one or more layers are added to the registry.
* Emitted when one or more layers were added to the registry.
* This signal is also emitted for layers added to the registry,
* but not to the legend and canvas.
* but not to the legend.
*
* @param theMapLayers The layers which have been added
* @param theMapLayers List of layers which have been added.
*
* @see legendLayersAdded()
* @see layerWasAdded()
*/
//TODO QGIS 3.0 - rename theMapLayers to mapLayers
void layersAdded( const QList<QgsMapLayer *>& theMapLayers );

/**
* Emitted when a layer is added to the registry.
* Emitted when a layer was added to the registry.
*
* @param theMapLayer The id of the layer which has been added
* @param theMapLayer The ID of the layer which has been added.
*
* @note Consider using {@link layersAdded()} instead
* @see layersAdded()
*/
// TODO QGIS 3.0 - rename theMapLayer to layer
void layerWasAdded( QgsMapLayer* theMapLayer );

/**
* Emitted, when a layer is added to the registry and the legend.
* Plugins are allowed to have private layers, which are signalled by
* Emitted, when a layer was added to the registry and the legend.
* Layers can also be private layers, which are signalled by
* {@link layersAdded()} and {@link layerWasAdded()} but will not be
* advertised by this signal.
*
* @param theMapLayers The {@link QgsMapLayer}s which are added to the legend.
* @param theMapLayers List of {@link QgsMapLayer}s which were added to the legend.
*/
//TODO QGIS 3.0 rename theMapLayers to mapLayers
void legendLayersAdded( const QList<QgsMapLayer*>& theMapLayers );

private:
//! private singleton constructor
QgsMapLayerRegistry();

void connectNotify( const char * signal );
}; // class QgsMapLayerRegistry
};

0 comments on commit 6b3cb24

Please sign in to comment.