commit e9719e5416e2301cf2c7cf355d9d10d97ebdd69d
Author:     ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
AuthorDate: Thu Oct 6 15:07:39 2022 +0200
Commit:     ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
CommitDate: Thu Oct 6 15:07:39 2022 +0200

    Update window icon-related doc in platform-specific section.

 documentation/src/osissues.dox | 34 +++++++++++++++++++---------------
 src/Fl_Window.cxx              |  6 ++++--
 2 files changed, 23 insertions(+), 17 deletions(-)

diff --git documentation/src/osissues.dox documentation/src/osissues.dox
index 3232884..e7c88cd 100644
--- documentation/src/osissues.dox
+++ documentation/src/osissues.dox
@@ -390,12 +390,14 @@ before compilation.
 
 \subsection osissues_x_icon Setting the Icon of a Window
 
-FLTK currently supports setting a window's icon \b before it
-is shown using the Fl_Window::icon() method.
-
-void Fl_Window::icon(const void *)
-
-\par
+FLTK recommends to set window icons using these platform-independent methods:
+Fl_Window::icon(const Fl_RGB_Image *) and Fl_Window::icons(const Fl_RGB_Image *[], int).
+See also methods setting default window icons Fl_Window::default_icon(const Fl_RGB_Image *)
+and Fl_Window::default_icons(const Fl_RGB_Image *[], int).
+
+FLTK on X11 also supports, for backward compatibility, use of the deprecated method
+Fl_Window::icon(const void *) as follows :
+<br>
 Sets the icon for the window to the passed pointer. You will
 need to cast the icon \c Pixmap to a \c char* when
 calling this method. To set a monochrome icon using a bitmap compiled
@@ -411,7 +413,6 @@ Pixmap p = XCreateBitmapFromData(fl_display, DefaultRootWindow(fl_display),
 window->icon((const void*)p);
 \endcode
 
-\par
 To use a multi-colored icon, the XPM format and library
 should be used as follows:
 \code
@@ -428,7 +429,6 @@ XpmCreatePixmapFromData(fl_display, DefaultRootWindow(fl_display),
 window->icon((const void *)p);
 \endcode
 
-\par
 When using the Xpm library, be sure to include it in the list
 of libraries that are used to link the application (usually "-lXpm").
 
@@ -446,6 +446,8 @@ of libraries that are used to link the application (usually "-lXpm").
 </TABLE>
 </CENTER>
 
+Any window icon must be set with the above methods before the window is shown.
+
 \subsection osissues_xresources X Resources
 
 When the
@@ -613,13 +615,14 @@ This matches the value of
 
 \subsection osissues_icon_windows Setting the Icon of a Window
 
-FLTK currently supports setting a window's icon *before* it
-is shown using the Fl_Window::icon() method.
+FLTK recommends to set window icons using these platform-independent methods:
+Fl_Window::icon(const Fl_RGB_Image *) and Fl_Window::icons(const Fl_RGB_Image *[], int).
+See also methods setting default window icons Fl_Window::default_icon(const Fl_RGB_Image *)
+and Fl_Window::default_icons(const Fl_RGB_Image *[], int).
 
-void Fl_Window::icon(const void *)
-
-\par
-Sets the icon for the window to the passed pointer. You will
+FLTK on Windows also supports, for backward compatibility, use of the deprecated method
+Fl_Window::icon(const void *) as follows :
+<br>Set the icon for the window to the passed pointer. You will
 need to cast the \c HICON handle to a \c char* when
 calling this method. To set the icon using an icon resource
 compiled with your application use:
@@ -627,7 +630,6 @@ compiled with your application use:
 window->icon((const void *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON)));
 \endcode
 
-\par
 You can also use the \c LoadImage() and related
 functions to load specific resolutions or create the icon from
 bitmap data.
@@ -646,6 +648,8 @@ bitmap data.
 </TABLE>
 </CENTER>
 
+Any window icon must be set with the above methods before the window is shown.
+
 \subsection osissues_msdos_console How to Not Get a MSDOS Console Window
 
 Windows has a really stupid mode switch stored in the
diff --git src/Fl_Window.cxx src/Fl_Window.cxx
index 2d589f4..3a39661 100644
--- src/Fl_Window.cxx
+++ src/Fl_Window.cxx
@@ -385,8 +385,10 @@ const void *Fl_Window::icon() const {
   return pWindowDriver->icon();
 }
 
-/** Sets the current icon window target dependent data.
-  \deprecated in 1.3.3
+/** Platform-specific method to set the window icon usable on Windows and X11 only.
+ See \ref osissues_x_icon for its use under X11, and \ref osissues_icon_windows under Windows.
+  \deprecated in 1.3.3 in favor of platform-independent methods Fl_Window::icon(const Fl_RGB_Image *icon)
+ and Fl_Window::icons(const Fl_RGB_Image *icons[], int count).
  */
 void Fl_Window::icon(const void * ic) {
   pWindowDriver->icon(ic);