Flip remaining scale API from real to denominators

Author: nyalldawson

doc/api_break.dox

@@ -1582,6 +1582,8 @@ QgsMapToPixel        {#qgis_api_break_3_0_QgsMapToPixel}
 
 - The constructor now uses the map center x and y, and requires both height and width in pixels and a rotation value
 - setYMaximum(), setYMinimum(), setXMinimum() were removed. Use setParameters() instead
+- fromScale now accepts the scale as a scale denominator, not actual scale (e.g. 2000 for 1:2000). This change
+was made to make all scale based API calls uniform in behavior.
 
 
 QgsMapToPixelGeometrySimplifier        {#qgis_api_break_3_0_QgsMapToPixelGeometrySimplifier}
@@ -1605,6 +1607,12 @@ plugins calling this method will need to be updated.
 - the default destination CRS has changed from WGS 84 to invalid CRS (i.e. undefined, no reprojection will be done).
 - setMapUnits() was removed. The map units are dictated by the units for the destination CRS.
 
+QgsMapUnitScale        {#qgis_api_break_3_0_QgsMapUnitScale}
+---------------
+
+- minScale and maxScale now represent the scale as a scale denominator, not actual scale (e.g. 2000 for 1:2000). This change
+was made to make all scale based API calls uniform in behavior.
+
 
 QgsMarkerSymbolLayer        {#qgis_api_break_3_0_QgsMarkerSymbolLayer}
 --------------------

python/core/qgslegendsettings.sip

@@ -193,9 +193,18 @@ Returns style
 
     double mapScale() const;
 %Docstring
+ Returns the legend map scale.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: setMapScale()
  :rtype: float
 %End
+
     void setMapScale( double scale );
+%Docstring
+ Sets the legend map ``scale``.
+ The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: mapScale()
+%End
 
     int dpi() const;
 %Docstring

python/core/qgsmapsettings.sip

@@ -238,9 +238,11 @@ Return the actual extent derived from requested extent that takes takes output i
 Return the distance in geographical coordinates that equals to one pixel in the map
  :rtype: float
 %End
+
     double scale() const;
 %Docstring
-Return the calculated scale of the map
+ Returns the calculated map scale.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
  :rtype: float
 %End
 

python/core/qgsmaptopixel.sip

@@ -42,8 +42,8 @@ class QgsMapToPixel
 
     static QgsMapToPixel fromScale( double scale, QgsUnitTypes::DistanceUnit mapUnits, double dpi = 96 );
 %Docstring
- Returns a new QgsMapToPixel created using a specified scale and distance unit.
- \param scale map scale
+ Returns a new QgsMapToPixel created using a specified ``scale`` and distance unit.
+ \param scale map scale denominator, e.g. 1000.0 for a 1:1000 map.
  \param dpi screen DPI
  \param mapUnits map units
  :return: matching QgsMapToPixel

python/core/qgsmapunitscale.sip

@@ -30,15 +30,19 @@ class QgsMapUnitScale
  Constructor for QgsMapUnitScale
  \param minScale minimum allowed scale, or 0.0 if no minimum scale set
  \param maxScale maximum allowed scale, or 0.0 if no maximum scale set
+ The scale values indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
 %End
 
     double minScale;
 %Docstring
-The minimum scale, or 0.0 if unset
+ The minimum scale, or 0.0 if unset.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
 %End
+
     double maxScale;
 %Docstring
-The maximum scale, or 0.0 if unset
+ The maximum scale, or 0.0 if unset.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
 %End
 
     bool minSizeMMEnabled;

python/core/qgsscalecalculator.sip

@@ -60,7 +60,7 @@ Returns current map units
  Calculate the scale denominator
  \param mapExtent QgsRectangle containing the current map extent
  \param canvasWidth Width of the map canvas in pixel (physical) units
- :return: scale denominator of current map view
+ :return: scale denominator of current map view, e.g. 1000.0 for a 1:1000 map.
  :rtype: float
 %End
 

src/core/qgslegendsettings.h

@@ -154,7 +154,18 @@ class CORE_EXPORT QgsLegendSettings
     bool useAdvancedEffects() const { return mUseAdvancedEffects; }
     void setUseAdvancedEffects( bool use ) { mUseAdvancedEffects = use; }
 
+    /**
+     * Returns the legend map scale.
+     * The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+     * \see setMapScale()
+     */
     double mapScale() const { return mMapScale; }
+
+    /**
+     * Sets the legend map \a scale.
+     * The \a scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+     * \see mapScale()
+     */
     void setMapScale( double scale ) { mMapScale = scale; }
 
     int dpi() const { return mDpi; }

src/core/qgsmapsettings.h

@@ -198,7 +198,11 @@ class CORE_EXPORT QgsMapSettings
     QPolygonF visiblePolygon() const;
     //! Return the distance in geographical coordinates that equals to one pixel in the map
     double mapUnitsPerPixel() const;
-    //! Return the calculated scale of the map
+
+    /**
+     * Returns the calculated map scale.
+     * The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+     */
     double scale() const;
 
     /** Sets the expression context. This context is used for all expression evaluation

src/core/qgsmaptopixel.cpp

@@ -61,7 +61,7 @@ QgsMapToPixel QgsMapToPixel::fromScale( double scale, QgsUnitTypes::DistanceUnit
 {
   double metersPerPixel = 25.4 / dpi / 1000.0;
   double mapUnitsPerPixel = metersPerPixel * QgsUnitTypes::fromUnitToUnitFactor( QgsUnitTypes::DistanceMeters, mapUnits );
-  return QgsMapToPixel( mapUnitsPerPixel / scale );
+  return QgsMapToPixel( mapUnitsPerPixel * scale );
 }
 
 QgsMapToPixel::QgsMapToPixel()

src/core/qgsmaptopixel.h

@@ -54,8 +54,8 @@ class CORE_EXPORT QgsMapToPixel
      */
     QgsMapToPixel( double mapUnitsPerPixel );
 
-    /** Returns a new QgsMapToPixel created using a specified scale and distance unit.
-     * \param scale map scale
+    /** Returns a new QgsMapToPixel created using a specified \a scale and distance unit.
+     * \param scale map scale denominator, e.g. 1000.0 for a 1:1000 map.
      * \param dpi screen DPI
      * \param mapUnits map units
      * \returns matching QgsMapToPixel