Add wxBitmap::GetLogical{Width,Height,Size}()

These functions have better names than the existing GetScaledXXX() ones,
so add them to be able to use them in the new code, even if we still
keep the old ones for compatibility.

docs/doxygen/mainpages/const_cpp.h

@@ -178,7 +178,7 @@ Currently the following symbols exist:
     same apparent size on the display independently of the DPI (this symbol
     only exists in wxWidgets 3.1.6 or later). Note that it should rarely, if
     ever, be necessary to use this symbol directly, functions such as
-    wxWindow::FromDIP() and wxBitmap::GetScaledSize() exist to hide the
+    wxWindow::FromDIP() and wxBitmap::GetLogicalSize() exist to hide the
     differences between the platforms with and without DPI-independent pixels.}
 @itemdef{wxHAS_MEMBER_DEFAULT, Defined if the currently used compiler supports
     C++11 @c =default.}

include/wx/bitmap.h

@@ -198,10 +198,16 @@ public:
 
     // These functions return the corresponding metrics divided by the scale
     // factor on platforms with DPI-independent pixels (e.g. GTK, Mac) and just
-    // the same thing as the non-scaled accessors elsewhere (e.g. MSW).
+    // return the same thing as normal accessors elsewhere (e.g. MSW).
-    double GetScaledWidth() const;
+    double GetLogicalWidth() const;
-    double GetScaledHeight() const;
+    double GetLogicalHeight() const;
-    wxSize GetScaledSize() const;
+    wxSize GetLogicalSize() const;
+
+    // Old synonyms for GetLogicalXXX() functions, prefer the new names in the
+    // new code.
+    double GetScaledWidth() const { return GetLogicalWidth(); }
+    double GetScaledHeight() const { return GetLogicalHeight(); }
+    wxSize GetScaledSize() const { return GetLogicalSize(); }
 
 #if wxUSE_IMAGE
     virtual wxImage ConvertToImage() const = 0;

include/wx/msw/bitmap.h

@@ -191,11 +191,16 @@ public:
     // return the size divided by scale factor
     wxSize GetDIPSize() const;
 
-    // but scaled metrics accessors return the same thing as non-scaled ones,
+    // logical metrics accessors return the same thing as physical ones, just
-    // just as in all the other ports without wxHAS_DPI_INDEPENDENT_PIXELS.
+    // as in all the other ports without wxHAS_DPI_INDEPENDENT_PIXELS.
-    double GetScaledWidth() const;
+    double GetLogicalWidth() const;
-    double GetScaledHeight() const;
+    double GetLogicalHeight() const;
-    wxSize GetScaledSize() const;
+    wxSize GetLogicalSize() const;
+
+    // old synonyms for GetLogicalXXX() functions
+    double GetScaledWidth() const { return GetLogicalWidth(); }
+    double GetScaledHeight() const { return GetLogicalHeight(); }
+    wxSize GetScaledSize() const { return GetLogicalSize(); }
 
     // implementation only from now on
     // -------------------------------

interface/wx/bitmap.h

@@ -549,7 +549,7 @@ public:
         SetScaleFactor()) and returns its physical size divided by this scale
         factor.
 
-        Unlike GetScaledSize(), this function returns the same value under all
+        Unlike GetLogicalSize(), this function returns the same value under all
         platforms and so its result should @e not be used as window or device
         context coordinates.
 
@@ -565,12 +565,56 @@ public:
     static wxList& GetHandlers();
 
     /**
-        Gets the height of the bitmap in pixels.
+        Returns the height of the bitmap in physical pixels.
 
-        @see GetWidth(), GetSize(), GetScaledHeight()
+        @see GetWidth(), GetSize(), GetLogicalHeight()
     */
     virtual int GetHeight() const;
 
