Skip to content

Commit

Permalink
Remove "the"-prefix from method signatures
Browse files Browse the repository at this point in the history
  • Loading branch information
@m-kuhn
m-kuhn committed Feb 20, 2017
1 parent 75367e4 commit 382b213
Show file tree
Hide file tree
Showing 3 changed files with 41 additions and 204 deletions.
175 changes: 12 additions & 163 deletions python/core/qgsproject.sip
View file
Expand Up @@ -412,14 +412,7 @@ class QgsProject : QObject, QgsExpressionContextGenerator
void setCustomVariables( const QVariantMap& customVariables );
int count() const;

/** 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;
QgsMapLayer* mapLayer( const QString& layerId ) const;

/** Retrieve a list of matching registered layers by layer name.
* @param layerName name of layers to match
Expand All @@ -436,79 +429,12 @@ class QgsProject : QObject, QgsExpressionContextGenerator
*/
QMap<QString, QgsMapLayer*> mapLayers() const;

/**
* @brief
* Add a list of layers to the map of loaded layers.
*
* 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.
* @param takeOwnership Ownership will be transferred to the layer registry.
* If you specify false here you have take care of deleting
* the layers yourself. Not available in python.
*
* @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 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/,
QList<QgsMapLayer *> addMapLayers( const QList<QgsMapLayer *>& layers /Transfer/,
bool addToLegend = true );

/**
* @brief
* Add a layer to the map of loaded layers.
*
* 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
* addMapLayers() instead.
*
* @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
* 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
* the layer yourself. Not available in python.
*
* @return nullptr if unable to add layer, otherwise pointer to newly added layer
*
* @see addMapLayers
*
* @note As a side-effect QgsProject is made dirty.
* @note Use addMapLayers if adding more than one layer at a time
* @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 );
QgsMapLayer* addMapLayer( QgsMapLayer * layer /Transfer/, bool addToLegend = true );

/**
* @brief
* Remove a set of layers from the registry by layer ID.
*
* The specified layers will be removed from the registry. If the registry has ownership
* of any layers these layers will also be deleted.
*
* @param theLayerIds list of IDs of the layers to remove
*
* @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 );
void removeMapLayers( const QStringList& layerIds );

/**
* @brief
Expand All @@ -525,21 +451,7 @@ class QgsProject : QObject, QgsExpressionContextGenerator
*/
void removeMapLayers( const QList<QgsMapLayer*>& layers );

/**
* @brief
* Remove a layer from the registry by layer ID.
*
* The specified layer will be removed from the registry. If the registry has ownership
* of the layer then it will also be deleted.
*
* @param theLayerId ID of the layer to remove
*
* @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 );
void removeMapLayer( const QString& layerId );

/**
* @brief
Expand Down Expand Up @@ -673,15 +585,7 @@ class QgsProject : QObject, QgsExpressionContextGenerator
// signals from QgsMapLayerRegistry
//

/**
* Emitted when one or more layers are about to be removed from the registry.
*
* @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 );
void layersWillBeRemoved( const QStringList& layerIds );

/**
* Emitted when one or more layers are about to be removed from the registry.
Expand All @@ -692,17 +596,7 @@ class QgsProject : QObject, QgsExpressionContextGenerator
*/
void layersWillBeRemoved( const QList<QgsMapLayer*>& layers );

/**
* Emitted when a layer is about to be removed from the registry.
*
* @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 );
void layerWillBeRemoved( const QString& layerId );

/**
* Emitted when a layer is about to be removed from the registry.
Expand All @@ -715,25 +609,9 @@ class QgsProject : QObject, QgsExpressionContextGenerator
*/
void layerWillBeRemoved( QgsMapLayer* layer );

