Improve API, docs for QgsDistanceArea

python/core/qgsdistancearea.sip

@@ -15,12 +15,28 @@ class QgsDistanceArea
     //! Copy constructor
     QgsDistanceArea( const QgsDistanceArea &origDA );
 
-    //! sets whether coordinates must be projected to ellipsoid before measuring
+    /** Sets whether coordinates must be projected to ellipsoid before measuring
+     * @note for calculations to use the ellipsoid, both the ellipsoid mode must be true
+     * and an ellipse must be set
+     * @see setEllipsoid()
+     * @see willUseEllipsoid()
+     */
     void setEllipsoidalMode( bool flag );
 
-    //! returns projections enabled flag
+    /** Returns whether ellipsoidal calculations are enabled
+     * @see willUseEllipsoid()
+     * @see setEllipsoidalMode()
+     */
     bool ellipsoidalEnabled() const;
 
+    /** Returns whether calculations will use the ellipsoid. Calculations will only use the
+     * ellipsoid if ellipsoidalEnabled() is true and an ellipsoid has been set.
+     * @note added in QGIS 2.14
+     * @see ellipsoidalEnabled()
+     * @see ellipsoid()
+     */
+    bool willUseEllipsoid() const;
+
     //! sets source spatial reference system (by QGIS CRS)
     void setSourceCrs( long srsid );
 
@@ -38,14 +54,31 @@ class QgsDistanceArea
     //! What sort of coordinate system is being used?
     bool geographic() const;
 
-    //! sets ellipsoid by its acronym
+    /** Sets ellipsoid by its acronym. Calculations will only use the ellipsoid if
+     * both the ellipsoid has been set and ellipsoidalEnabled() is true.
+     * @returns true if ellipsoid was successfully set
+     * @see ellipsoid()
+     * @see setEllipsoidalMode()
+     * @see willUseEllipsoid()
+     */
     bool setEllipsoid( const QString& ellipsoid );
 
-    //! Sets ellipsoid by supplied radii
+    /** Sets ellipsoid by supplied radii. Calculations will only use the ellipsoid if
+     * both the ellipsoid has been set and ellipsoidalEnabled() is true.
+     * @returns true if ellipsoid was successfully set
+     * @see ellipsoid()
+     * @see setEllipsoidalMode()
+     * @see willUseEllipsoid()
+     */
     // Inverse flattening is calculated with invf = a/(a-b)
     bool setEllipsoid( double semiMajor, double semiMinor );
 
-    //! returns ellipsoid's acronym
+    /** Returns ellipsoid's acronym. Calculations will only use the
+     * ellipsoid if ellipsoidalEnabled() is true and an ellipsoid has been set.
+     * @see setEllipsoid()
+     * @see ellipsoidalEnabled()
+     * @see willUseEllipsoid()
+     */
     QString ellipsoid() const;
 
     //! returns ellipsoid's semi major axis

src/core/qgsdistancearea.cpp

@@ -98,6 +98,11 @@ void QgsDistanceArea::setEllipsoidalMode( bool flag )
   mEllipsoidalMode = flag;
 }
 
+bool QgsDistanceArea::willUseEllipsoid() const
+{
+  return mEllipsoidalMode && mEllipsoid != GEO_NONE;
+}
+
 void QgsDistanceArea::setSourceCrs( long srsid )
 {
   QgsCoordinateReferenceSystem srcCRS;

src/core/qgsdistancearea.h

@@ -48,12 +48,28 @@ class CORE_EXPORT QgsDistanceArea
     //! Assignment operator
     QgsDistanceArea & operator=( const QgsDistanceArea & origDA );
 
-    //! sets whether coordinates must be projected to ellipsoid before measuring
+    /** Sets whether coordinates must be projected to ellipsoid before measuring
+     * @note for calculations to use the ellipsoid, both the ellipsoid mode must be true
+     * and an ellipse must be set
+     * @see setEllipsoid()
+     * @see willUseEllipsoid()
+     */
     void setEllipsoidalMode( bool flag );
 
-    //! returns projections enabled flag
+    /** Returns whether ellipsoidal calculations are enabled
+     * @see willUseEllipsoid()
+     * @see setEllipsoidalMode()
+     */
     bool ellipsoidalEnabled() const { return mEllipsoidalMode; }
 
+    /** Returns whether calculations will use the ellipsoid. Calculations will only use the
+     * ellipsoid if ellipsoidalEnabled() is true and an ellipsoid has been set.
+     * @note added in QGIS 2.14
+     * @see ellipsoidalEnabled()
+     * @see ellipsoid()
+     */
+    bool willUseEllipsoid() const;
+
     //! sets source spatial reference system (by QGIS CRS)
     void setSourceCrs( long srsid );
 
@@ -71,14 +87,31 @@ class CORE_EXPORT QgsDistanceArea
     //! What sort of coordinate system is being used?
     bool geographic() const { return mCoordTransform->sourceCrs().geographicFlag(); }
 
-    //! sets ellipsoid by its acronym
+    /** Sets ellipsoid by its acronym. Calculations will only use the ellipsoid if
+     * both the ellipsoid has been set and ellipsoidalEnabled() is true.
+     * @returns true if ellipsoid was successfully set
+     * @see ellipsoid()
+     * @see setEllipsoidalMode()
+     * @see willUseEllipsoid()
+     */
     bool setEllipsoid( const QString& ellipsoid );
 
-    //! Sets ellipsoid by supplied radii
+    /** Sets ellipsoid by supplied radii. Calculations will only use the ellipsoid if
+     * both the ellipsoid has been set and ellipsoidalEnabled() is true.
+     * @returns true if ellipsoid was successfully set
+     * @see ellipsoid()
+     * @see setEllipsoidalMode()
+     * @see willUseEllipsoid()
+     */
     // Inverse flattening is calculated with invf = a/(a-b)
     bool setEllipsoid( double semiMajor, double semiMinor );
 
-    //! returns ellipsoid's acronym
+    /** Returns ellipsoid's acronym. Calculations will only use the
+     * ellipsoid if ellipsoidalEnabled() is true and an ellipsoid has been set.
+     * @see setEllipsoid()
+     * @see ellipsoidalEnabled()
+     * @see willUseEllipsoid()
+     */
     QString ellipsoid() const { return mEllipsoid; }
 
     //! returns ellipsoid's semi major axis

tests/src/python/test_qgsdistancearea.py

@@ -121,5 +121,23 @@ def testMeasureMultiPolygon(self):
         perimeter = da.measurePerimeter(polygon)
         assert perimeter == 16, "Expected:\n%f\nGot:\n%f\n" % (16, perimeter)
 
+    def testWillUseEllipsoid(self):
+        """test QgsDistanceArea::willUseEllipsoid """
+
+        da = QgsDistanceArea()
+        da.setEllipsoidalMode(False)
+        da.setEllipsoid("NONE")
+        self.assertFalse(da.willUseEllipsoid())
+
+        da.setEllipsoidalMode(True)
+        self.assertFalse(da.willUseEllipsoid())
+
+        da.setEllipsoid("WGS84")
+        assert da.willUseEllipsoid()
+
+        da.setEllipsoidalMode(False)
+        self.assertFalse(da.willUseEllipsoid())
+
+
 if __name__ == '__main__':
     unittest.main()