Improved, yet compatible, widget callback system using macros (#729)

* adds FL/fl_callback.macros.H
* adds FL_FUNCTION_CALLBACK_n(widget, function, [type, data])
* adds FL_METHOD_CALLBACK_n(widget, class, instance, method, [type, data])
* adds FL_INLINE_CALLBACK_n(widget, [type, name, data], callback_body)
* adds `examples/callback`
* full documentation

1 files changed, 44 insertions, 10 deletions

diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index cf3a16b4f..fc7091225 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -70,6 +70,24 @@ struct FL_EXPORT Fl_Label {
 };
 
 
+/** A class prototype that allows for additional data in callbacks.
+
+ Users can extend this class and pass it to widget callbacks. Widgets can
+ take ownership of the callback data, deleting the data when the widget
+ itself is deleted.
+
+ The destructor of this class is virtual, allowing for additional code to
+ deallocate resources when the user data is deleted.
+
+ \see FL_FUNCTION_CALLBACK, FL_METHOD_CALLBACK, FL_INLINE_CALLBACK
+ \see Fl_Widget::callback(Fl_Callback*, Fl_Callback_User_Data*, bool)
+ \see Fl_Widget::user_data(Fl_Callback_User_Data*, bool)
+ */
+class Fl_Callback_User_Data {
+public:
+  virtual ~Fl_Callback_User_Data() { }
+};
+
 
 /** Fl_Widget is the base class for all widgets in FLTK.
 
@@ -152,7 +170,7 @@ protected:
         CLIP_CHILDREN   = 1<<11,  ///< all drawing within this widget will be clipped (Fl_Group)
         MENU_WINDOW     = 1<<12,  ///< a temporary popup window, dismissed by clicking outside (Fl_Window)
         TOOLTIP_WINDOW  = 1<<13,  ///< a temporary popup, transparent to events, and dismissed easily (Fl_Window)
-        MODAL           = 1<<14,  ///< a window blocking input to all other winows (Fl_Window)
+        MODAL           = 1<<14,  ///< a window blocking input to all other windows (Fl_Window)
         NO_OVERLAY      = 1<<15,  ///< window not using a hardware overlay plane (Fl_Menu_Window)
         GROUP_RELATIVE  = 1<<16,  ///< Reserved, not implemented. DO NOT USE.
         COPIED_TOOLTIP  = 1<<17,  ///< the widget tooltip is internally copied, its destruction is handled by the widget
@@ -161,6 +179,7 @@ protected:
         NEEDS_KEYBOARD  = 1<<20,  ///< set on touch screen devices if a widget needs a keyboard when it gets the focus. Reserved, not yet used in 1.4.0. \see Fl_Widget::needs_keyboard()
         IMAGE_BOUND     = 1<<21,  ///< binding the image to the widget will transfer ownership, so that the widget will delete the image when it is no longer needed
         DEIMAGE_BOUND   = 1<<22,  ///< bind the inactive image to the widget, so the widget deletes the image when it is no longer needed
+        AUTO_DELETE_USER_DATA = 1<<23, ///< automatically call `delete` on the user_data pointer when destroying this widget; if set, user_data must point to a class derived from the class Fl_Callback_User_Data
 
         // Note to devs: add new FLTK core flags above this line (up to 1<<28).
 
@@ -667,12 +686,27 @@ public:
    */
   Fl_Callback_p callback() const {return callback_;}
 
-  /** Sets the current callback function for the widget.
+  /** Sets the current callback function and data for the widget.
       Each widget has a single callback.
       \param[in] cb new callback
       \param[in] p user data
    */
-  void callback(Fl_Callback* cb, void* p) {callback_ = cb; user_data_ = p;}
+  void callback(Fl_Callback* cb, void* p) {
+    callback_ = cb;
+    user_data(p);
+  }
+
+  /** Sets the current callback function and managed user data for the widget.
+   Setting auto_free will transfer ownership of the callback user data to the
+   widget. Deleting the widget will then also delete the user data.
+   \param[in] cb new callback
+   \param[in] p user data
+   \param[in] auto_free if set, the widget will free user data when destroyed
+   */
+  void callback(Fl_Callback* cb, Fl_Callback_User_Data* p, bool auto_free) {
+    callback_ = cb;
+    user_data(p, auto_free);
+  }
 
   /** Sets the current callback function for the widget.
       Each widget has a single callback.
@@ -695,7 +729,7 @@ public:
    */
   void callback(Fl_Callback1* cb, long p = 0) {
     callback_ = (Fl_Callback*)(fl_intptr_t)(cb);
-    user_data_ = (void*)(fl_intptr_t)p;
+    user_data((void*)(fl_intptr_t)p);
   }
 
   /** Gets the user data for this widget.
@@ -704,11 +738,11 @@ public:
    */
   void* user_data() const {return user_data_;}
 
-  /** Sets the user data for this widget.
-      Sets the new user data (void *) argument that is passed to the callback function.
-      \param[in] v new user data
-   */
-  void user_data(void* v) {user_data_ = v;}
+  /** \brief Sets the user data for this widget. */
+  void user_data(void* v);
+
+  /** \brief Sets the user data for this widget. */
+  void user_data(Fl_Callback_User_Data* v, bool auto_free);
 
   /** Gets the current user data (long) argument that is passed to the callback function.
 
@@ -727,7 +761,7 @@ public:
 
     \see argument()
    */
-  void argument(long v) {user_data_ = (void*)(fl_intptr_t)v;}
+  void argument(long v) {user_data((void*)(fl_intptr_t)v);}
 
   /** Returns the conditions under which the callback is called.