/**
* Emitted after one or more layers were removed from the registry.
*
* @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 );
void layersRemoved( const QStringList& layerIds );

/**
* Emitted after a layer was removed from the registry.
*
* @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 );
void layerRemoved( const QString& layerId );

/**
* Emitted when all layers are removed, before {@link layersWillBeRemoved()} and
Expand All @@ -744,40 +622,11 @@ class QgsProject : QObject, QgsExpressionContextGenerator
//TODO QGIS 3.0 - rename to past tense
void removeAll();

/**
* 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.
*
* @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 );
void layersAdded( const QList<QgsMapLayer *>& layers );

/**
* Emitted when a layer was added to the registry.
*
* @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 );
void layerWasAdded( QgsMapLayer* layer );

/**
* 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 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 );
void legendLayersAdded( const QList<QgsMapLayer*>& layers );

public slots:
/**
Expand Down
20 changes: 10 additions & 10 deletions src/core/qgsproject.cpp
View file
Expand Up @@ -2001,9 +2001,9 @@ int QgsProject::count() const
return mMapLayers.size();
}

QgsMapLayer * QgsProject::mapLayer( const QString& theLayerId ) const
QgsMapLayer * QgsProject::mapLayer( const QString& layerId ) const
{
return mMapLayers.value( theLayerId );
return mMapLayers.value( layerId );
}

QList<QgsMapLayer *> QgsProject::mapLayersByName( const QString& layerName ) const
Expand All @@ -2020,12 +2020,12 @@ QList<QgsMapLayer *> QgsProject::mapLayersByName( const QString& layerName ) con
}

QList<QgsMapLayer *> QgsProject::addMapLayers(
const QList<QgsMapLayer *>& theMapLayers,
const QList<QgsMapLayer *>& layers,
bool addToLegend,
bool takeOwnership )
{
QList<QgsMapLayer *> myResultList;
Q_FOREACH ( QgsMapLayer* myLayer, theMapLayers )
Q_FOREACH ( QgsMapLayer* myLayer, layers )
{
if ( !myLayer || !myLayer->isValid() )
{
Expand Down Expand Up @@ -2056,19 +2056,19 @@ QList<QgsMapLayer *> QgsProject::addMapLayers(
}

QgsMapLayer *
QgsProject::addMapLayer( QgsMapLayer* theMapLayer,
QgsProject::addMapLayer( QgsMapLayer* layer,
bool addToLegend,
bool takeOwnership )
{
QList<QgsMapLayer *> addedLayers;
addedLayers = addMapLayers( QList<QgsMapLayer*>() << theMapLayer, addToLegend, takeOwnership );
addedLayers = addMapLayers( QList<QgsMapLayer*>() << layer, addToLegend, takeOwnership );
return addedLayers.isEmpty() ? nullptr : addedLayers[0];
}

void QgsProject::removeMapLayers( const QStringList& theLayerIds )
void QgsProject::removeMapLayers( const QStringList& layerIds )
{
QList<QgsMapLayer*> layers;
Q_FOREACH ( const QString &myId, theLayerIds )
Q_FOREACH ( const QString &myId, layerIds )
{
layers << mMapLayers.value( myId );
}
Expand Down Expand Up @@ -2116,9 +2116,9 @@ void QgsProject::removeMapLayers( const QList<QgsMapLayer*>& layers )
emit layersRemoved( layerIds );
}

void QgsProject::removeMapLayer( const QString& theLayerId )
void QgsProject::removeMapLayer( const QString& layerId )
{
removeMapLayers( QList<QgsMapLayer*>() << mMapLayers.value( theLayerId ) );
removeMapLayers( QList<QgsMapLayer*>() << mMapLayers.value( layerId ) );
}

void QgsProject::removeMapLayer( QgsMapLayer* layer )
Expand Down

6 comments on commit 382b213

@3nids
Copy link
Member

@3nids 3nids commented on 382b213 Feb 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are tons of it. Is it something wanted to remove all of them?

@m-kuhn
Copy link
Member Author

@m-kuhn m-kuhn commented on 382b213 Feb 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to have them removed, but no particular hurry.
I'm not sure if it accounts for an API change, I never found a reason why it should, but @nyalldawson once pointed out that it is... (basically this determines if it's required to do this before QGIS 3)

@nyalldawson
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't it potentially a break if someone's using ?

 project.removeMapLayers( theLayerIds = ['a','b'] )

I know that some people strictly always use named arguments in python code like this...

@m-kuhn
Copy link
Member Author

@m-kuhn m-kuhn commented on 382b213 Feb 20, 2017 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That was what I suspected when you told me it's public API... But using these as named arguments didn't work for me, does it for you? Maybe a sip compile option or version issue?

proj = QgsProject.instance()
proj.removeMapLayers(layerIds = ['xxx'] )
Traceback (most recent call last):
  File "/usr/lib64/python3.5/code.py", line 91, in runcode
    exec(code, self.locals)
  File "<input>", line 1, in <module>
TypeError: removeMapLayers() takes no keyword arguments

@nyalldawson
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah... you're right. I'd always just assumed that worked!! So I guess no break here then.

@m-kuhn
Copy link
Member Author

@m-kuhn m-kuhn commented on 382b213 Feb 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd always just assumed that worked

... which would be really nice ...

Thanks, in this case no particular hurry to drop these prefixes, I'll just address them as I bump into them.

Please sign in to comment.