Add a signal when a project is cleared

Author: nyalldawson

python/core/auto_generated/qgsproject.sip.in

@@ -221,6 +221,8 @@ from a source to destination coordinate reference system.
 Clear the project - removes all settings and resets it back to an empty, default state.
 
 .. versionadded:: 2.4
+
+.. seealso:: :py:func:`cleared`
 %End
 
     bool read( const QString &filename );
@@ -984,19 +986,30 @@ in the project. The removeMapLayer(), removeMapLayers() calls do not block remov
 %End
 
   signals:
+
+    void cleared();
+%Docstring
+Emitted when the project is cleared (and additionally when an open project is cleared
+just before a new project is read).
+
+.. seealso:: :py:func:`clear`
+
+.. versionadded:: 3.2
+%End
+
     void readProject( const QDomDocument & );
 %Docstring
-emitted when project is being read
+Emitted when a project is being read.
 %End
 
     void writeProject( QDomDocument & );
 %Docstring
-emitted when project is being written
+Emitted when the project is being written.
 %End
 
     void readMapLayer( QgsMapLayer *mapLayer, const QDomElement &layerNode );
 %Docstring
-Emitted, after the basic initialization of a layer from the project
+Emitted after the basic initialization of a layer from the project
 file is done. You can use this signal to read additional information
 from the project file.
 
@@ -1006,7 +1019,7 @@ from the project file.
 
     void writeMapLayer( QgsMapLayer *mapLayer, QDomElement &layerElem, QDomDocument &doc );
 %Docstring
-Emitted, when a layer is being saved. You can use this method to save
+Emitted when a layer is being saved. You can use this method to save
 additional information to the layer.
 
 :param mapLayer: The map layer which is being initialized
@@ -1016,12 +1029,12 @@ additional information to the layer.
 
     void projectSaved();
 %Docstring
-emitted when the project file has been written and closed
+Emitted when the project file has been written and closed.
 %End
 
     void oldProjectVersionWarning( const QString & );
 %Docstring
-emitted when an old project file is read.
+Emitted when an old project file is read.
 %End
 
     void layerLoaded( int i, int n );
@@ -1070,7 +1083,7 @@ Emitted when the home path of the project changes.
 
     void snappingConfigChanged( const QgsSnappingConfig &config );
 %Docstring
-emitted whenever the configuration for snapping has changed
+Emitted whenever the configuration for snapping has changed.
 %End
 
     void customVariablesChanged();

src/core/qgsproject.cpp

@@ -606,6 +606,7 @@ void QgsProject::clear()
   mRootGroup->clear();
 
   setDirty( false );
+  emit cleared();
 }
 
 // basically a debugging tool to dump property list values

src/core/qgsproject.h

@@ -247,6 +247,7 @@ class CORE_EXPORT QgsProject : public QObject, public QgsExpressionContextGenera
     /**
      * Clear the project - removes all settings and resets it back to an empty, default state.
      * \since QGIS 2.4
+     * \see cleared()
      */
     void clear();
 
@@ -955,14 +956,28 @@ class CORE_EXPORT QgsProject : public QObject, public QgsExpressionContextGenera
     void setRequiredLayers( const QSet<QgsMapLayer *> &layers );
 
   signals:
-    //! emitted when project is being read
+
+    /**
+     * Emitted when the project is cleared (and additionally when an open project is cleared
+     * just before a new project is read).
+     *
+     * \see clear()
+     * \since QGIS 3.2
+     */
+    void cleared();
+
+    /**
+     * Emitted when a project is being read.
+     */
     void readProject( const QDomDocument & );
 
-    //! emitted when project is being written
+    /**
+     * Emitted when the project is being written.
+     */
     void writeProject( QDomDocument & );
 
     /**
-     * Emitted, after the basic initialization of a layer from the project
+     * Emitted after the basic initialization of a layer from the project
      * file is done. You can use this signal to read additional information
      * from the project file.
      *
@@ -972,7 +987,7 @@ class CORE_EXPORT QgsProject : public QObject, public QgsExpressionContextGenera
     void readMapLayer( QgsMapLayer *mapLayer, const QDomElement &layerNode );
 
     /**
-     * Emitted, when a layer is being saved. You can use this method to save
+     * Emitted when a layer is being saved. You can use this method to save
      * additional information to the layer.
      *
      * \param mapLayer  The map layer which is being initialized
@@ -981,10 +996,14 @@ class CORE_EXPORT QgsProject : public QObject, public QgsExpressionContextGenera
      */
     void writeMapLayer( QgsMapLayer *mapLayer, QDomElement &layerElem, QDomDocument &doc );
 
-    //! emitted when the project file has been written and closed
+    /**
+     * Emitted when the project file has been written and closed.
+     */
     void projectSaved();
 
-    //! emitted when an old project file is read.
+    /**
+     * Emitted when an old project file is read.
+     */
     void oldProjectVersionWarning( const QString & );
 
     /**
@@ -1019,7 +1038,9 @@ class CORE_EXPORT QgsProject : public QObject, public QgsExpressionContextGenera
      */
     void homePathChanged();
 
-    //! emitted whenever the configuration for snapping has changed
+    /**
+     * Emitted whenever the configuration for snapping has changed.
+     */
     void snappingConfigChanged( const QgsSnappingConfig &config );
 
     /**

tests/src/python/test_qgsproject.py

@@ -135,6 +135,14 @@ def test_makeKeyTokens_(self):
     def catchMessage(self):
         self.messageCaught = True
 
+    def testClear(self):
+        prj = QgsProject.instance()
+        prj.setTitle('xxx')
+        spy = QSignalSpy(prj.cleared)
+        prj.clear()
+        self.assertEqual(len(spy), 1)
+        self.assertFalse(prj.title())
+
     def testCrs(self):
         prj = QgsProject.instance()
         prj.clear()