Improve documentation for QgsMapCanvas and remove false QGIS 3 TODO

nyalldawson · nyalldawson · commit 79fb8aeb970a · 2017-03-01T07:29:35.000+10:00
diff --git a/python/gui/qgsmapcanvas.sip b/python/gui/qgsmapcanvas.sip
@@ -170,23 +170,9 @@ class QgsMapCanvas : QGraphicsView
 
     //! return list of layers within map canvas.
     QList<QgsMapLayer*> layers() const;
-
-    /**
-     * Freeze/thaw the map canvas. This is used to prevent the canvas from
-     * responding to events while layers are being added/removed etc.
-     * @param frz Boolean specifying if the canvas should be frozen (true) or
-     * thawed (false). Default is true.
-     *
-     * TODO remove in QGIS 3
-     */
-    void freeze( bool frz = true );
-
-    /**
-     * Accessor for frozen status of canvas
-     *
-     * TODO remove in QGIS 3
-     */
-    bool isFrozen();
+    void freeze( bool frozen = true );
+    bool isFrozen() const;
+    bool renderFlag() const;
 
     //! Get the current canvas map units
     QgsUnitTypes::DistanceUnit mapUnits() const;
@@ -347,11 +333,7 @@ class QgsMapCanvas : QGraphicsView
 
     //! This slot is connected to the layer's CRS change
     void layerCrsChange();
-
-    //! Whether to suppress rendering or not
     void setRenderFlag( bool flag );
-    //! State of render suppression flag
-    bool renderFlag();
 
     //! stop rendering (if there is any right now)
     //! @note added in 2.4
diff --git a/src/gui/qgsmapcanvas.cpp b/src/gui/qgsmapcanvas.cpp
@@ -443,7 +443,7 @@ void QgsMapCanvas::refresh()
     return;
   }
 
-  if ( !mRenderFlag || mFrozen )  // do we really need two flags controlling rendering?
+  if ( !mRenderFlag || mFrozen )
   {
     QgsDebugMsg( "CANVAS render flag off" );
     return;
@@ -1555,15 +1555,15 @@ void QgsMapCanvas::layerCrsChange()
 } // layerCrsChange
 
 
-void QgsMapCanvas::freeze( bool frz )
+void QgsMapCanvas::freeze( bool frozen )
 {
-  mFrozen = frz;
-} // freeze
+  mFrozen = frozen;
+}
 
-bool QgsMapCanvas::isFrozen()
+bool QgsMapCanvas::isFrozen() const
 {
   return mFrozen;
-} // freeze
+}
 
 
 double QgsMapCanvas::mapUnitsPerPixel() const
diff --git a/src/gui/qgsmapcanvas.h b/src/gui/qgsmapcanvas.h
@@ -232,19 +232,32 @@ class GUI_EXPORT QgsMapCanvas : public QGraphicsView
     /**
      * Freeze/thaw the map canvas. This is used to prevent the canvas from
      * responding to events while layers are being added/removed etc.
-     * @param frz Boolean specifying if the canvas should be frozen (true) or
+     * @param frozen Boolean specifying if the canvas should be frozen (true) or
      * thawed (false). Default is true.
-     *
-     * TODO remove in QGIS 3
+     * @see isFrozen()
+     * @see setRenderFlag(). freeze() should be used to programmatically halt map updates,
+     * while setRenderFlag() should only be used when users disable rendering via GUI.
      */
-    void freeze( bool frz = true );
+    void freeze( bool frozen = true );
 
     /**
-     * Accessor for frozen status of canvas
-     *
-     * TODO remove in QGIS 3
+     * Returns true if canvas is frozen.
+     * @see renderFlag(). isFrozen() should be used to determine whether map updates
+     * have been halted programmatically, while renderFlag() should be used to
+     * determine whether a user has disabled rendering via GUI.
+     * @see freeze()
      */
-    bool isFrozen();
+    bool isFrozen() const;
+
+    /**
+     * Returns true if canvas render is disabled as a result of user disabling
+     * renders via the GUI.
+     * @see setRenderFlag()
+     * @see isFrozen(). isFrozen() should be used to determine whether map updates
+     * have been halted programmatically, while renderFlag() should be used to
+     * determine whether a user has disabled rendering via GUI.
+     */
+    bool renderFlag() const { return mRenderFlag; }
 
     /**
      * Convience function for returning the current canvas map units. The map units
@@ -409,10 +422,14 @@ class GUI_EXPORT QgsMapCanvas : public QGraphicsView
     //! This slot is connected to the layer's CRS change
     void layerCrsChange();
 
-    //! Whether to suppress rendering or not
+    /**
+     * Sets whether a user has disabled canvas renders via the GUI.
+     * @param flag set to false to indicate that user has disabled renders
+     * @see renderFlag()
+     * @see freeze(). freeze() should be used to programmatically halt map updates,
+     * while setRenderFlag() should only be used when users disable rendering via GUI.
+     */
     void setRenderFlag( bool flag );
-    //! State of render suppression flag
-    bool renderFlag() {return mRenderFlag;}
 
     //! stop rendering (if there is any right now)
     //! @note added in 2.4

Original file line number	Diff line number	Diff line change
`@@ -443,7 +443,7 @@ void QgsMapCanvas::refresh()`
`443`	`443`	`return;`
`444`	`444`	`}`
`445`	`445`
`446`		`- if ( !mRenderFlag \|\| mFrozen ) // do we really need two flags controlling rendering?`
	`446`	`+ if ( !mRenderFlag \|\| mFrozen )`
`447`	`447`	`{`
`448`	`448`	`QgsDebugMsg( "CANVAS render flag off" );`
`449`	`449`	`return;`
`@@ -1555,15 +1555,15 @@ void QgsMapCanvas::layerCrsChange()`
`1555`	`1555`	`} // layerCrsChange`
`1556`	`1556`
`1557`	`1557`
`1558`		`-void QgsMapCanvas::freeze( bool frz )`
	`1558`	`+void QgsMapCanvas::freeze( bool frozen )`
`1559`	`1559`	`{`
`1560`		`- mFrozen = frz;`
`1561`		`-} // freeze`
	`1560`	`+ mFrozen = frozen;`
	`1561`	`+}`
`1562`	`1562`
`1563`		`-bool QgsMapCanvas::isFrozen()`
	`1563`	`+bool QgsMapCanvas::isFrozen() const`
`1564`	`1564`	`{`
`1565`	`1565`	`return mFrozen;`
`1566`		`-} // freeze`
	`1566`	`+}`
`1567`	`1567`
`1568`	`1568`
`1569`	`1569`	`double QgsMapCanvas::mapUnitsPerPixel() const`