Unify scale widgets API

Flip all scale based widgets to use scale denominators instead
of actual scales (ie 100.0 instead of 0.01 for 1:100).

This is done for consistency with the rest of the API, which
predominantly uses scale denominators. It also helps
precision loss as a result of multiple 1.0 / scale conversions
throughout the code.

Refs #15337

Author: nyalldawson

doc/api_break.dox

@@ -2010,6 +2010,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}
 ----------
 

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/gui/qgsscalecombobox.sip

@@ -21,57 +21,90 @@ class QgsScaleComboBox : QComboBox
 #include "qgsscalecombobox.h"
 %End
   public:
+
     QgsScaleComboBox( QWidget *parent /TransferThis/ = 0 );
+%Docstring
+ Constructor for QgsScaleComboBox.
+%End
 
-    QString scaleString();
+    QString scaleString() const;
 %Docstring
-Function to read the selected scale as text
+ Returns the selected scale as a string, e.g. "1:150".
+.. seealso:: setScaleString()
  :rtype: str
 %End
-    bool setScaleString( const QString &scaleTxt );
+
+    bool setScaleString( const QString &string );
 %Docstring
-Function to set the selected scale from text
+ Set the selected scale from a ``string``, e.g. "1:150".
+.. seealso:: scaleString()
  :rtype: bool
 %End
+
     double scale() const;
 %Docstring
-Function to read the selected scale as double
+ Returns the selected scale as a double.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: setScale()
  :rtype: float
 %End
-    void setScale( double scale );
-%Docstring
-Function to set the selected scale from double
-%End
+
     double minScale() const;
 %Docstring
-Function to read the min scale
+ Returns the minimum scale, or 0 if no minimum scale set.
+ The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+ Any scale lower than the minimum scale will automatically be converted to the minimum scale.
+ Except for 0 which is always allowed.
  :rtype: float
 %End
 
     static QString toString( double scale );
 %Docstring
+ Helper function to convert a ``scale`` double to scale string.
+ The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+
+ The returned string will be rounded (e.g. 1:1000, not 1:1000.345).
+.. seealso:: toDouble()
  :rtype: str
 %End
-    static double toDouble( const QString &scaleString, bool *ok = 0 );
+
+    static double toDouble( const QString &string, bool *ok = 0 );
 %Docstring
-Helper function to convert a scale string to double
+ Helper function to convert a scale ``string`` to double.
+ The returned value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+ If specified, ``ok`` will be set to true if the string was successfully interpreted as a scale.
+.. seealso:: toString()
  :rtype: float
 %End
 
   signals:
+
     void scaleChanged( double scale );
 %Docstring
-Signal is emitted when *user* has finished editing/selecting a new scale.
+ Emitted when *user* has finished editing/selecting a new scale.
+ The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
 %End
 
   public slots:
+
     void updateScales( const QStringList &scales = QStringList() );
+%Docstring
+ Sets the list of predefined ``scales`` to show in the combobox. List elements
+ are expected to be valid scale strings, such as "1:1000000".
+%End
+
+    void setScale( double scale );
+%Docstring
+ Set the selected scale from a double.
+ The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: scale()
+%End
 
     void setMinScale( double scale );
 %Docstring
- Set the minimum allowed scale.
- Anything scale lower than the minimum scale will automatically
- be converted to the minimum scale.
+ Set the minimum allowed ``scale``. Set to 0 to disable the minimum scale.
+ The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+ Any scale lower than the minimum scale will automatically be converted to the minimum scale.
  Except for 0 which is always allowed.
 %End
 

python/gui/qgsscalerangewidget.sip

