Adding `FL_BEFORE_MENU` event to classes derived from `Fl_Menu_`

6 files changed, 22 insertions, 5 deletions

diff --git a/FL/Enumerations.H b/FL/Enumerations.H
index db6465096..5bc2951aa 100644
--- a/FL/Enumerations.H
+++ b/FL/Enumerations.H
@@ -418,7 +418,11 @@ enum Fl_Event { // events
   /** A tooltip is about to pop up for this widget. The mouse coordinates are
    available in Fl::event_x() and Fl::event_y(). Change the widget tooltip
    as needed. */
-  FL_TOOLTIP_EVENT      = 28
+  FL_BEFORE_TOOLTIP     = 28,
+  /** Triggered just before a menu is displayed. Widgets derived from Fl_Menu_
+   receive this event right before the menu appears, providing an opportunity
+   to update menu item states and activation. */
+  FL_BEFORE_MENU        = 29
   // DEV NOTE: Keep this list in sync with FL/names.h
 };
 
diff --git a/FL/Fl_Choice.H b/FL/Fl_Choice.H
index 944f4d3a4..2434a9ac3 100644
--- a/FL/Fl_Choice.H
+++ b/FL/Fl_Choice.H
@@ -100,6 +100,10 @@
    }
  \endcode
 
+  FLTK triggers an `FL_BEFORE_MENU` event for this widget right before
+  displaying the menu. This event provides an opportunity to update menu
+  item states and activation. See `test/menubar.cxx`, class `Dynamic_Choice`
+  "Flip" and "Flop" for a usage example.
  */
 class FL_EXPORT Fl_Choice : public Fl_Menu_ {
 protected:
diff --git a/FL/Fl_Menu_Bar.H b/FL/Fl_Menu_Bar.H
index 26c08539d..4e7af0d6e 100644
--- a/FL/Fl_Menu_Bar.H
+++ b/FL/Fl_Menu_Bar.H
@@ -61,6 +61,10 @@
 
   Typing the shortcut() of any of the menu items will cause
   callbacks exactly the same as when you pick the item with the mouse.
+
+  FLTK triggers an `FL_BEFORE_MENU` event for this widget right before
+  displaying the menu. This event provides an opportunity to update menu
+  item states and activation.
  */
 class FL_EXPORT Fl_Menu_Bar : public Fl_Menu_ {
   friend class Fl_Sys_Menu_Bar_Driver;
diff --git a/FL/Fl_Menu_Button.H b/FL/Fl_Menu_Button.H
index 0e1036450..3f52593b4 100644
--- a/FL/Fl_Menu_Button.H
+++ b/FL/Fl_Menu_Button.H
@@ -52,6 +52,10 @@
     is done instead, along with any userdata configured for it.
     The callback can determine which item was picked using
     value(), mvalue(), item_pathname(), etc.
+
+  FLTK triggers an `FL_BEFORE_MENU` event for this widget right before
+  displaying the menu. This event provides an opportunity to update menu
+  item states and activation.
 */
 class FL_EXPORT Fl_Menu_Button : public Fl_Menu_ {
 protected:
diff --git a/FL/Fl_Tooltip.H b/FL/Fl_Tooltip.H
index d417ba189..592371651 100644
--- a/FL/Fl_Tooltip.H
+++ b/FL/Fl_Tooltip.H
@@ -95,7 +95,7 @@ public:
   static void wrap_width(int v) { wrap_width_ = v; }
   /** Returns the window that is used for tooltips */
   static Fl_Window* current_window(void);
-  /** \brief Temporarily Override Tooltip Text during an FL_TOOLTIP_EVENT. */
+  /** \brief Temporarily Override Tooltip Text during an FL_BEFORE_TOOLTIP event. */
   static int override_text(const char *new_text);
 
   // These should not be public, but Fl_Widget::tooltip() needs them...
diff --git a/FL/names.h b/FL/names.h
index e47d005ec..90ef231e7 100644
--- a/FL/names.h
+++ b/FL/names.h
@@ -73,10 +73,11 @@ const char * const fl_eventnames[] =
   "FL_FULLSCREEN",
   "FL_ZOOM_GESTURE",
   "FL_ZOOM_EVENT",
-  "FL_TOOLTIP_EVENT",
-  "FL_EVENT_29", // not yet defined, just in case it /will/ be defined ...
+  "FL_BEFORE_TOOLTIP",
+  "FL_BEFORE_MENU",
   "FL_EVENT_30", // not yet defined, just in case it /will/ be defined ...
-  "FL_EVENT_31"  // not yet defined, just in case it /will/ be defined ...
+  "FL_EVENT_31", // not yet defined, just in case it /will/ be defined ...
+  "FL_EVENT_32"  // not yet defined, just in case it /will/ be defined ...
 };
 
 /**