Merge remote-tracking branch 'refs/remotes/origin/master'

8 files changed, 68 insertions, 20 deletions

diff --git a/FL/Enumerations.H b/FL/Enumerations.H
index 1a8b219bd..5bc2951aa 100644
--- a/FL/Enumerations.H
+++ b/FL/Enumerations.H
@@ -153,11 +153,15 @@
   This is done to prevent users from defining an illegal ABI version.
 
   Rule: FL_MAJOR_VERSION * 10000 + FL_MINOR_VERSION * 100
-          <= FL_ABI_VERSION <= FL_API_VERSION.
+          <= FL_ABI_VERSION <= FL_API_VERSION + 1.
 
-  Example (FLTK 1.3.4):
+  Since FLTK 1.4.2+ (Git commits after release 1.4.2) FL_ABI_VERSION is
+  allowed to be one higher than FL_API_VERSION so ABI changes in Git
+  targeted at the *next* release (e.g. 1.4.3) can be used.
 
-    10300 <= FL_ABI_VERSION <= 10304
+  Example: Commits after release FLTK 1.4.2 (before release 1.4.3):
+
+    10400 <= FL_ABI_VERSION <= 10403
 
   Note: configure + CMake can be used to define FL_ABI_VERSION, but they
   do not check validity. This is done here.
@@ -168,10 +172,10 @@
 # undef FL_ABI_VERSION
 # define FL_ABI_VERSION (FL_MAJOR_VERSION*10000 + FL_MINOR_VERSION*100)
 
-#elif FL_ABI_VERSION > FL_API_VERSION
+#elif FL_ABI_VERSION > FL_API_VERSION + 1
 
 # undef FL_ABI_VERSION
-# define FL_ABI_VERSION FL_API_VERSION
+# define FL_ABI_VERSION FL_API_VERSION + 1
 
 #endif
 
