Merge pull request #4672 from nyalldawson/scale

Unify scale widgets API, pt 1

doc/api_break.dox

@@ -1027,6 +1027,7 @@ QgsDiagramSettings        {#qgis_api_break_3_0_QgsDiagramSettings}
 - readXml() and writeXml() do not take QgsVectorLayer as an argument anymore.
 - transparency was removed. Use opacity instead.
 - angleOffset was removed. Use rotationOffset instead.
+- minScaleDenominator and maxScaleDenominator were removed. Use maximumScale and minimumScale instead.
 
 
 QgsDial        {#qgis_api_break_3_0_QgsDial}
@@ -1067,6 +1068,8 @@ QgsDxfExport        {#qgis_api_break_3_0_QgsDxfExport}
 - The signature for writeLine() has changed.
 - writePoint(), writeFilledCircle(), writeCircle(), writeText() and writeMText() now take QgsPointV2 arguments
 - setMapUnits() was removed. The map units are dictated by the units for the destination CRS.
+- setSymbologyScaleDenominator() and symbologyScaleDenominator() were renamed to setSymbologyScale() and symbologyScale()
+for consistency with other parts of the QGIS API.
 
 
 QgsEditFormConfig        {#qgis_api_break_3_0_QgsEditFormConfig}
@@ -1582,6 +1585,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 +1610,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}
 --------------------
@@ -1740,6 +1751,8 @@ and setDataDefinedProperties() instead.
 - readXml() and writeXml() now expect a reference to QgsReadWriteContext.
 - fromLayer() has been reoved. Labeling is read/written in QgsAbstractVectorLayerLabeling and its subclasses.
 - angleOffset is now in degrees clockwise. QGIS 2.x used degrees counterclockwise.
+- scaleMin and scaleMax were removed. Use minimumScale and maximumScale instead (note that the definition
+of these are the opposite of scaleMin/scaleMax).
 
 
 QgsPanelWidgetStack        {#qgis_api_break_3_0_QgsPanelWidgetStack}
@@ -1773,6 +1786,8 @@ QgsPointDisplacementRenderer        {#qgis_api_break_3_0_QgsPointDisplacementRen
 ----------------------------
 
 - The deprecated method setDisplacementGroups() has been removed. This method has had no effect since QGIS 2.4
+- setMaxLabelScaleDenominator() and maxLabelScaleDenominator() were renamed to setMinimumLabelScale() and 
+minimumLabelScale() for consistency with other areas in the QGIS API.
 
 
 QgsPointLocator        {#qgis_api_break_3_0_QgsPointLocator}
@@ -1991,6 +2006,7 @@ QgsRuleBasedRenderer        {#qgis_api_break_3_0_QgsRuleBasedRenderer}
 
 - QgsRuleBasedRenderer.Rule checkState() and setCheckState() were removed. Use active() and setActive() instead.
 - QgsRuleBasedRenderer.Rule updateElseRules() was removed.
+- QgsRuleBasedRenderer.Rule scaleMinDenom(), scaleMaxDenom(), setScaleMaxDenom() and setScaleMinDenom() were removed. Use minimumScale(), maximumScale(), setMinimumScale() and setMaximumScale() instead.
 - startRender( QgsRenderContext& context, const QgsFields& fields ) was removed. Use startRender( QgsRenderContext& context, const QgsFields& fields, QString& filter ) instead.
 
 
@@ -2010,6 +2026,32 @@ QgsScaleBarStyle        {#qgis_api_break_3_0_QgsScaleBarStyle}
 - The interface for QgsScaleBarStyle has been completely rewritten - any code using QgsScaleBarStyle or subclasses will need to update
 to the new draw() and calculateBoxSize() methods.
 
+
+QgsScaleComboBox        {#qgis_api_break_3_0_QgsScaleComboBox}
+----------------
+
+- All numeric scales reported and used by QgsScaleComboBox now represent the scale denominator (i.e. 2345 for a scale "1:2345"), for consistency with other scale use throughout the API.
+
+
+QgsScaleRangeWidget        {#qgis_api_break_3_0_QgsScaleRangeWidget}
+-------------------
+
+- All numeric scales reported and used by QgsScaleRangeWidget now represent the scale denominator (i.e. 2345 for a scale "1:2345"), for consistency with other scale use throughout the API.
+- minimumScaleDenom() and maximumScaleDenom() were removed. Now minimumScale() and maximumScale() report the scale denominator.
+
+
+QgsScaleVisibilityDialog        {#qgis_api_break_3_0_QgsScaleVisibilityDialog}
+------------------------
+
+- All numeric scales reported and used by QgsScaleVisibilityDialog now represent the scale denominator (i.e. 2345 for a scale "1:2345"), for consistency with other scale use throughout the API.
+
+
+QgsScaleWidget        {#qgis_api_break_3_0_QgsScaleWidget}
+--------------
+
+- All numeric scales reported and used by QgsScaleWidget now represent the scale denominator (i.e. 2345 for a scale "1:2345"), for consistency with other scale use throughout the API.
+
+
 QgsServer       {#qgis_api_break_3_0_QgsServer}
 ----------
 
@@ -2408,6 +2450,8 @@ QgsCoordinateReferenceSystem is now implicitly shared, using references to QgsCo
 pointers makes for more robust, safer code. Use an invalid (default constructed) QgsCoordinateReferenceSystem
 in code which previously passed a null pointer to QgsVectorFileWriter.
 - writeAsVectorFormat() now takes a QgsCoordinateTransform reference, not a pointer. An invalid QgsCoordinateTransform should be used instead of a null pointer if no transformation is required.
+- setSymbologyScaleDenominator() and symbologyScaleDenominator() were renamed to setSymbologyScale() and symbologyScale()
+for consistency with other parts of the QGIS API.
 
 
 QgsWMSLegendNode        {#qgis_api_break_3_0_QgsWMSLegendNode}

python/auto_sip.blacklist

@@ -50,8 +50,6 @@ gui/qgsrasterformatsaveoptionswidget.sip
 gui/qgsrasterlayersaveasdialog.sip
 gui/qgsrasterpyramidsoptionswidget.sip
 gui/qgsrubberband.sip
-gui/qgsscalerangewidget.sip
-gui/qgsscalevisibilitydialog.sip
 gui/qgsscrollarea.sip
 gui/qgssearchquerybuilder.sip
 gui/qgsshortcutsmanager.sip

python/core/composer/qgscomposermap.sip

@@ -107,13 +107,17 @@ Sets new scene rectangle bounds and recalculates hight and extent
 
     double scale() const;
 %Docstring
- Scale
+ Returns the map scale.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: setNewScale()
  :rtype: float
 %End
 
     void setNewScale( double scaleDenominator, bool forceUpdate = true );
 %Docstring
-Sets new scale and changes only mExtent
+ Sets new map ``scale`` and changes only the map extent.
+ The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: scale()
 %End
 
     void setNewExtent( const QgsRectangle &extent );

python/core/dxf/qgsdxfexport.sip

@@ -43,17 +43,20 @@ class QgsDxfExport
 
     int writeToFile( QIODevice *d, const QString &codec );  //maybe add progress dialog? other parameters (e.g. scale, dpi)?
 
-    void setSymbologyScaleDenominator( double d );
+    void setSymbologyScale( double scale );
 %Docstring
- Set reference scale for output
- \param d scale denominator
+ Set reference ``scale`` for output.
+ The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. versionadded:: 3.0
+.. seealso:: symbologyScale()
 %End
 
-    double symbologyScaleDenominator() const;
+    double symbologyScale() const;
 %Docstring
- Retrieve reference scale for output
- :return: reference scale
-.. seealso:: setSymbologyScaleDenominator
+ Returns the reference scale for output.
+ The  scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. versionadded:: 3.0
+.. seealso:: setSymbologyScale()
  :rtype: float
 %End
 
@@ -263,9 +266,10 @@ class QgsDxfExport
 .. versionadded:: 2.15
 %End
 
-    static double mapUnitScaleFactor( double scaleDenominator, QgsUnitTypes::RenderUnit symbolUnits, QgsUnitTypes::DistanceUnit mapUnits );
+    static double mapUnitScaleFactor( double scale, QgsUnitTypes::RenderUnit symbolUnits, QgsUnitTypes::DistanceUnit mapUnits );
 %Docstring
-Calculates a scaling factor to convert from map units to a specified symbol unit.
+ Calculates a scaling factor to convert from map units to a specified symbol unit.
+ The ``scale`` parameter indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
  :rtype: float
 %End
 

python/core/layertree/qgslayertreemodel.sip

@@ -211,12 +211,22 @@ Return at what number of legend nodes the layer node should be collapsed. -1 mea
  :rtype: int
 %End
 
-    void setLegendFilterByScale( double scaleDenominator );
+    void setLegendFilterByScale( double scale );
 %Docstring
+ Force only display of legend nodes which are valid for a given ``scale``.
+ The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+ Setting ``scale`` <= 0 will disable the functionality.
 .. versionadded:: 2.6
+.. seealso:: legendFilterByScale()
 %End
+
     double legendFilterByScale() const;
 %Docstring
+ Returns the scale which restricts the legend nodes which are visible.
+ The  scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+ A scale <= 0 indicates that no scale filtering is being performed.
+.. versionadded:: 2.6
+.. seealso:: setLegendFilterByScale()
  :rtype: float
 %End
 

python/core/qgsdiagramrenderer.sip

@@ -373,8 +373,22 @@ Opacity, from 0 (transparent) to 1.0 (opaque)
 %End
 
     bool scaleBasedVisibility;
-    double minScaleDenominator;
-    double maxScaleDenominator;
+
+    double maximumScale;
+%Docstring
+ The maximum map scale (i.e. most "zoomed in" scale) at which the diagrams will be visible.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+ A scale of 0 indicates no maximum scale visibility.
+.. seealso:: minimumScale
+%End
+
+    double minimumScale;
+%Docstring
+ The minimum map scale (i.e. most "zoomed out" scale) at which the diagrams will be visible.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+ A scale of 0 indicates no minimum scale visibility.
+.. seealso:: maximumScale
+%End
 
     double minimumSize;
 %Docstring

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/qgsmaplayer.sip

@@ -760,8 +760,8 @@ Return pointer to layer's undo stack
 
     bool isInScaleRange( double scale ) const;
 %Docstring
- Tests whether the layer should be visible at the specified scale.
- \param scale scale denominator to test
+ Tests whether the layer should be visible at the specified ``scale``.
+  The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
  :return: true if the layer is visible at the given scale.
 .. versionadded:: 2.16
 .. seealso:: minimumScale()

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/qgspallabeling.sip

@@ -248,7 +248,9 @@ class QgsPalLayerSettings
       // rendering
       ScaleVisibility,
       MinScale,
+      MinimumScale,
       MaxScale,
+      MaximumScale,
       FontLimitPixel,
       FontMinPixel,
       FontMaxPixel,
@@ -362,8 +364,22 @@ Label rotation, in degrees clockwise
 
 
     bool scaleVisibility;
-    int scaleMin;
-    int scaleMax;
+
+    double maximumScale;
+%Docstring
+ The maximum map scale (i.e. most "zoomed in" scale) at which the labels will be visible.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+ A scale of 0 indicates no maximum scale visibility.
+.. seealso:: minimumScale
+%End
+
+    double minimumScale;
+%Docstring
+ The minimum map scale (i.e. most "zoomed out" scale) at which the labels will be visible.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+ A scale of 0 indicates no minimum scale visibility.
+.. seealso:: maximumScale
+%End
 
     bool fontLimitPixelSize; // true is label should be limited by fontMinPixelSize/fontMaxPixelSize
     int fontMinPixelSize; // minimum pixel size for showing rendered map unit labels (1 - 1000)