commit 84c09ae7b2de0ad9142551ebd4f53a7e113902b4
Author:     Greg Ercolano <erco@seriss.com>
AuthorDate: Fri Nov 26 13:13:58 2021 -0800
Commit:     Greg Ercolano <erco@seriss.com>
CommitDate: Fri Nov 26 13:13:58 2021 -0800

    Fixes #297 - improvements for icon.cxx + icon() docs

 src/Fl_Window.cxx |  3 +++
 test/icon.cxx     | 24 +++++++++++++++++-------
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git src/Fl_Window.cxx src/Fl_Window.cxx
index 26e259b..0ca39a5 100644
--- src/Fl_Window.cxx
+++ src/Fl_Window.cxx
@@ -333,6 +333,9 @@ void Fl_Window::default_icons(const Fl_RGB_Image *icons[], int count) {
   default window icon (see links below) or the system default icon will
   be used.
 
+  This method makes an internal copy of the \p icon pixel buffer,
+  so once set, the Fl_RGB_Image instance can be freed by the caller.
+
   \param[in] icon icon for this window, NULL to reset window icon.
 
   \see Fl_Window::default_icon(const Fl_RGB_Image *)
diff --git test/icon.cxx test/icon.cxx
index f3c60c8..1c9c507 100644
--- test/icon.cxx
+++ test/icon.cxx
@@ -1,5 +1,5 @@
 //
-// Icon test program for the Fast Light Tool Kit (FLTK).
+// Window icon test program for the Fast Light Tool Kit (FLTK).
 //
 // Copyright 1998-2021 by Bill Spitzak and others.
 //
@@ -23,13 +23,20 @@ static Fl_Double_Window *win;
 
 void choice_cb(Fl_Widget *, void *v) {
   Fl_Color c = (Fl_Color)fl_uint(v);
-  static uchar buffer[32*32*3];         // static: issue #296
-  Fl_RGB_Image icon(buffer, 32, 32, 3);
-  icon.color_average(c, 0.0);
-  win->icon(&icon);
+  if ( c != 0 ) {
+    // choice was "Red", "Green"..
+    static uchar buffer[32*32*3];         // static: issue #296
+    Fl_RGB_Image rgbicon(buffer, 32, 32, 3);
+    rgbicon.color_average(c, 0.0);
+    win->icon(&rgbicon);                  // once assigned, 'rgbicon' can go out of scope
+  } else {
+    // choice was "None"..
+    win->icon((Fl_RGB_Image*)0);          // reset window icon
+  }
 }
 
 Fl_Menu_Item choices[] = {
+  {"None",  0, choice_cb, fl_voidptr(0)},
   {"Red",   0, choice_cb, fl_voidptr(FL_RED)},
   {"Green", 0, choice_cb, fl_voidptr(FL_GREEN)},
   {"Blue",  0, choice_cb, fl_voidptr(FL_BLUE)},
@@ -37,15 +44,18 @@ Fl_Menu_Item choices[] = {
 };
 
 int main(int argc, char **argv) {
-  Fl_Double_Window window(400,300);
+  Fl_Double_Window window(400,300, "FLTK Window Icon Test");
   win = &window;
 
-  Fl_Choice choice(80,100,200,25,"Colour:");
+  Fl_Choice choice(120,100,200,25,"Window icon:");
   choice.menu(choices);
   choice.callback(choice_cb);
   choice.when(FL_WHEN_RELEASE|FL_WHEN_NOT_CHANGED);
+  choice.tooltip("Sets the application icon for window manager. "
+                 "Affects e.g. titlebar, toolbar, Dock, Alt-Tab..");
 
   window.end();
   window.show(argc,argv);
+  choice.do_callback();         // make default take effect
   return Fl::run();
 }