Clarify in doxygen what scale values represent

qgis · Jun 8, 2017 · 463e722 · 463e722
1 parent 08a9bcb
commit 463e722
Show file tree

Hide file tree

Showing 11 changed files with 33 additions and 24 deletions.
diff --git a/python/core/qgsmaplayer.sip b/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()

diff --git a/python/gui/qgsmapcanvas.sip b/python/gui/qgsmapcanvas.sip
@@ -141,9 +141,10 @@ Constructor
  :rtype: int
 %End
 
-    double scale();
+    double scale() const;
 %Docstring
-Get the last reported scale of the canvas
+ Returns the last reported scale of the canvas.
+ The ``scale`` value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
  :rtype: float
 %End
 
@@ -405,7 +406,8 @@ set wheel zoom factor (should be greater than 1)
 
     void zoomScale( double scale );
 %Docstring
-Zoom to a specific scale
+ Zooms the canvas to a specific ``scale``.
+ The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
 %End
 
     void zoomByFactor( double scaleFactor, const QgsPointXY *center = 0 );

diff --git a/src/app/qgisapp.cpp b/src/app/qgisapp.cpp
@@ -8734,8 +8734,7 @@ void QgisApp::saveLastMousePosition( const QgsPointXY &p )
 
 void QgisApp::showScale( double scale )
 {
-  // Why has MapCanvas the scale inverted?
-  mScaleWidget->setScale( 1.0 / scale );
+  mScaleWidget->setScale( scale );
 
   // Not sure if the lines below do anything meaningful /Homann
   if ( mScaleWidget->width() > mScaleWidget->minimumWidth() )

diff --git a/src/app/qgsstatusbarscalewidget.cpp b/src/app/qgsstatusbarscalewidget.cpp
@@ -80,7 +80,7 @@ QgsStatusBarScaleWidget::~QgsStatusBarScaleWidget()
 void QgsStatusBarScaleWidget::setScale( double scale )
 {
   mScale->blockSignals( true );
-  mScale->setScale( 1.0 / scale );
+  mScale->setScale( scale );
   mScale->blockSignals( false );
 }
 

diff --git a/src/app/qgsstatusbarscalewidget.h b/src/app/qgsstatusbarscalewidget.h
@@ -44,8 +44,8 @@ class APP_EXPORT QgsStatusBarScaleWidget : public QWidget
     virtual ~QgsStatusBarScaleWidget();
 
     /**
-     * \brief setScale set the selected scale from double
-     * \param scale
+     * Set the selected \a scale from double.
+     * The \a scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
      */
     void setScale( double scale );
 

diff --git a/src/core/qgsmaplayer.h b/src/core/qgsmaplayer.h
@@ -679,8 +679,8 @@ class CORE_EXPORT QgsMapLayer : public QObject
      */
     QgsMapLayerStyleManager *styleManager() const;
 
-    /** 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 \a scale.
+     *  The \a scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
      * \returns true if the layer is visible at the given scale.
      * \since QGIS 2.16
      * \see minimumScale()

diff --git a/src/gui/qgsmapcanvas.cpp b/src/gui/qgsmapcanvas.cpp
@@ -277,10 +277,10 @@ void QgsMapCanvas::setCurrentLayer( QgsMapLayer *layer )
   emit currentLayerChanged( layer );
 }
 
-double QgsMapCanvas::scale()
+double QgsMapCanvas::scale() const
 {
   return mapSettings().scale();
-} // scale
+}
 
 bool QgsMapCanvas::isDrawing()
 {

diff --git a/src/gui/qgsmapcanvas.h b/src/gui/qgsmapcanvas.h
@@ -172,8 +172,11 @@ class GUI_EXPORT QgsMapCanvas : public QGraphicsView
     //! \since QGIS 2.4
     int mapUpdateInterval() const;
 
-    //! Get the last reported scale of the canvas
-    double scale();
+    /**
+     * Returns the last reported scale of the canvas.
+     * The \a scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+     */
+    double scale() const;
 
     //! Returns the mapUnitsPerPixel (map units per pixel) for the canvas
     double mapUnitsPerPixel() const;
@@ -365,7 +368,10 @@ class GUI_EXPORT QgsMapCanvas : public QGraphicsView
     //! set wheel zoom factor (should be greater than 1)
     void setWheelFactor( double factor );
 
-    //! Zoom to a specific scale
+    /**
+     * Zooms the canvas to a specific \a scale.
+     * The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
+     */
     void zoomScale( double scale );
 
     //! Zoom with the factor supplied. Factor > 1 zooms out, interval (0,1) zooms in

diff --git a/src/gui/qgstextformatwidget.cpp b/src/gui/qgstextformatwidget.cpp
@@ -1227,7 +1227,7 @@ void QgsTextFormatWidget::onSubstitutionsChanged( const QgsStringReplacementColl
 
 void QgsTextFormatWidget::previewScaleChanged( double scale )
 {
-  lblFontPreview->setScale( 1.0 / scale );
+  lblFontPreview->setScale( scale );
 }
 
 void QgsTextFormatWidget::updateSvgWidgets( const QString &svgPath )

diff --git a/src/gui/qgstextpreview.cpp b/src/gui/qgstextpreview.cpp
@@ -19,7 +19,6 @@
 
 QgsTextPreview::QgsTextPreview( QWidget *parent )
   : QLabel( parent )
-  , mScale( -1 )
   , mMapUnits( QgsUnitTypes::DistanceMeters )
 {
   // initially use a basic transform with no scale
@@ -78,7 +77,7 @@ void QgsTextPreview::updateContext()
 {
   if ( mScale >= 0 )
   {
-    QgsMapToPixel newCoordXForm = QgsMapToPixel::fromScale( mScale, mMapUnits, QgsApplication::desktop()->logicalDpiX() );
+    QgsMapToPixel newCoordXForm = QgsMapToPixel::fromScale( 1.0 / mScale, mMapUnits, QgsApplication::desktop()->logicalDpiX() );
     mContext.setMapToPixel( newCoordXForm );
   }
   update();

diff --git a/src/gui/qgstextpreview.h b/src/gui/qgstextpreview.h
@@ -63,14 +63,17 @@ class GUI_EXPORT QgsTextPreview : public QLabel
      */
     QgsTextFormat format() const { return mFormat; }
 
-    /** Sets the scale to use for previewing format sizes in map units.
-     * \param scale preview map scale
+    /**
+     * Sets the \a scale to use for previewing format sizes in map units.
+     * The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
      * \see scale()
      * \see setMapUnits()
      */
     void setScale( double scale );
 
-    /** Returns the scale used for previewing format sizes in map units.
+    /**
+     * Returns the scale used for previewing format sizes in map units.
+     * The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
      * \see setScale()
      * \see mapUnits()
      */
@@ -92,7 +95,7 @@ class GUI_EXPORT QgsTextPreview : public QLabel
   private:
     QgsTextFormat mFormat;
     QgsRenderContext mContext;
-    double mScale;
+    double mScale = -1;
     QgsUnitTypes::DistanceUnit mMapUnits;
     void updateContext();
 };