@@ -410,7 +414,15 @@ enum Fl_Event { // events
   /** A zoom event (ctrl/+/-/0/ or cmd/+/-/0/) was processed.
    Use Fl::add_handler() to be notified of this event.
    */
-  FL_ZOOM_EVENT         = 27
+  FL_ZOOM_EVENT         = 27,
+  /** 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_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_Menu_Item.H b/FL/Fl_Menu_Item.H
index 3073dd2d0..6eaf0a9d2 100644
--- a/FL/Fl_Menu_Item.H
+++ b/FL/Fl_Menu_Item.H
@@ -34,7 +34,8 @@ enum { // values for flags:
   FL_SUBMENU_POINTER = 0x20,       ///< Indicates user_data() is a pointer to another menu array
   FL_SUBMENU         = 0x40,       ///< Item is a submenu to other items
   FL_MENU_DIVIDER    = 0x80,       ///< Creates divider line below this item. Also ends a group of radio buttons
-  FL_MENU_HORIZONTAL = 0x100       ///< ??? -- reserved, internal (do not use)
+  FL_MENU_HORIZONTAL = 0x100,      ///< reserved, do not use
+  FL_MENU_CHATTY     = 0x200       ///< Menu Item receives additional callbacks
   ///< Note: \b ALL other bits in \p flags are reserved: do not use them for your own purposes!
 };
 
@@ -67,7 +68,8 @@ class Fl_Menu_;
    FL_SUBMENU_POINTER = 0x20,       // Indicates user_data() is a pointer to another menu array
    FL_SUBMENU         = 0x40,       // This item is a submenu to other items
    FL_MENU_DIVIDER    = 0x80,       // Creates divider line below this item. Also ends a group of radio buttons.
-   FL_MENU_HORIZONTAL = 0x100       // ??? -- reserved, internal (do not use)
+   FL_MENU_HORIZONTAL = 0x100       // reserved, do not use
+   FL_MENU_CHATTY     = 0x200       ///< Menu Item receives additional callbacks
   };
   \endcode
 
@@ -120,6 +122,16 @@ class Fl_Menu_;
     variants copies the entire menu to internal storage. Using the
     memory of a static menu array after that would access unused (but not
     released) memory and thus have no effect.
+
+  When a menu item is selected by the user and a callback is set, the callback
+  will be called with FL_REASON_SELECTED. The Fl_Widget pointer is set to the
+  widget that opened the menu, a copy of the menu item's user data. If no menu
+  item callback is set, the callback of the managing widget is called instead.
+
+  If the FL_MENU_CHATTY flag is set, the menu item callback may be called for
+  additional reasons. When a menu item is highlighted, the callback is called
+  with FL_REASON_GOT_FOCUS. If it is no longer highlighted,
+  FL_REASON_LOST_FOCUS is sent.
 */
 struct FL_EXPORT Fl_Menu_Item {
   const char *text;         ///< menu item text, returned by label()
@@ -490,14 +502,18 @@ 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 {Fl::callback_reason_=FL_REASON_SELECTED; callback_(o, user_data_);}
+  void do_callback(Fl_Widget* o, Fl_Callback_Reason reason=FL_REASON_UNKNOWN) const {
+    Fl::callback_reason_ = reason; 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 {Fl::callback_reason_=FL_REASON_SELECTED; callback_(o, arg);}
+  void do_callback(Fl_Widget* o, void* arg, Fl_Callback_Reason reason=FL_REASON_UNKNOWN) const {
+    Fl::callback_reason_ = reason; callback_(o, arg);
+  }
 
   /**
     Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument.
@@ -506,7 +522,9 @@ 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 {Fl::callback_reason_=FL_REASON_SELECTED; callback_(o, (void*)(fl_intptr_t)arg);}
+  void do_callback(Fl_Widget* o, long arg, Fl_Callback_Reason reason=FL_REASON_UNKNOWN) const {
+    Fl::callback_reason_ = FL_REASON_SELECTED; callback_(o, (void*)(fl_intptr_t)arg);
+  }
 
   /** Back compatibility only.
     \deprecated
diff --git a/FL/Fl_Tooltip.H b/FL/Fl_Tooltip.H
index b79d93149..592371651 100644
--- a/FL/Fl_Tooltip.H
+++ b/FL/Fl_Tooltip.H
@@ -95,6 +95,8 @@ 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_BEFORE_TOOLTIP event. */
+  static int override_text(const char *new_text);
 
   // These should not be public, but Fl_Widget::tooltip() needs them...
   // fabien: made it private with only a friend function access
@@ -104,20 +106,22 @@ private:
   static void enter_(Fl_Widget* w);
   static void exit_(Fl_Widget *w);
   static void set_enter_exit_once_();
+  static void tooltip_timeout_(void*);
 
 private:
-  static float delay_; //!< delay before a tooltip is shown
-  static float hidedelay_; //!< delay until tooltip is closed again
-  static float hoverdelay_; //!< delay between tooltips
+  static float delay_;          //!< delay before a tooltip is shown
+  static float hidedelay_;      //!< delay until tooltip is closed again
+  static float hoverdelay_;     //!< delay between tooltips
   static Fl_Color color_;
   static Fl_Color textcolor_;
   static Fl_Font font_;
   static Fl_Fontsize size_;
-  static Fl_Widget* widget_; //!< Keeps track of the current target widget
+  static Fl_Widget* widget_;    //!< Keeps track of the current target widget
   static int margin_width_;     //!< distance around tooltip text left+right
   static int margin_height_;    //!< distance around tooltip text top+bottom
   static int wrap_width_;       //!< maximum width of tooltip text before it word wraps
   static const int draw_symbols_; // 1 = draw @-symbols in tooltips, 0 = no
+  static char *override_text_;  //!< a copy of the last text for an overridden tooltip
 };
 
 #endif
diff --git a/FL/Fl_Tree_Item.H b/FL/Fl_Tree_Item.H
index b76395334..8cdd6ee10 100644
--- a/FL/Fl_Tree_Item.H
+++ b/FL/Fl_Tree_Item.H
@@ -93,8 +93,8 @@ protected:
   void _Init(const Fl_Tree_Prefs &prefs, Fl_Tree *tree);
   void show_widgets();
   void hide_widgets();
-  void draw_vertical_connector(int x, int y1, int y2, const Fl_Tree_Prefs &prefs);
-  void draw_horizontal_connector(int x1, int x2, int y, const Fl_Tree_Prefs &prefs);
+  virtual void draw_vertical_connector(int x, int y1, int y2, const Fl_Tree_Prefs &prefs);
+  virtual void draw_horizontal_connector(int x1, int x2, int y, const Fl_Tree_Prefs &prefs);
   void recalc_tree();
   int calc_item_height(const Fl_Tree_Prefs &prefs) const;
   Fl_Color drawfgcolor() const;
diff --git a/FL/names.h b/FL/names.h
index 984afbfe0..90ef231e7 100644
--- a/FL/names.h
+++ b/FL/names.h
@@ -73,9 +73,11 @@ const char * const fl_eventnames[] =
   "FL_FULLSCREEN",
   "FL_ZOOM_GESTURE",
   "FL_ZOOM_EVENT",
-  "FL_EVENT_28", // not yet defined, just in case it /will/ be defined ...
-  "FL_EVENT_29", // not yet defined, just in case it /will/ be defined ...
-  "FL_EVENT_30"  // 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_32"  // not yet defined, just in case it /will/ be defined ...
 };
 
 /**