Add close buttons for individual tabs in Fl_Tabs (#628)

Add close buttons for Fl_Tabs
Introducing callback reasons
FLUID shows all FL_WHEN_... options
Adding Fl_Tabs overflow types
Improved test/tabs to show new features

14 files changed, 165 insertions, 41 deletions

diff --git a/FL/Enumerations.H b/FL/Enumerations.H
index 9d40152d6..928f09612 100644
--- a/FL/Enumerations.H
+++ b/FL/Enumerations.H
@@ -1,7 +1,7 @@
 //
 // Enumerations for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2022 by Bill Spitzak and others.
+// Copyright 1998-2023 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -415,22 +415,51 @@ enum Fl_Event { // events
 /*@{*/
 /** These constants determine when a callback is performed.
 
-    \see Fl_Widget::when();
-    \todo doxygen comments for values are incomplete and maybe wrong or unclear
+    Fl_When is a bit field. Some values are merely shorcuts for common bit
+    combinations. New flags may be added in the future, so it's important to
+    mask the required bit when reading via \p when().
+
+    \note Some widgets may not fully suppoert \p FL_WHEN_... flags.
+
+    \see Fl_Widget::when(), Fl::callback_reason(), Fl_Callback_Reason, Fl_Widget::do_callback()
  */
 enum Fl_When { // Fl_Widget::when():
-  FL_WHEN_NEVER             = 0, ///< Never call the callback
-  FL_WHEN_CHANGED           = 1, ///< Do the callback only when the widget value changes
-  FL_WHEN_NOT_CHANGED       = 2, ///< Do the callback whenever the user interacts with the widget
-  FL_WHEN_RELEASE           = 4, ///< Do the callback when the button or key is released and the value changes
-  FL_WHEN_RELEASE_ALWAYS    = 6, ///< Do the callback when the button or key is released, even if the value doesn't change
-  FL_WHEN_ENTER_KEY         = 8, ///< Do the callback when the user presses the ENTER key and the value changes
-  FL_WHEN_ENTER_KEY_ALWAYS  =10, ///< Do the callback when the user presses the ENTER key, even if the value doesn't change
-  FL_WHEN_ENTER_KEY_CHANGED =11  ///< = (FL_WHEN_ENTER_KEY | FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED)
+  FL_WHEN_NEVER             =  0, ///< Never call the callback
+  FL_WHEN_CHANGED           =  1, ///< Do the callback only when the widget value changes
+  FL_WHEN_NOT_CHANGED       =  2, ///< Do the callback whenever the user interacts with the widget
+  FL_WHEN_RELEASE           =  4, ///< Do the callback when the button or key is released and the value changes
+  FL_WHEN_RELEASE_ALWAYS    =  6, ///< Do the callback when the button or key is released, even if the value doesn't change
+  FL_WHEN_ENTER_KEY         =  8, ///< Do the callback when the user presses the ENTER key and the value changes
+  FL_WHEN_ENTER_KEY_ALWAYS  = 10, ///< Do the callback when the user presses the ENTER key, even if the value doesn't change
+  FL_WHEN_ENTER_KEY_CHANGED = 11, ///< Do callbacks whether the value changed or not, and when the ENTER key is pressed
+  FL_WHEN_CLOSED            = 16  ///< Do the callback when a child of Fl_Tabs is closed
 };
-
 /*@}*/          // group: When Conditions
 
+
+/** \name Callback Reasons */
+/*@{*/
+/** These constants describe why a callback is performed.
+
+    \see Fl::callback_reason(), Fl_Widget::when(), Fl_When
+ */
+enum Fl_Callback_Reason {
+  FL_REASON_UNKNOWN=0,    ///< unknown or unset reason
+  FL_REASON_SELECTED,     ///< an item was selected
+  FL_REASON_DESELECTED,   ///< an item was de-selected
+  FL_REASON_RESELECTED,   ///< an item was re-selected (double-clicked).
+  FL_REASON_OPENED,       ///< an item was opened
+  FL_REASON_CLOSED,       ///< an item was closed
+  FL_REASON_DRAGGED,      ///< an item was dragged into a new place
+  FL_REASON_CANCELLED,    ///< a dialog was cancelled
+  FL_REASON_CHANGED,      ///< the value of the widget was modified
+  FL_REASON_GOT_FOCUS,    ///< a widget received focus
+  FL_REASON_LOST_FOCUS,   ///< a widget lost focus
+  FL_REASON_RELEASED,     ///< the mouse button was released
+};
+/*@}*/          // group: Callback Reasons
+
+
 /** \name Mouse and Keyboard Events
 
     This and the following constants define the non-ASCII keys on the
diff --git a/FL/Fl.H b/FL/Fl.H
index 8f1e0bf44..6f51181a4 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -202,6 +202,7 @@ public: // should be private!
   static void *e_clipboard_data;
   static const char *e_clipboard_type;
   static Fl_Event_Dispatch e_dispatch;
+  static Fl_Callback_Reason callback_reason_;
   static Fl_Widget* belowmouse_;
   static Fl_Widget* pushed_;
   static Fl_Widget* focus_;
@@ -847,6 +848,7 @@ public:
   static void remove_system_handler(Fl_System_Handler h);
   static void event_dispatch(Fl_Event_Dispatch d);
   static Fl_Event_Dispatch event_dispatch();
+  static Fl_Callback_Reason callback_reason();
   /** @} */
 
   /** \defgroup  fl_clipboard  Selection & Clipboard functions
diff --git a/FL/Fl_Browser_.H b/FL/Fl_Browser_.H
index 78d242206..03550b67a 100644
--- a/FL/Fl_Browser_.H
+++ b/FL/Fl_Browser_.H
@@ -53,6 +53,12 @@
   accessing image data or doing stat() on a file or doing some
   other slow operation.
 
+  Callbacks are called when the value changes with \p FL_REASON_CHANGED.
+  If \p FL_WHEN_RELEASE is set, callbacks are called when the mouse button is
+  released with \p FL_REASON_CHANGED or \p FL_REASON_RESELECTED if the selection
+  did not change. If \p FL_WHEN_ENTER_KEY is set, callbacks are also called when
+  key presses or double clicks change the selection.
+
 Keyboard navigation of browser items
 ------------------------------------
 
diff --git a/FL/Fl_Button.H b/FL/Fl_Button.H
index 38d804070..14e515d1b 100644
--- a/FL/Fl_Button.H
+++ b/FL/Fl_Button.H
@@ -65,10 +65,15 @@ class Fl_Widget_Tracker;
   being \c FL_WHEN_RELEASE:
   \li \c 0: The callback is not done, instead changed() is turned on.
   \li \c FL_WHEN_RELEASE: The callback is done after the user successfully
-         clicks the button, or when a shortcut is typed.
+         clicks the button, or when a shortcut is typed. The reason is
+         \p FL_REASON_RELEASED.
   \li \c FL_WHEN_CHANGED: The callback is done each time the value() changes
          (when the user pushes and releases the button, and as the mouse is
-         dragged around in and out of the button).
+         dragged around in and out of the button). The reason is set to
+         \p FL_REASON_CHANGED
+  \li \c FL_WHEN_NOT_CHANGED: The callback is done when the mouse button is
+         released, but the value did not changed. The reason is set to
+         \p FL_REASON_SELECTED
 */
 
 class FL_EXPORT Fl_Button : public Fl_Widget {
diff --git a/FL/Fl_Color_Chooser.H b/FL/Fl_Color_Chooser.H
index 1aa569c11..29baecec7 100644
--- a/FL/Fl_Color_Chooser.H
+++ b/FL/Fl_Color_Chooser.H
@@ -104,6 +104,9 @@ public:
   available colors, leaving you no space to exactly represent the color the
   user picks! You can however use fl_rectf() to fill a region with a simulated
   color using dithering.
+
+  Callback reasons can be \c FL_REASON_DRAGGED, \c FL_REASON_CHANGED, or
+  \c FL_REASON_RESELECTED.
  */
 /** @} */
 class FL_EXPORT Fl_Color_Chooser : public Fl_Group {
diff --git a/FL/Fl_Group.H b/FL/Fl_Group.H
index 793f2c854..1e21b20ba 100644
--- a/FL/Fl_Group.H
+++ b/FL/Fl_Group.H
@@ -47,6 +47,11 @@ class Fl_Rect;
   \endcode
   ..and this will trigger proper scheduling of the widget's removal
   from its parent group.
+
+  If used as a child of \p Fl_Tabs, setting \p when(FL_WHEN_CLOSED) will
+  enable the Close button in the corresponding tab. If the user clicks the
+  Close button, the callback of this group will be called with the callback
+  reason \p FL_REASON_CLOSED.
 */
 class FL_EXPORT Fl_Group : public Fl_Widget {
 
diff --git a/FL/Fl_Input_.H b/FL/Fl_Input_.H
index 0ec9b09ab..7d3f90cc3 100644
--- a/FL/Fl_Input_.H
+++ b/FL/Fl_Input_.H
@@ -200,7 +200,7 @@ protected:
   int handletext(int e, int, int, int, int);
 
   /* Check the when() field and do a callback if indicated. */
-  void maybe_do_callback();
+  void maybe_do_callback(Fl_Callback_Reason reason = FL_REASON_UNKNOWN);
 
   /** \internal Horizontal offset of text to left edge of widget. */
   int xscroll() const {return xscroll_;}
diff --git a/FL/Fl_Menu_Item.H b/FL/Fl_Menu_Item.H
index 7ae1faeef..0f1083a9a 100644
--- a/FL/Fl_Menu_Item.H
+++ b/FL/Fl_Menu_Item.H
@@ -390,14 +390,14 @@ struct FL_EXPORT Fl_Menu_Item {
     The callback is called with the stored user_data() as its second argument.
     You must first check that callback() is non-zero before calling this.
   */
-  void do_callback(Fl_Widget* o) const {callback_(o, user_data_);}
+  void do_callback(Fl_Widget* o) const {Fl::callback_reason_=FL_REASON_SELECTED; callback_(o, user_data_);}
 
   /**
     Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument.
     This call overrides the callback's second argument with the given value \p arg.
     You must first check that callback() is non-zero before calling this.
   */
-  void do_callback(Fl_Widget* o,void* arg) const {callback_(o, arg);}
+  void do_callback(Fl_Widget* o,void* arg) const {Fl::callback_reason_=FL_REASON_SELECTED; callback_(o, arg);}
 
   /**
     Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument.
@@ -406,7 +406,7 @@ struct FL_EXPORT Fl_Menu_Item {
     the callback.
     You must first check that callback() is non-zero before calling this.
   */
-  void do_callback(Fl_Widget* o,long arg) const {callback_(o, (void*)(fl_intptr_t)arg);}
+  void do_callback(Fl_Widget* o,long arg) const {Fl::callback_reason_=FL_REASON_SELECTED; callback_(o, (void*)(fl_intptr_t)arg);}
 
   /** Back compatibility only.
     \deprecated
diff --git a/FL/Fl_Tabs.H b/FL/Fl_Tabs.H
index 27f5bc0da..334be5773 100644
--- a/FL/Fl_Tabs.H
+++ b/FL/Fl_Tabs.H
@@ -1,7 +1,7 @@
 //
 // Tab header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2017 by Bill Spitzak and others.
+// Copyright 1998-2023 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -22,10 +22,15 @@
 
 #include "Fl_Group.H"
 
+struct Fl_Menu_Item;
+
 /**
-  The Fl_Tabs widget is the "file card tabs"
-  interface that allows you to put lots and lots of buttons and
-  switches in a panel, as popularized by many toolkits.
+  The Fl_Tabs widget is a container widget that displays a set of tabs, with
+  each tab representing a different child widget. The user can select a tab by
+  clicking on it, and the corresponding child widget will be displayed.
+  The Fl_Tabs widget is useful for organizing a large number of controls or
+  other widgets into a compact space, allowing the user to switch between
+  different sets of controls as needed.
 
   \image html  tabs.png
   \image latex tabs.png "Fl_Tabs" width=8cm
@@ -46,8 +51,8 @@
   children (there should be some space between the children and
   the edge of the Fl_Tabs), and the tabs may be placed
   "inverted" on the bottom - this is determined by which
-  gap is larger. It is easiest to lay this out in fluid, using the
-  fluid browser to select each child group and resize them until
+  gap is larger. It is easiest to lay this out in FLUID, using the
+  FLUID browser to select each child group and resize them until
   the tabs look the way you want them to.
 
   The background area behind and to the right of the tabs is
@@ -157,6 +162,19 @@
   \image html  tabs_uniform.png "Fl_Tabs with uniform colors"
   \image latex tabs_uniform.png "Fl_Tabs with uniform colors" width=8cm
 
+  \b Close \b Button \b on \b Tabs
+
+  The Fl_Tabs widget allows you to specify that a child widget should display
+  a close button in its tab. If the \ref FL_WHEN_CLOSED flag is set for the
+  child widget, an "X" symbol will be displayed to the left of the label text
+  in the tab. When the close button is clicked, the child widget's callback
+  function will be called with the \ref FL_REASON_CLOSED argument. It is then
+  the responsibility of the child widget to remove itself from the
+  Fl_Tabs container.
+
+  Tabs that are in a compressed state will not display a close button until
+  they are fully expanded.
+
   \b Resizing \b Caveats
 
   When Fl_Tabs is resized vertically, the default behavior scales the
@@ -197,6 +215,7 @@
     -#  \ref FL_WHEN_NOT_CHANGED can happen if someone clicks on an already selected tab,
         or if a keyboard navigation attempt results in no change to the tabs,
         such as using the arrow keys while at the left or right end of the tabs.
+    -#  \ref Fl::callback_reason() returns FL_REASON_SELECTED or FL_REASON_RESELECTED
 */
 class FL_EXPORT Fl_Tabs : public Fl_Group {
 
@@ -204,16 +223,31 @@ class FL_EXPORT Fl_Tabs : public Fl_Group {
 
 protected:
 
+  int overflow_type;
+  int tab_offset;
   int *tab_pos;         // array of x-offsets of tabs per child + 1
   int *tab_width;       // array of widths of tabs per child + 1
+  int *tab_flags;       // array of tab flag of tabs per child + 1
   int tab_count;        // array size
   Fl_Align tab_align_;  // tab label alignment
+  int has_overflow_menu;
+  Fl_Menu_Item* overflow_menu;
+
+  void check_overflow_menu();
+  void handle_overflow_menu();
+  void draw_overflow_menu_button();
+
+  int on_insert(Fl_Widget*, int) FL_OVERRIDE;
+  int on_move(int, int) FL_OVERRIDE;
+  void on_remove(int) FL_OVERRIDE;
+  void resize(int, int, int, int) FL_OVERRIDE;
 
   virtual void redraw_tabs();
   virtual int tab_positions();  // allocate and calculate tab positions
   virtual void clear_tab_positions();
-  virtual void draw_tab(int x1, int x2, int W, int H, Fl_Widget* o, int sel=0);
+  virtual void draw_tab(int x1, int x2, int W, int H, Fl_Widget* o, int flags, int sel);
   virtual int tab_height();
+  virtual int hit_close(Fl_Widget *o, int event_x, int event_y);
 
   void draw() FL_OVERRIDE;
 
@@ -225,6 +259,7 @@ public:
   int handle(int) FL_OVERRIDE;
   Fl_Widget *value();
   int value(Fl_Widget *);
+
   /**
     Returns the tab group for the tab the user has currently down-clicked on
     and remains over until FL_RELEASE. Otherwise, returns NULL.
@@ -256,12 +291,23 @@ public:
     recommended alignment to show the icon left of the text.
   */
   void tab_align(Fl_Align a) {tab_align_ = a;}
+
   /**
     Gets the tab label alignment.
 
     \see tab_align(Fl_Align)
   */
   Fl_Align tab_align() const {return tab_align_;}
+
+  enum {
+    OVERFLOW_COMPRESS = 0,
+    OVERFLOW_CLIP,
+    OVERFLOW_PULLDOWN,
+    OVERFLOW_DRAG,
+  };
+
+  void handle_overflow(int ov);
+
 };
 
 #endif
diff --git a/FL/Fl_Text_Editor.H b/FL/Fl_Text_Editor.H
index b9a0d42b0..5bf49781e 100644
--- a/FL/Fl_Text_Editor.H
+++ b/FL/Fl_Text_Editor.H
@@ -113,7 +113,7 @@ class FL_EXPORT Fl_Text_Editor : public Fl_Text_Display {
 
   protected:
     int handle_key();
-    void maybe_do_callback();
+    void maybe_do_callback(Fl_Callback_Reason reason = FL_REASON_CHANGED);
 
 #ifndef FL_DOXYGEN
     int insert_mode_;
diff --git a/FL/Fl_Tree.H b/FL/Fl_Tree.H
index 9a56e1841..6c2b7bf3c 100644
--- a/FL/Fl_Tree.H
+++ b/FL/Fl_Tree.H
@@ -273,14 +273,14 @@
 /// The reason the callback was invoked.
 ///
 enum Fl_Tree_Reason {
-  FL_TREE_REASON_NONE=0,        ///< unknown reason
-  FL_TREE_REASON_SELECTED,      ///< an item was selected
-  FL_TREE_REASON_DESELECTED,    ///< an item was de-selected
-  FL_TREE_REASON_RESELECTED,    ///< an item was re-selected (double-clicked).
+  FL_TREE_REASON_NONE       = FL_REASON_UNKNOWN,        ///< unknown reason
+  FL_TREE_REASON_SELECTED   = FL_REASON_SELECTED,       ///< an item was selected
+  FL_TREE_REASON_DESELECTED = FL_REASON_DESELECTED,     ///< an item was de-selected
+  FL_TREE_REASON_RESELECTED = FL_REASON_RESELECTED,     ///< an item was re-selected (double-clicked).
                                 ///< See ::Fl_Tree_Item_Reselect_Mode to enable this.
-  FL_TREE_REASON_OPENED,        ///< an item was opened
-  FL_TREE_REASON_CLOSED,        ///< an item was closed
-  FL_TREE_REASON_DRAGGED        ///< an item was dragged into a new place
+  FL_TREE_REASON_OPENED     = FL_REASON_OPENED,         ///< an item was opened
+  FL_TREE_REASON_CLOSED     = FL_REASON_CLOSED,         ///< an item was closed
+  FL_TREE_REASON_DRAGGED    = FL_REASON_DRAGGED         ///< an item was dragged into a new place
 };
 
 class FL_EXPORT Fl_Tree : public Fl_Group {
diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index 5b16555b9..772717856 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -1,7 +1,7 @@
 //
 // Widget header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2020 by Bill Spitzak and others.
+// Copyright 1998-2023 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -707,7 +707,7 @@ public:
       FL_WHEN_RELEASE.
 
       \return set of flags
-      \see when(uchar)
+      \see when(uchar), Fl_When, do_callback(), Fl::callback_reason()
    */
   Fl_When when() const {return (Fl_When)when_;}
 
@@ -733,6 +733,11 @@ public:
          a newline for a Fl_Multiline_Input) - this changes the behavior.
      \li FL_WHEN_ENTER_KEY|FL_WHEN_NOT_CHANGED: The Enter key will do the
          callback even if the text has not changed. Useful for command fields.
+     \li \ref FL_WHEN_CLOSED : If the user requests that the widget is closed,
+         the callback is called with \ref FL_REASON_CLOSED. The \ref Fl_Tabs
+         widget checks this flag on its children to determine whether to display
+         a close button on the tab of that widget.
+
       Fl_Widget::when() is a set of bitflags used by subclasses of
       Fl_Widget to decide when to do the callback.
 
@@ -741,6 +746,7 @@ public:
       class so that you can scan a panel and do_callback() on all the ones
       that don't do their own callbacks in response to an "OK" button.
       \param[in] i set of flags
+      \see Fl_When, do_callback(), Fl::callback_reason()
    */
   void when(uchar i) {when_ = i;}
 
@@ -962,7 +968,7 @@ public:
     \see callback()
     \see do_callback(Fl_Widget *widget, void *data)
   */
-  void do_callback() {do_callback(this, user_data_);}
+  void do_callback(Fl_Callback_Reason reason=FL_REASON_UNKNOWN) {do_callback(this, user_data_, reason);}
 
   /** Calls the widget callback function with arbitrary arguments.
     \param[in] widget call the callback with \p widget as the first argument
@@ -970,13 +976,11 @@ public:
     \see callback()
     \see do_callback(Fl_Widget *widget, void *data)
   */
-  void do_callback(Fl_Widget *widget, long arg) {
-    do_callback(widget, (void*)(fl_intptr_t)arg);
+  void do_callback(Fl_Widget *widget, long arg, Fl_Callback_Reason reason=FL_REASON_UNKNOWN) {
+    do_callback(widget, (void*)(fl_intptr_t)arg, reason);
   }
 
-  // Causes a widget to invoke its callback function with arbitrary arguments.
-  // Documentation and implementation in Fl_Widget.cxx
-  void do_callback(Fl_Widget *widget, void *arg = 0);
+  void do_callback(Fl_Widget *widget, void *arg = 0, Fl_Callback_Reason reason=FL_REASON_UNKNOWN);
 
   /* Internal use only. */
   int test_shortcut();
diff --git a/FL/Fl_Window.H b/FL/Fl_Window.H
index ddb3283eb..f012d59a2 100644
--- a/FL/Fl_Window.H
+++ b/FL/Fl_Window.H
@@ -48,6 +48,9 @@ class Fl_Double_Window;
   The window's callback is done if the user tries to close a window
   using the window manager and Fl::modal() is zero or equal to the
   window. Fl_Window has a default callback that calls Fl_Window::hide().
+  Callback reasons can be \p FL_REASON_CANCELLED if the Escape key was pressed,
+  or \p FL_REASON_CLOSED when the close button is clicked. \p FL_WHEN_...
+  flags are ignored.
 */
 class FL_EXPORT Fl_Window : public Fl_Group {
   friend int Fl::arg(int argc, char **argv, int &i);
diff --git a/FL/names.h b/FL/names.h
index 9aaef5490..745ec2133 100644
--- a/FL/names.h
+++ b/FL/names.h
@@ -110,6 +110,27 @@ const char * const fl_fontnames[] =
   "FL_ZAPF_DINGBATS",
 };
 
+/**
+ This is an array of callback reason names you can use to convert font numbers into names.
+
+ The array gets defined inline wherever your '\#include <FL/names.h>' appears.
+ */
+const char * const fl_callback_reason_names[] =
+{
+  "FL_REASON_UNKNOWN",
+  "FL_REASON_SELECTED",
+  "FL_REASON_DESELECTED",
+  "FL_REASON_RESELECTED",
+  "FL_REASON_OPENED",
+  "FL_REASON_CLOSED",
+  "FL_REASON_DRAGGED",
+  "FL_REASON_CANCELLED",
+  "FL_REASON_CHANGED",
+  "FL_REASON_GOT_FOCUS",
+  "FL_REASON_LOST_FOCUS",
+  "FL_REASON_RELEASED",
+};
+
 /** @} */
 
 #endif /* FL_NAMES_H */