From 74424cbeb2c59870ed581e642171b84484371b8d Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Fri, 11 Feb 2022 17:30:57 +0000 Subject: [PATCH] Rename wxBitmap::CreateWithLogicalSize() to CreateWithDIPSize() The new name, recently introduced in 94716fd801 (Add wxBitmap::CreateWithLogicalSize(), 2022-01-22), was perhaps more clear, but also misleading and confusing because the postcondition CreateWithLogicalSize(size, 2).GetLogicalSize() == size was not satisfied under MSW, so rename it once again, and hopefully finally, because the new name is consistent with GetDIPSize() returning the same size. Also try to improve the documentation a bit more. --- docs/doxygen/overviews/high_dpi.md | 8 +++---- include/wx/bitmap.h | 16 +++++++------- include/wx/msw/bitmap.h | 18 +++++++-------- interface/wx/bitmap.h | 35 +++++++++++++++++------------- src/common/animatecmn.cpp | 2 +- src/common/dcbufcmn.cpp | 2 +- src/msw/bitmap.cpp | 2 +- src/osx/cocoa/toolbar.mm | 2 +- src/osx/cocoa/utils.mm | 4 ++-- src/osx/core/bitmap.cpp | 4 ++-- src/propgrid/propgrid.cpp | 4 ++-- src/stc/PlatWX.cpp | 2 +- tests/graphics/bmpbundle.cpp | 2 +- 13 files changed, 53 insertions(+), 48 deletions(-) diff --git a/docs/doxygen/overviews/high_dpi.md b/docs/doxygen/overviews/high_dpi.md index 4d6337ae75..4d33ed102a 100644 --- a/docs/doxygen/overviews/high_dpi.md +++ b/docs/doxygen/overviews/high_dpi.md @@ -172,10 +172,10 @@ use "Logical", "Physical" or "DIP" in their names, the only exceptions are: - Size passed to wxBitmap constructors taking one, as well as the size returned by wxBitmap::GetWidth() and wxBitmap::GetHeight() is in physical pixels. You - can use wxBitmap::CreateWithLogicalSize() and wxBitmap::GetLogicalWidth(), - wxBitmap::GetLogicalHeight() and wxBitmap::GetLogicalSize() to use or get the - size in logical pixels which must be used in any computations involving the - sizes expressed in logical units. + can use wxBitmap::CreateWithDIPSize() and wxBitmap::GetDIPSize() or + wxBitmap::GetLogicalSize() to use or get the size in DPI-independent or + logical pixels (notably, the latter must be used in any computations + involving the sizes expressed in logical units). - Similarly, the size returned by wxBitmapBundle::GetPreferredBitmapSizeFor() is in physical pixels, but wxBitmapBundle::GetPreferredLogicalSizeFor() can be used to retrieve the same value in logical units. diff --git a/include/wx/bitmap.h b/include/wx/bitmap.h index 74c23a818c..f5ccd8397b 100644 --- a/include/wx/bitmap.h +++ b/include/wx/bitmap.h @@ -178,13 +178,13 @@ public: virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH) = 0; virtual bool Create(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH) = 0; - bool CreateWithLogicalSize(const wxSize& sz, - double scale, - int depth = wxBITMAP_SCREEN_DEPTH) + bool CreateWithDIPSize(const wxSize& sz, + double scale, + int depth = wxBITMAP_SCREEN_DEPTH) { return DoCreate(sz, scale, depth); } - bool CreateWithLogicalSize(int width, int height, - double scale, - int depth = wxBITMAP_SCREEN_DEPTH) + bool CreateWithDIPSize(int width, int height, + double scale, + int depth = wxBITMAP_SCREEN_DEPTH) { return DoCreate(wxSize(width, height), scale, depth); } virtual int GetHeight() const = 0; @@ -211,10 +211,10 @@ public: double GetLogicalHeight() const; wxSize GetLogicalSize() const; - // Old synonyms for CreateWithLogicalSize() and GetLogicalXXX() functions, + // Old synonyms for CreateWithDIPSize() and GetLogicalXXX() functions, // prefer the new names in the new code. bool CreateScaled(int w, int h, int d, double logicalScale) - { return CreateWithLogicalSize(w, h, logicalScale, d); } + { return CreateWithDIPSize(w, h, logicalScale, d); } double GetScaledWidth() const { return GetLogicalWidth(); } double GetScaledHeight() const { return GetLogicalHeight(); } wxSize GetScaledSize() const { return GetLogicalSize(); } diff --git a/include/wx/msw/bitmap.h b/include/wx/msw/bitmap.h index 81f981848f..90401db1e2 100644 --- a/include/wx/msw/bitmap.h +++ b/include/wx/msw/bitmap.h @@ -159,13 +159,13 @@ public: virtual bool Create(int width, int height, const wxDC& dc); virtual bool Create(const void* data, wxBitmapType type, int width, int height, int depth = 1); - bool CreateWithLogicalSize(const wxSize& sz, - double scale, - int depth = wxBITMAP_SCREEN_DEPTH); - bool CreateWithLogicalSize(int width, int height, - double scale, - int depth = wxBITMAP_SCREEN_DEPTH) - { return CreateWithLogicalSize(wxSize(width, height), scale, depth); } + bool CreateWithDIPSize(const wxSize& sz, + double scale, + int depth = wxBITMAP_SCREEN_DEPTH); + bool CreateWithDIPSize(int width, int height, + double scale, + int depth = wxBITMAP_SCREEN_DEPTH) + { return CreateWithDIPSize(wxSize(width, height), scale, depth); } virtual bool LoadFile(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE); virtual bool SaveFile(const wxString& name, wxBitmapType type, const wxPalette *cmap = NULL) const; @@ -191,9 +191,9 @@ public: void UseAlpha(bool use = true); void ResetAlpha() { UseAlpha(false); } - // old synonyms for CreateWithLogicalSize() and GetLogicalXXX() functions + // old synonyms for CreateWithDIPSize() and GetLogicalXXX() functions bool CreateScaled(int w, int h, int d, double logicalScale) - { return CreateWithLogicalSize(wxSize(w, h), logicalScale, d); } + { return CreateWithDIPSize(wxSize(w, h), logicalScale, d); } double GetScaledWidth() const { return GetLogicalWidth(); } double GetScaledHeight() const { return GetLogicalHeight(); } wxSize GetScaledSize() const { return GetLogicalSize(); } diff --git a/interface/wx/bitmap.h b/interface/wx/bitmap.h index e9ffc3a4db..7f06e9cec6 100644 --- a/interface/wx/bitmap.h +++ b/interface/wx/bitmap.h @@ -460,16 +460,21 @@ public: bool Create(int width, int height, const wxDC& dc); /** - Create a bitmap specifying its size in logical pixels and the scale - factor to use. + Create a bitmap specifying its size in DPI-independent pixels and the + scale factor to use. The physical size of the bitmap is obtained by multiplying the given - size in logical pixels by @a scale and rounding it to the closest - integer. + @a size by @a scale and rounding it to the closest integer. + + After using this function the following postconditions are true: + + - GetSize() returns @a size multiplied by @a scale + - GetDIPSize() returns @a size + - GetScaleFactor() returns @a scale @param size - The size of the bitmap in logical pixels. Both width and height - must be strictly positive. + The size of the bitmap in DPI-independent pixels. Both width and + height must be strictly positive. @param scale Scale factor used by the bitmap, see SetScaleFactor(). @param depth @@ -479,19 +484,19 @@ public: @since 3.1.6 */ - bool CreateWithLogicalSize(const wxSize& size, - double scale, - int depth = wxBITMAP_SCREEN_DEPTH); + bool CreateWithDIPSize(const wxSize& size, + double scale, + int depth = wxBITMAP_SCREEN_DEPTH); /// @overload - bool CreateWithLogicalSize(int width, int height, - double scale, - int depth = wxBITMAP_SCREEN_DEPTH); + bool CreateWithDIPSize(int width, int height, + double scale, + int depth = wxBITMAP_SCREEN_DEPTH); /** Create a bitmap with a scale factor. - This is an older synonym for CreateWithLogicalSize(), use the new + This is an older synonym for CreateWithDIPSize(), use the new function in the new code. @param width @@ -577,7 +582,7 @@ public: Returns the size of bitmap in DPI-independent units. This assumes that the bitmap was created using the value of scale - factor corresponding to the current DPI (see CreateWithLogicalSize() + factor corresponding to the current DPI (see CreateWithDIPSize() and SetScaleFactor()) and returns its physical size divided by this scale factor. @@ -895,7 +900,7 @@ public: which logical and physical pixels differ (i.e. wxOSX and wxGTK3, but not wxMSW). - When creating a new bitmap, CreateWithLogicalSize() can be used to + When creating a new bitmap, CreateWithDIPSize() can be used to specify the correct scale factor from the beginning. @since 3.1.6 diff --git a/src/common/animatecmn.cpp b/src/common/animatecmn.cpp index ecb9ea5b2e..39c0fd4ae5 100644 --- a/src/common/animatecmn.cpp +++ b/src/common/animatecmn.cpp @@ -148,7 +148,7 @@ void wxAnimationCtrlBase::UpdateStaticImage() m_bmpStaticReal.GetLogicalHeight() != sz.GetHeight()) { // need to (re)create m_bmpStaticReal - if (!m_bmpStaticReal.CreateWithLogicalSize(sz, + if (!m_bmpStaticReal.CreateWithDIPSize(sz, bmpCurrent.GetScaleFactor(), bmpCurrent.GetDepth())) { diff --git a/src/common/dcbufcmn.cpp b/src/common/dcbufcmn.cpp index 4f6e83c527..0dbfcf48de 100644 --- a/src/common/dcbufcmn.cpp +++ b/src/common/dcbufcmn.cpp @@ -84,7 +84,7 @@ private: // we must always return a valid bitmap but creating a bitmap of // size 0 would fail, so create a 1*1 bitmap in this case - buffer->CreateWithLogicalSize(wxMax(w, 1), wxMax(h, 1), scale); + buffer->CreateWithDIPSize(wxMax(w, 1), wxMax(h, 1), scale); return buffer; } diff --git a/src/msw/bitmap.cpp b/src/msw/bitmap.cpp index fa78d2b1b0..91e1c281b4 100644 --- a/src/msw/bitmap.cpp +++ b/src/msw/bitmap.cpp @@ -763,7 +763,7 @@ bool wxBitmap::Create(int width, int height, const wxDC& dc) return false; } -bool wxBitmap::CreateWithLogicalSize(const wxSize& size, double scale, int depth) +bool wxBitmap::CreateWithDIPSize(const wxSize& size, double scale, int depth) { if ( !Create(size*scale, depth) ) return false; diff --git a/src/osx/cocoa/toolbar.mm b/src/osx/cocoa/toolbar.mm index 7d684e9395..21b2a564be 100644 --- a/src/osx/cocoa/toolbar.mm +++ b/src/osx/cocoa/toolbar.mm @@ -599,7 +599,7 @@ void wxToolBarTool::UpdateImages() // TODO CS this should use the best current representation, or optionally iterate through all wxSize sz = m_bmpNormal.GetDefaultSize(); m_alternateBitmap = wxBitmap(); - m_alternateBitmap.Create(sz.x, sz.y, -1); // TODO CS m_alternateBitmap.CreateWithLogicalSize(sz, m_bmpNormal.GetScaleFactor()); + m_alternateBitmap.Create(sz.x, sz.y, -1); // TODO CS m_alternateBitmap.CreateWithDIPSize(sz, m_bmpNormal.GetScaleFactor()); m_alternateBitmap.UseAlpha(); wxMemoryDC dc; diff --git a/src/osx/cocoa/utils.mm b/src/osx/cocoa/utils.mm index e7de491337..61d829f954 100644 --- a/src/osx/cocoa/utils.mm +++ b/src/osx/cocoa/utils.mm @@ -559,7 +559,7 @@ wxBitmap wxWindowDCImpl::DoGetAsBitmap(const wxRect *subrect) const const wxSize bitmapSize(subrect ? subrect->GetSize() : m_window->GetSize()); wxBitmap bitmap; - bitmap.CreateWithLogicalSize(bitmapSize, m_contentScaleFactor); + bitmap.CreateWithDIPSize(bitmapSize, m_contentScaleFactor); NSView* view = (NSView*) m_window->GetHandle(); if ( [view isHiddenOrHasHiddenAncestor] == NO ) @@ -591,7 +591,7 @@ wxBitmap wxWindowDCImpl::DoGetAsBitmap(const wxRect *subrect) const CGRect r = CGRectMake( 0 , 0 , CGImageGetWidth(cgImageRef) , CGImageGetHeight(cgImageRef) ); - // The bitmap created by wxBitmap::CreateWithLogicalSize() above is scaled, + // The bitmap created by wxBitmap::CreateWithDIPSize() above is scaled, // so we need to adjust the coordinates for it. r.size.width /= m_contentScaleFactor; r.size.height /= m_contentScaleFactor; diff --git a/src/osx/core/bitmap.cpp b/src/osx/core/bitmap.cpp index 11aa805426..5b1f113755 100644 --- a/src/osx/core/bitmap.cpp +++ b/src/osx/core/bitmap.cpp @@ -961,7 +961,7 @@ wxBitmap wxBitmap::GetSubBitmap(const wxRect &rect) const wxBitmap ret; double scale = GetScaleFactor(); - ret.CreateWithLogicalSize( rect.GetSize(), scale, GetDepth() ); + ret.CreateWithDIPSize( rect.GetSize(), scale, GetDepth() ); wxASSERT_MSG( ret.IsOk(), wxT("GetSubBitmap error") ); if ( HasAlpha() ) ret.UseAlpha() ; @@ -1039,7 +1039,7 @@ bool wxBitmap::Create(int w, int h, int d) bool wxBitmap::Create(int w, int h, const wxDC& dc) { double factor = dc.GetContentScaleFactor(); - return CreateWithLogicalSize(w, h, factor); + return CreateWithDIPSize(w, h, factor); } bool wxBitmap::DoCreate(const wxSize& size, double scale, int d) diff --git a/src/propgrid/propgrid.cpp b/src/propgrid/propgrid.cpp index 6befa57fa7..c916656054 100644 --- a/src/propgrid/propgrid.cpp +++ b/src/propgrid/propgrid.cpp @@ -4621,7 +4621,7 @@ void wxPropertyGrid::OnResize( wxSizeEvent& event ) int w = wxMax(width, 250); int h = wxMax(height + dblh, 400); m_doubleBuffer = new wxBitmap; - m_doubleBuffer->CreateWithLogicalSize( w, h, scaleFactor ); + m_doubleBuffer->CreateWithDIPSize( w, h, scaleFactor ); } else { @@ -4635,7 +4635,7 @@ void wxPropertyGrid::OnResize( wxSizeEvent& event ) if ( h < (height+dblh) ) h = height + dblh; delete m_doubleBuffer; m_doubleBuffer = new wxBitmap; - m_doubleBuffer->CreateWithLogicalSize( w, h, scaleFactor ); + m_doubleBuffer->CreateWithDIPSize( w, h, scaleFactor ); } } } diff --git a/src/stc/PlatWX.cpp b/src/stc/PlatWX.cpp index 44067dba6a..0ac2ae46ab 100644 --- a/src/stc/PlatWX.cpp +++ b/src/stc/PlatWX.cpp @@ -299,7 +299,7 @@ void SurfaceImpl::InitPixMap(int width, int height, Surface *surface, WindowID w if (width < 1) width = 1; if (height < 1) height = 1; bitmap = new wxBitmap(); - bitmap->CreateWithLogicalSize(width, height,(GETWIN(winid))->GetContentScaleFactor()); + bitmap->CreateWithDIPSize(width, height,(GETWIN(winid))->GetContentScaleFactor()); mdc->SelectObject(*bitmap); } diff --git a/tests/graphics/bmpbundle.cpp b/tests/graphics/bmpbundle.cpp index 38c1622161..176515624f 100644 --- a/tests/graphics/bmpbundle.cpp +++ b/tests/graphics/bmpbundle.cpp @@ -173,7 +173,7 @@ TEST_CASE("BitmapBundle::Scale", "[bmpbundle][scale]") // setting scale factor works correctly for bitmaps, as wxBitmapBundle does // this internally. wxBitmap bmp; - bmp.CreateWithLogicalSize(8, 8, 2); + bmp.CreateWithDIPSize(8, 8, 2); #ifdef wxHAS_DPI_INDEPENDENT_PIXELS CHECK( bmp.GetLogicalSize() == wxSize(8, 8) ); #endif