@@ -1,49 +1,104 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/qgsscalerangewidget.h                                        *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
 
 class QgsScaleRangeWidget : QWidget
 {
+%Docstring
+ A widget allowing entry of a range of map scales, e.g. minimum scale and maximum scale.
+%End
+
 %TypeHeaderCode
 #include "qgsscalerangewidget.h"
 %End
-
   public:
-    explicit QgsScaleRangeWidget( QWidget *parent /TransferThis/ = 0 );
-    ~QgsScaleRangeWidget();
-
-    //! set the map canvas which will be used for the current scale buttons
-    /**
-     * @brief setMapCanvas set the map canvas which will be used for the current scale buttons
-     * if not set, the buttons are hidden.
-     */
-    void setMapCanvas( QgsMapCanvas *mapCanvas );
 
-    //! return the minimum scale
-    double minimumScale();
+    explicit QgsScaleRangeWidget( QWidget *parent /TransferThis/ = 0 );
+%Docstring
+ Constructor for QgsScaleRangeWidget.
+%End
 
-    //! return the maximum scale
-    double maximumScale();
+    void setMapCanvas( QgsMapCanvas *canvas );
+%Docstring
+ Sets the map ``canvas`` which will be used for the current scale buttons.
+ If not set, the buttons are hidden.
+%End
 
-    //! return the minimum scale denominator ( = 1 / maximum scale )
-    double minimumScaleDenom();
+    double minimumScale() const;
+%Docstring
+ Returns the selected minimum scale, or 0 if minimum scale is not set.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: maximumScale()
+.. seealso:: setMinimumScale()
+ :rtype: float
+%End
 
-    //! return the maximum scale denominator ( = 1 / minimum scale )
-    double maximumScaleDenom();
+    double maximumScale() const;
+%Docstring
+ Returns the selected maximum scale, or 0 if maximum scale is not set.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: minimumScale()
+.. seealso:: setMaximumScale()
+ :rtype: float
+%End
 
-    //! call to reload the project scales and apply them to the 2 scales combo boxes
     void reloadProjectScales();
+%Docstring
+ Call to reload the preset scales from the current project and apply them to the 2 scales combo boxes.
+%End
 
   public slots:
+
     void setMinimumScale( double scale );
+%Docstring
+ Set the minimum ``scale``, or 0 to indicate the minimum is not set.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: minimumScale()
+.. seealso:: setMaximumScale()
+.. seealso:: setScaleRange()
+%End
 
     void setMaximumScale( double scale );
+%Docstring
+ Set the maximum ``scale``, or 0 to indicate the minimum is not set.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: maximumScale()
+.. seealso:: setMinimumScale()
+.. seealso:: setScaleRange()
+%End
 
     void setScaleRange( double min, double max );
+%Docstring
+ Sets the scale range, from ``min`` scale to ``max`` scale.
+ The scale values indicates the scale denominator, e.g. 1000.0 for a 1:1000 map,
+ or 0 to indicate not set.
+.. seealso:: setMinimumScale()
+.. seealso:: setMaximumScale()
+%End
 
   signals:
 
-    /** Emitted when the scale range set in the widget is changed.
-     * @param min minimum scale
-     * @param max maximum scale
-     * @note added in QGIS 2.16
-     */
     void rangeChanged( double min, double max );
+%Docstring
+ Emitted when the scale range set in the widget is changed.
+ The scale values indicates the scale denominator, e.g. 1000.0 for a 1:1000 map,
+ or 0 to indicate not set.
+.. versionadded:: 2.16
+%End
+
 };
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/qgsscalerangewidget.h                                        *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

python/gui/qgsscalevisibilitydialog.sip

@@ -1,30 +1,87 @@
-class QgsScaleVisibilityDialog : QObject
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/qgsscalevisibilitydialog.h                                   *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+
+class QgsScaleVisibilityDialog : QDialog
 {
-%TypeHeaderCode
-#include <qgsscalevisibilitydialog.h>
+%Docstring
+ A dialog allowing users to enter a scale visibility range.
 %End
 
+%TypeHeaderCode
+#include "qgsscalevisibilitydialog.h"
+%End
   public:
-    explicit QgsScaleVisibilityDialog( QWidget *parent /TransferThis/ = 0, const QString &title = QString(), QgsMapCanvas *mapCanvas = 0 );
 
-    //! return if scale visibilty is enabled
-    bool hasScaleVisibility();
+    explicit QgsScaleVisibilityDialog( QWidget *parent /TransferThis/ = 0, const QString &title = QString(), QgsMapCanvas *mapCanvas = 0 );
+%Docstring
+ Constructor for QgsScaleVisibilityDialog, with specified dialog ``title``. The ``mapCanvas`` argument
+ can be used to associate the dialog with a map canvas, allowing use of the current map scale
+ within the dialog.
+%End
 
-    //! return minimum scale (true scale, not scale denominator)
-    double minimumScale();
+    bool hasScaleVisibility() const;
+%Docstring
+ Return true if scale based visibilty is enabled.
+ :rtype: bool
+%End
 
-    //! return maximum scale (true scale, not scale denominator)
-    double maximumScale();
+    double minimumScale() const;
+%Docstring
+ Returns the selected minimum scale, or 0 if minimum scale is not set.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: maximumScale()
+.. seealso:: setMinimumScale()
+ :rtype: float
+%End
 
+    double maximumScale() const;
+%Docstring
+ Returns the selected maximum scale, or 0 if maximum scale is not set.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: minimumScale()
+.. seealso:: setMaximumScale())
+ :rtype: float
+%End
 
   public slots:
-    //! set if scale visibility is enabled
+
     void setScaleVisiblity( bool hasScaleVisibility );
+%Docstring
+ Set whether scale based visibility is enabled.
+.. seealso:: hasScaleVisibility()
+%End
 
-    //! set minimum scale (true scale, not scale denominator)
-    void setMinimumScale( double minScale );
+    void setMinimumScale( double scale );
+%Docstring
+ Set the minimum ``scale``, or 0 to indicate the minimum is not set.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: minimumScale()
+.. seealso:: setMaximumScale()
+%End
+
+    void setMaximumScale( double scale );
+%Docstring
+ Set the maximum ``scale``, or 0 to indicate the minimum is not set.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+.. seealso:: maximumScale()
+.. seealso:: setMinimumScale()
+%End
 
-    //! set maximum scale (true scale, not scale denominator)
-    void setMaximumScale( double maxScale );
 
 };
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/qgsscalevisibilitydialog.h                                   *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/