+    /**
+        Returns the height of the bitmap in logical pixels.
+
+        See GetLogicalSize() for more information.
+
+        @see GetLogicalWidth(), GetWidth()
+
+        @since 3.1.6
+     */
+    double GetLogicalHeight() const;
+
+    /**
+        Returns the size of the bitmap in logical pixels.
+
+        For the platforms using DPI-independent pixels, i.e. those where @c
+        wxHAS_DPI_INDEPENDENT_PIXELS is defined, such as wxOSX or wxGTK 3,
+        this function returns the physical size of the bitmap, as returned by
+        GetSize(), divided by its scale factor, as returned by
+        GetScaleFactor(), while for the other platforms, it simply returns the
+        same thing as GetSize().
+
+        This ensures that the result of this function is always expressed in
+        the pixel coordinates appropriate for the current platform, i.e. its
+        return value is always in logical pixels, used for window and wxDC
+        coordinates, whether these pixels are the same as physical pixels,
+        which are returned by GetSize(), or not.
+
+        @see GetLogicalWidth(), GetLogicalHeight(), GetSize()
+
+        @since 2.9.5
+     */
+    wxSize GetLogicalSize() const;
+
+    /**
+        Returns the width of the bitmap in logical pixels.
+
+        See GetLogicalSize() for more information.
+
+        @see GetLogicalHeight(), GetWidth()
+
+        @since 3.1.6
+     */
+    double GetLogicalWidth() const;
+
     /**
         Gets the associated mask (if any) which may have been loaded from a file
         or set for the bitmap.
@@ -605,69 +649,59 @@ public:
         pixels are not the same as physical ones, such as wxOSX or wxGTK3, and
         this function always returns 1 under the other platforms.
 
-        @see SetScaleFactor(), GetScaledWidth(), GetScaledHeight(), GetScaledSize()
+        @see SetScaleFactor(), GetLogicalWidth(), GetLogicalHeight(), GetLogicalSize()
 
         @since 2.9.5
      */
     virtual double GetScaleFactor() const;
 
     /**
-        Returns the scaled height of the bitmap.
+        Returns the height of the bitmap in logical pixels.
 
-        See GetScaledSize() for more information.
+        This is an older synonym for GetLogicalHeight(), use the new function
-
+        in the new code.
-        @see GetScaledWidth(), GetHeight()
 
         @since 2.9.5
      */
     double GetScaledHeight() const;
 
     /**
-        Returns the scaled size of the bitmap.
+        Returns the size of the bitmap in logical pixels.
 
-        For the platforms using DPI-independent pixels, i.e. those where @c
+        This is an older synonym for GetLogicalSize(), use the new function in
-        wxHAS_DPI_INDEPENDENT_PIXELS is defined, such as wxOSX or wxGTK 3,
+        the new code.
-        this function returns the physical size of the bitmap, as returned by
-        GetSize(), divided by its scale factor, as returned by
-        GetScaleFactor(), while for the other platforms, it simply returns the
-        same thing as GetSize().
-
-        This ensures that the result of this function is always expressed in
-        the pixel coordinates appropriate for the current platform, i.e. its
-        return value is always in logical pixels, used for window and wxDC
-        coordinates, whether these pixels are the same as physical pixels,
-        which are returned by GetSize(), or not.
-
-        @see GetScaledWidth(), GetScaledHeight(), GetSize()
 
         @since 2.9.5
      */
     wxSize GetScaledSize() const;
 
     /**
-        Returns the scaled width of the bitmap.
+        Returns the width of the bitmap in logical pixels.
 
-        See GetScaledSize() for more information.
+        This is an older synonym for GetLogicalWidth(), use the new function in
-
+        the new code.
-        @see GetScaledHeight(), GetWidth()
 
         @since 2.9.5
      */
     double GetScaledWidth() const;
 
     /**
-        Returns the size of the bitmap in pixels.
+        Returns the size of the bitmap in physical pixels.
+
+        The return value of this function doesn't depend on the scale factor,
+        it is always the physical size of the bitmap, i.e. corresponding to the
+        actual number of pixels in it.
 
         @since 2.9.0
 
-        @see GetHeight(), GetWidth(), GetScaledSize()
+        @see GetHeight(), GetWidth(), GetLogicalSize()
     */
     wxSize GetSize() const;
 
     /**
-        Gets the width of the bitmap in pixels.
+        Returns the width of the bitmap in physical pixels.
 
-        @see GetHeight(), GetSize(), GetScaledWidth()
+        @see GetHeight(), GetSize(), GetLogicalWidth()
     */
     virtual int GetWidth() const;
 

src/common/bmpbase.cpp

@@ -227,34 +227,34 @@ wxSize wxBitmapBase::GetDIPSize() const
 
 #ifdef wxHAS_DPI_INDEPENDENT_PIXELS
 
-double wxBitmapBase::GetScaledWidth() const
+double wxBitmapBase::GetLogicalWidth() const
 {
     return GetWidth() / GetScaleFactor();
 }
 
-double wxBitmapBase::GetScaledHeight() const
+double wxBitmapBase::GetLogicalHeight() const
 {
     return GetHeight() / GetScaleFactor();
 }
 
-wxSize wxBitmapBase::GetScaledSize() const
+wxSize wxBitmapBase::GetLogicalSize() const
 {
-    return wxSize(wxRound(GetScaledWidth()), wxRound(GetScaledHeight()));
+    return wxSize(wxRound(GetLogicalWidth()), wxRound(GetLogicalHeight()));
 }
 
 #else // !wxHAS_DPI_INDEPENDENT_PIXELS
 
-double wxBitmapBase::GetScaledWidth() const
+double wxBitmapBase::GetLogicalWidth() const
 {
     return GetWidth();
 }
 
-double wxBitmapBase::GetScaledHeight() const
+double wxBitmapBase::GetLogicalHeight() const
 {
     return GetHeight();
 }
 
-wxSize wxBitmapBase::GetScaledSize() const
+wxSize wxBitmapBase::GetLogicalSize() const
 {
     return GetSize();
 }

src/msw/bitmap.cpp

@@ -1390,17 +1390,17 @@ wxSize wxBitmap::GetDIPSize() const
     return GetSize() / GetScaleFactor();
 }
 
-double wxBitmap::GetScaledWidth() const
+double wxBitmap::GetLogicalWidth() const
 {
     return GetWidth();
 }
 
-double wxBitmap::GetScaledHeight() const
+double wxBitmap::GetLogicalHeight() const
 {
     return GetHeight();
 }
 
-wxSize wxBitmap::GetScaledSize() const
+wxSize wxBitmap::GetLogicalSize() const
 {
     return GetSize();
 }