Skip to content

Commit 6b3cb24

Browse files
nyalldawsonnyalldawson
committed
Cleanups to QgsMapLayerRegistry
- const correctness - improve and clarify docs, remove outdated notes - add some QGIS 3.0 todos
1 parent 15c2f0a commit 6b3cb24

File tree

3 files changed

+281
-190
lines changed

3 files changed

+281
-190
lines changed

‎python/core/qgsmaplayerregistry.sip‎

Lines changed: 133 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
/** \ingroup core
2+
* \class QgsMapLayerRegistry
23
* This class tracks map layers that are currently loaded and provides
3-
* a means to fetch a pointer to a map layer and delete it.
4+
* various methods to retrieve matching layers from the registry.
45
*/
56
class QgsMapLayerRegistry : QObject
67
{
@@ -12,60 +13,78 @@ class QgsMapLayerRegistry : QObject
1213
//! Returns the instance pointer, creating the object on the first call
1314
static QgsMapLayerRegistry * instance();
1415

15-
//! Return the number of registered layers.
16-
int count();
17-
1816
~QgsMapLayerRegistry();
1917

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

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

26-
//! Retrieve the mapLayers collection (mainly intended for use by projection)
27-
const QMap<QString, QgsMapLayer*> & mapLayers();
30+
/** Retrieve a list of matching registered layers by layer name.
31+
* @param layerName name of layers to match
32+
* @returns list of matching layers
33+
* @see mapLayer()
34+
* @see mapLayers()
35+
*/
36+
QList<QgsMapLayer *> mapLayersByName( const QString& layerName ) const;
37+
38+
/** Returns a list of all registered layers.
39+
* @see mapLayer()
40+
* @see mapLayersByName()
41+
* @see layers()
42+
*/
43+
QMap<QString, QgsMapLayer*> mapLayers() const;
2844

2945
/**
3046
* @brief
31-
* Add a list of layers to the map of loaded layers
47+
* Add a list of layers to the map of loaded layers.
3248
*
33-
* The layersAdded() and layersWasAdded() signals will be emitted in any case.
34-
* The legendLayersAdded() signal only if addToLegend is true.
49+
* The layersAdded() and layerWasAdded() signals will always be emitted.
50+
* The legendLayersAdded() signal is emitted only if addToLegend is true.
3551
*
3652
* @param theMapLayers A list of layer which should be added to the registry
3753
* @param addToLegend If true (by default), the layers will be added to the
3854
* legend and to the main canvas. If you have a private
39-
* layer, you can set this parameter to false to hide it.
55+
* layer you can set this parameter to false to hide it.
4056
* @param takeOwnership Ownership will be transferred to the layer registry.
41-
* If you specify false here, you have take care of deleting
57+
* If you specify false here you have take care of deleting
4258
* the layers yourself. Not available in python.
4359
*
44-
* @return QList<QgsMapLayer *> - a list of the map layers that were added
60+
* @return a list of the map layers that were added
4561
* successfully. If a layer is invalid, or already exists in the registry,
4662
* it will not be part of the returned QList.
4763
*
4864
* @note As a side-effect QgsProject is made dirty.
49-
* @note takeOwnership not available in python binding - always takes ownership
65+
* @note takeOwnership is not available in the Python bindings - the registry will always
66+
* take ownership
67+
* @note added in QGIS 1.8
68+
* @see addMapLayer()
5069
*/
5170
QList<QgsMapLayer *> addMapLayers( const QList<QgsMapLayer *>& theMapLayers /Transfer/,
5271
bool addToLegend = true );
5372

5473
/**
5574
* @brief
56-
* Add a layer to the map of loaded layers
75+
* Add a layer to the map of loaded layers.
5776
*
58-
* The layersAdded() and layersWasAdded() signals will be emitted in any case.
59-
* The legendLayersAdded() signal only if addToLegend is true.
77+
* The layersAdded() and layerWasAdded() signals will always be emitted.
78+
* The legendLayersAdded() signal is emitted only if addToLegend is true.
6079
* If you are adding multiple layers at once, you should use
61-
* {@link addMapLayers()} instead.
80+
* addMapLayers() instead.
6281
*
63-
* @param theMapLayer A layer to add to the registry
82+
* @param theMapLayer A layer to add to the registry
6483
* @param addToLegend If true (by default), the layer will be added to the
6584
* legend and to the main canvas. If you have a private
66-
* you can set this parameter to false to hide it.
85+
* layer you can set this parameter to false to hide it.
6786
* @param takeOwnership Ownership will be transferred to the layer registry.
68-
* If you specify false here, you have take care of deleting
87+
* If you specify false here you have take care of deleting
6988
* the layer yourself. Not available in python.
7089
*
7190
* @return nullptr if unable to add layer, otherwise pointer to newly added layer
@@ -74,75 +93,84 @@ class QgsMapLayerRegistry : QObject
7493
*
7594
* @note As a side-effect QgsProject is made dirty.
7695
* @note Use addMapLayers if adding more than one layer at a time
77-
* @note takeOwner not available in python binding - always takes ownership
96+
* @note takeOwnership is not available in the Python bindings - the registry will always
97+
* take ownership
98+
* @see addMapLayers()
7899
*/
79100
QgsMapLayer* addMapLayer( QgsMapLayer * theMapLayer /Transfer/, bool addToLegend = true );
80101

81102
/**
82103
* @brief
83-
* Remove a set of layers from the registry
104+
* Remove a set of layers from the registry by layer ID.
84105
*
85-
* Any canvases using the affected layers will need to remove them
106+
* The specified layers will be removed from the registry. If the registry has ownership
107+
* of any layers these layers will also be deleted.
86108
*
87-
* The layers being removed are deleted as well as the registry
88-
* table entries.
109+
* @param theLayerIds list of IDs of the layers to remove
89110
*
90-
* @param theLayerIds The ids of the layers to remove
91-
*
92-
* @note As a side-effect QgsProject is made dirty.
111+
* @note As a side-effect the QgsProject instance is marked dirty.
112+
* @note added in QGIS 1.8
113+
* @see removeMapLayer()
114+
* @see removeAllMapLayers()
93115
*/
116+
// TODO QGIS 3.0 - rename theLayerIds to layerIds
94117
void removeMapLayers( const QStringList& theLayerIds );
95118

96119
/**
97120
* @brief
98-
* Remove a set of layers from the registry
121+
* Remove a set of layers from the registry.
99122
*
100-
* Any canvases using the affected layers will need to remove them
123+
* The specified layers will be removed from the registry. If the registry has ownership
124+
* of any layers these layers will also be deleted.
101125
*
102-
* The layers being removed are deleted as well as the registry
103-
* table entries.
126+
* @param layers A list of layers to remove. Null pointers are ignored.
104127
*
105-
* @param layers The layers to remove. Null pointers are ignored
106-
*
107-
* @note As a side-effect QgsProject is made dirty.
128+
* @note As a side-effect the QgsProject instance is marked dirty.
129+
* @see removeMapLayer()
130+
* @see removeAllMapLayers()
108131
*/
109132
void removeMapLayers( const QList<QgsMapLayer*>& layers );
110133

111134
/**
112135
* @brief
113-
* Remove a layer from qgis
136+
* Remove a layer from the registry by layer ID.
114137
*
115-
* Any canvases using the affected layers will need to remove them
138+
* The specified layer will be removed from the registry. If the registry has ownership
139+
* of the layer then it will also be deleted.
116140
*
117-
* The layer being removed is deleted as well as the registry
118-
* table entry.
141+
* @param theLayerId ID of the layer to remove
119142
*
120-
* @param theLayerId The id of the layer to remove
121-
*
122-
* @note As a side-effect QgsProject is made dirty.
143+
* @note As a side-effect the QgsProject instance is marked dirty.
144+
* @see removeMapLayers()
145+
* @see removeAllMapLayers()
123146
*/
147+
// TODO QGIS 3.0 - rename theLayerId to layerId
124148
void removeMapLayer( const QString& theLayerId );
125149

126150
/**
127151
* @brief
128-
* Remove a layer from qgis
152+
* Remove a layer from the registry.
129153
*
130-
* Any canvases using the affected layers will need to remove them
154+
* The specified layer will be removed from the registry. If the registry has ownership
155+
* of the layer then it will also be deleted.
131156
*
132-
* The layer being removed is deleted as well as the registry
133-
* table entry.
157+
* @param layer The layer to remove. Null pointers are ignored.
134158
*
135-
* @param layer The layer to remove. Nothing happens if the pointer is null
136-
*
137-
* @note As a side-effect QgsProject is made dirty.
159+
* @note As a side-effect the QgsProject instance is marked dirty.
160+
* @see removeMapLayers()
161+
* @see removeAllMapLayers()
138162
*/
139163
void removeMapLayer( QgsMapLayer* layer );
140164

141165
/**
142-
* Remove all registered layers
143-
*
144-
* @note As a side-effect QgsProject is made dirty.
145-
* @note The layers are deleted as the registry is cleared!
166+
* Removes all registered layers. If the registry has ownership
167+
* of any layers these layers will also be deleted.
168+
*
169+
* @note As a side-effect the QgsProject instance is marked dirty.
170+
* @note Calling this method will cause the removeAll() signal to
171+
* be emitted.
172+
* @see removeMapLayer()
173+
* @see removeMapLayers()
146174
*/
147175
void removeAllMapLayers();
148176

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

158186
/**
159-
* Reload all provider data caches (currently used for WFS and WMS providers)
187+
* Reload all registered layer's provider data caches, synchronising the layer
188+
* with any changes in the datasource.
189+
* @see QgsMapLayer::reload()
160190
*/
161191
void reloadAllLayers();
162192

163193
signals:
194+
164195
/**
165-
* Emitted when one or more layers are removed from the registry
196+
* Emitted when one or more layers are about to be removed from the registry.
166197
*
167-
* @param theLayerIds A list of ids of the layers which are removed.
198+
* @param theLayerIds A list of IDs for the layers which are to be removed.
199+
* @see layerWillBeRemoved()
200+
* @see layersRemoved()
168201
*/
202+
// TODO QGIS 3.0 - rename theLayerIds to layerIds
169203
void layersWillBeRemoved( const QStringList& theLayerIds );
170204

171205
/**
172-
* Emitted when one or more layers are removed from the registry
206+
* Emitted when one or more layers are about to be removed from the registry.
173207
*
174-
* @param layers A list of layers which are removed.
208+
* @param layers A list of layers which are to be removed.
209+
* @see layerWillBeRemoved()
210+
* @see layersRemoved()
175211
*/
176212
void layersWillBeRemoved( const QList<QgsMapLayer*>& layers );
177213

178214
/**
179-
* Emitted when an owned layer is removed from the registry
215+
* Emitted when a layer is about to be removed from the registry.
180216
*
181-
* @param theLayerId The id of the layer being removed
217+
* @param theLayerId The ID of the layer to be removed.
182218
*
183219
* @note Consider using {@link layersWillBeRemoved()} instead
220+
* @see layersWillBeRemoved()
221+
* @see layerRemoved()
184222
*/
223+
//TODO QGIS 3.0 - rename theLayerId to layerId
185224
void layerWillBeRemoved( const QString& theLayerId );
186225

187226
/**
188-
* Emitted when an owned layer is removed from the registry
227+
* Emitted when a layer is about to be removed from the registry.
189228
*
190-
* @param layer The layer being removed
229+
* @param layer The layer to be removed.
191230
*
192231
* @note Consider using {@link layersWillBeRemoved()} instead
232+
* @see layersWillBeRemoved()
233+
* @see layerRemoved()
193234
*/
194235
void layerWillBeRemoved( QgsMapLayer* layer );
195236

196237
/**
197-
* Emitted after one or more layers were removed from the registry
238+
* Emitted after one or more layers were removed from the registry.
198239
*
199-
* @param theLayerIds A list of ids of the layers which were removed.
240+
* @param theLayerIds A list of IDs of the layers which were removed.
241+
* @see layersWillBeRemoved()
200242
*/
243+
//TODO QGIS 3.0 - rename theLayerIds to layerIds
201244
void layersRemoved( const QStringList& theLayerIds );
202245

203246
/**
204-
* Emitted after a layer was removed from the registry
247+
* Emitted after a layer was removed from the registry.
205248
*
206-
* @param theLayerId The id of the layer removed
249+
* @param theLayerId The ID of the layer removed.
207250
*
208251
* @note Consider using {@link layersRemoved()} instead
252+
* @see layerWillBeRemoved()
209253
*/
254+
//TODO QGIS 3.0 - rename theLayerId to layerId
210255
void layerRemoved( const QString& theLayerId );
211256

212-
213257
/**
214-
* Emitted, when all layers are removed, before {@link layersWillBeRemoved()} and
215-
* {@link layerWillBeRemoved()} signals are emitted. You will still get these signals
216-
* in any case.
258+
* Emitted when all layers are removed, before {@link layersWillBeRemoved()} and
259+
* {@link layerWillBeRemoved()} signals are emitted. The layersWillBeRemoved() and
260+
* layerWillBeRemoved() signals will still be emitted following this signal.
217261
* You can use this signal to do easy (and fast) cleanup.
218262
*/
263+
//TODO QGIS 3.0 - rename to past tense
219264
void removeAll();
220265

221266
/**
222-
* Emitted when one or more layers are added to the registry.
267+
* Emitted when one or more layers were added to the registry.
223268
* This signal is also emitted for layers added to the registry,
224-
* but not to the legend and canvas.
269+
* but not to the legend.
225270
*
226-
* @param theMapLayers The layers which have been added
271+
* @param theMapLayers List of layers which have been added.
227272
*
228273
* @see legendLayersAdded()
274+
* @see layerWasAdded()
229275
*/
276+
//TODO QGIS 3.0 - rename theMapLayers to mapLayers
230277
void layersAdded( const QList<QgsMapLayer *>& theMapLayers );
231278

232279
/**
233-
* Emitted when a layer is added to the registry.
280+
* Emitted when a layer was added to the registry.
234281
*
235-
* @param theMapLayer The id of the layer which has been added
282+
* @param theMapLayer The ID of the layer which has been added.
236283
*
237284
* @note Consider using {@link layersAdded()} instead
285+
* @see layersAdded()
238286
*/
287+
// TODO QGIS 3.0 - rename theMapLayer to layer
239288
void layerWasAdded( QgsMapLayer* theMapLayer );
240289

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

251301
private:
252302
//! private singleton constructor
253303
QgsMapLayerRegistry();
254304

255305
void connectNotify( const char * signal );
256-
}; // class QgsMapLayerRegistry
306+
};

0 commit comments

Comments
 (0)