From 83daf02f351fe568682c6ec27bef158d45b6cbb5 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Tue, 22 Mar 2022 01:20:10 +0100
Subject: [PATCH] Update wxImageList documentation to mention high DPI concerns

First of all, document that this class is (informally) deprecated.

Also document that the various sizes are expressed in logical pixels.
---
 interface/wx/imaglist.h | 40 +++++++++++++++++++---------------------
 1 file changed, 19 insertions(+), 21 deletions(-)

diff --git a/interface/wx/imaglist.h b/interface/wx/imaglist.h
index 9d60830add..71cd5ad804 100644
--- a/interface/wx/imaglist.h
+++ b/interface/wx/imaglist.h
@@ -34,6 +34,10 @@ enum
     wxImageList is used principally in conjunction with wxTreeCtrl and
     wxListCtrl classes.
 
+    Use of this class is not recommended in the new code as it doesn't support
+    showing DPI-dependent bitmaps. Please use wxWithImages::SetImages() instead
+    of wxWithImages::SetImageList().
+
     @library{wxcore}
     @category{gdi}
 
@@ -51,6 +55,8 @@ public:
         Constructor specifying the image size, whether image masks should be created,
         and the initial size of the list.
 
+        Note that the size is specified in logical pixels.
+
         @param width
             Width of the images in the list.
         @param height
@@ -68,19 +74,17 @@ public:
     /**
         Adds a new image or images using a bitmap and optional mask bitmap.
 
+        The logical size of the bitmap should be the same as the size specified
+        when constructing wxImageList. If the logical width of the bitmap is
+        greater than the image list width, bitmap is split into smaller images
+        of the required width.
+
         @param bitmap
             Bitmap representing the opaque areas of the image.
         @param mask
             Monochrome mask bitmap, representing the transparent areas of the image.
 
         @return The new zero-based image index.
-
-        @remarks The original bitmap or icon is not affected by the Add()
-                 operation, and can be deleted afterwards.
-                 If the bitmap is wider than the images in the list, then the
-                 bitmap will automatically be split into smaller images, each
-                 matching the dimensions of the image list.
-                 This does not apply when adding icons.
     */
     int Add(const wxBitmap& bitmap,
             const wxBitmap& mask = wxNullBitmap);
@@ -88,37 +92,31 @@ public:
     /**
         Adds a new image or images using a bitmap and mask colour.
 
+        The logical size of the bitmap should be the same as the size specified
+        when constructing wxImageList. If the logical width of the bitmap is
+        greater than the image list width, bitmap is split into smaller images
+        of the required width.
+
         @param bitmap
             Bitmap representing the opaque areas of the image.
         @param maskColour
             Colour indicating which parts of the image are transparent.
 
         @return The new zero-based image index.
-
-        @remarks The original bitmap or icon is not affected by the Add()
-                 operation, and can be deleted afterwards.
-                 If the bitmap is wider than the images in the list, then the
-                 bitmap will automatically be split into smaller images, each
-                 matching the dimensions of the image list.
-                 This does not apply when adding icons.
     */
     int Add(const wxBitmap& bitmap, const wxColour& maskColour);
 
     /**
         Adds a new image using an icon.
 
+        The logical size of the icon should be the same as the size specified
+        when constructing wxImageList.
+
         @param icon
             Icon to use as the image.
 
         @return The new zero-based image index.
 
-        @remarks The original bitmap or icon is not affected by the Add()
-                 operation, and can be deleted afterwards.
-                 If the bitmap is wider than the images in the list, then the
-                 bitmap will automatically be split into smaller images, each
-                 matching the dimensions of the image list.
-                 This does not apply when adding icons.
-
         @onlyfor{wxmsw,wxosx}
     */
     int Add(const wxIcon& icon);