Improve documentation for QgsMapCanvas and remove false QGIS 3 TODO

python/gui/qgsmapcanvas.sip

@@ -170,23 +170,9 @@ class QgsMapCanvas : QGraphicsView
 
     //! return list of layers within map canvas.
     QList<QgsMapLayer*> layers() const;
-
+    void freeze( bool frozen = true );
-    /**
+    bool isFrozen() const;
-     * Freeze/thaw the map canvas. This is used to prevent the canvas from
+    bool renderFlag() const;
-     * 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();
 
     //! 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

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;
+  mFrozen = frozen;
-} // freeze
+}
 
-bool QgsMapCanvas::isFrozen()
+bool QgsMapCanvas::isFrozen() const
 {
   return mFrozen;
-} // freeze
+}
 
 
 double QgsMapCanvas::mapUnitsPerPixel() const

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.
-     *
+     * @see isFrozen()
-     * TODO remove in QGIS 3
+     * @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
+     * Returns true if canvas is frozen.
-     *
+     * @see renderFlag(). isFrozen() should be used to determine whether map updates
-     * TODO remove in QGIS 3
+     * 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