Unify widget callback mechanism with closure

Previous design had widget-specific callback mechanisms (button signals,
scroll signals) with duplicated closure management code.

This commit introduces two complementary callback patterns:
1. Widget-level dispatch (for custom widgets and complex event handling)
   - Added dispatch_ex with (widget, event, closure) signature
   - Unified closure storage in twin_widget_t
   - Used by custom widgets and applications needing full event access
2. Button-specific API (for simple click handling)
   - Added twin_button_on_clicked(button, callback, data)
   - Simplified signature: void (*)(twin_button_t*, void*)
   - Direct callback invocation on button click
   - Used by calc, image, spline demos

Button signals promoted to standard events (TwinEventButtonSignal*).
Removed obsolete scroll signal typedefs and button-specific fields.

Author: jserv

.gitignore

@@ -29,8 +29,7 @@ __pycache__/
 *.pyc
 
 # Configuration
-.config
-.config.old
+.config*
 config.h
 
 # CI pipeline

apps/animation.c

@@ -56,8 +56,11 @@ static twin_time_t _apps_animation_timeout(twin_time_t now, void *closure)
 }
 
 static twin_dispatch_result_t _apps_animation_dispatch(twin_widget_t *widget,
-                                                       twin_event_t *event)
+                                                       twin_event_t *event,
+                                                       void *closure)
 {
+    (void) closure; /* unused parameter */
+
     twin_custom_widget_t *custom = twin_widget_get_custom(widget);
     if (!custom)
         return TwinDispatchContinue;

apps/calc.c

@@ -129,15 +129,11 @@ static void _apps_calc_digit(apps_calc_t *calc, int digit)
     _apps_calc_update_value(calc);
 }
 
-static void _apps_calc_button_signal(twin_button_t *button,
-                                     twin_button_signal_t signal,
-                                     void *closure)
+static void _apps_calc_button_clicked(twin_button_t *button, void *data)
 {
-    apps_calc_t *calc = closure;
+    apps_calc_t *calc = data;
     int a, b;
 
-    if (signal != TwinButtonSignalDown)
-        return;
     int i = _apps_calc_button_to_id(calc, button);
     if (i < 0)
         return;
@@ -220,8 +216,8 @@ void apps_calc_start(twin_screen_t *screen,
                 APPS_CALC_BUTTON_SIZE, APPS_CALC_BUTTON_STYLE);
             twin_widget_set(&calc->buttons[b]->label.widget,
                             APPS_CALC_BUTTON_BG);
-            calc->buttons[b]->signal = _apps_calc_button_signal;
-            calc->buttons[b]->closure = calc;
+            twin_button_on_clicked(calc->buttons[b], _apps_calc_button_clicked,
+                                   calc);
             calc->buttons[b]->label.widget.shape = TwinShapeEllipse;
             if (i || j)
                 calc->buttons[b]->label.widget.copy_geom =

apps/clock.c

@@ -204,8 +204,11 @@ static twin_time_t _apps_clock_timeout(twin_time_t now, void *closure)
 }
 
 static twin_dispatch_result_t _apps_clock_dispatch(twin_widget_t *widget,
-                                                   twin_event_t *event)
+                                                   twin_event_t *event,
+                                                   void *closure)
 {
+    (void) closure; /* unused parameter */
+
     twin_custom_widget_t *custom = twin_widget_get_custom(widget);
     if (!custom)
         return TwinDispatchContinue;

apps/image.c

@@ -54,8 +54,11 @@ static void _apps_image_paint(twin_custom_widget_t *custom)
 }
 
 static twin_dispatch_result_t _apps_image_dispatch(twin_widget_t *widget,
-                                                   twin_event_t *event)
+                                                   twin_event_t *event,
+                                                   void *closure)
 {
+    (void) closure; /* unused parameter */
+
     twin_custom_widget_t *custom = twin_widget_get_custom(widget);
     if (!custom)
         return TwinDispatchContinue;
@@ -70,15 +73,11 @@ static twin_dispatch_result_t _apps_image_dispatch(twin_widget_t *widget,
     return TwinDispatchContinue;
 }
 
-static void _apps_image_button_signal(twin_button_t *button,
-                                      twin_button_signal_t signal,
-                                      void *closure)
+static void _apps_image_button_clicked(twin_button_t *button, void *data)
 {
     (void) button; /* unused parameter */
-    if (signal != TwinButtonSignalDown)
-        return;
 
-    twin_custom_widget_t *custom = closure;
+    twin_custom_widget_t *custom = data;
     apps_image_data_t *img =
         (apps_image_data_t *) twin_custom_widget_data(custom);
     const int n = sizeof(tvg_files) / sizeof(tvg_files[0]);
@@ -113,8 +112,7 @@ static twin_custom_widget_t *_apps_image_init(twin_box_t *parent)
         twin_button_create(parent, "Next Image", 0xFF482722, D(10),
                            TwinStyleBold | TwinStyleOblique);
     twin_widget_set(&button->label.widget, 0xFFFEE4CE);
-    button->signal = _apps_image_button_signal;
-    button->closure = custom;
+    twin_button_on_clicked(button, _apps_image_button_clicked, custom);
     button->label.widget.shape = TwinShapeRectangle;
 
     return custom;

apps/line.c

@@ -71,8 +71,11 @@ static int _apps_line_hit(apps_line_data_t *line,
 }
 
 static twin_dispatch_result_t _apps_line_dispatch(twin_widget_t *widget,
-                                                  twin_event_t *event)
+                                                  twin_event_t *event,
+                                                  void *closure)
 {
+    (void) closure; /* unused parameter */
+
     twin_custom_widget_t *custom = twin_widget_get_custom(widget);
     if (!custom)
         return TwinDispatchContinue;

apps/spline.c

@@ -113,15 +113,11 @@ static void _apps_spline_paint(twin_custom_widget_t *custom)
     twin_path_destroy(path);
 }
 
-static void _apps_spline_button_signal(twin_button_t *button,
-                                       twin_button_signal_t signal,
-                                       void *closure)
+static void _apps_spline_button_clicked(twin_button_t *button, void *data)
 {
     (void) button; /* unused parameter */
-    if (signal != TwinButtonSignalDown)
-        return;
 
-    twin_custom_widget_t *custom = closure;
+    twin_custom_widget_t *custom = data;
     apps_spline_data_t *spline =
         (apps_spline_data_t *) twin_custom_widget_data(custom);
     spline->n_points = (spline->n_points == 3) ? 4 : 3;
@@ -167,8 +163,11 @@ static int _apps_spline_hit(apps_spline_data_t *spline,
 }
 
 static twin_dispatch_result_t _apps_spline_dispatch(twin_widget_t *widget,
-                                                    twin_event_t *event)
+                                                    twin_event_t *event,
+                                                    void *closure)
 {
+    (void) closure; /* unused parameter */
+
     twin_custom_widget_t *custom = twin_widget_get_custom(widget);
     if (!custom)
         return TwinDispatchContinue;
@@ -227,8 +226,7 @@ static twin_custom_widget_t *_apps_spline_init(twin_box_t *parent, int n_points)
         twin_button_create(parent, "Switch curve", 0xffae0000, D(10),
                            TwinStyleBold | TwinStyleOblique);
     twin_widget_set(&button->label.widget, 0xc0808080);
-    button->signal = _apps_spline_button_signal;
-    button->closure = custom;
+    twin_button_on_clicked(button, _apps_spline_button_clicked, custom);
     button->label.widget.shape = TwinShapeRectangle;
 
     return custom;

include/twin.h

@@ -116,6 +116,12 @@ typedef struct _twin_screen twin_screen_t;
 typedef struct _twin_pixmap twin_pixmap_t;
 typedef struct _twin_animation twin_animation_t;
 
+/** Button signal types (used in unified event system) */
+typedef enum _twin_button_signal {
+    TwinButtonSignalDown /**< Sent when button pressed */,
+    TwinButtonSignalUp /**< Sent when button released inside widget */
+} twin_button_signal_t;
+
 /**
  * Event type enumeration for input and system events
  *
@@ -147,7 +153,11 @@ typedef enum _twin_event_kind {
     TwinEventPaint = 0x1001 /**< Widget needs painting */,
     TwinEventQueryGeometry = 0x1002 /**< Widget geometry query */,
     TwinEventConfigure = 0x1003 /**< Widget configuration change */,
-    TwinEventDestroy = 0x1004 /**< Widget destruction */
+    TwinEventDestroy = 0x1004 /**< Widget destruction */,
+
+    /* Button signals (unified with event system) */
+    TwinEventButtonSignalDown = 0x2001 /**< Button pressed signal */,
+    TwinEventButtonSignalUp = 0x2002 /**< Button released signal */
 } twin_event_kind_t;
 
 /**
@@ -177,7 +187,10 @@ typedef struct _twin_event {
         struct {
             twin_rect_t extents; /**< New widget geometry */
         } configure;             /**< Widget configuration event data */
-    } u;                         /**< Event-specific data union */
+        struct {
+            twin_button_signal_t signal; /**< Button signal type */
+        } button_signal;                 /**< Button signal event data */
+    } u;                                 /**< Event-specific data union */
 } twin_event_t;
 
 /**
@@ -588,11 +601,27 @@ typedef enum _twin_box_dir {
 
 typedef enum _twin_dispatch_result {
     TwinDispatchDone /**< Event processing complete */,
-    TwinDispatchContinue /**< Continue event propagation */
+    TwinDispatchContinue /**< Continue event propagation */,
+    TwinDispatchReject /**< Cannot handle this event */
 } twin_dispatch_result_t;
 
-typedef twin_dispatch_result_t (*twin_dispatch_proc_t)(twin_widget_t *widget,
-                                                       twin_event_t *event);
+/**
+ * Widget event handler function signature
+ *
+ * All widget event handlers use this signature with closure support.
+ * The closure parameter enables stateful event handling without global state.
+ *
+ * @widget  : Widget receiving the event
+ * @event   : Event to process
+ * @closure : User data pointer for stateful handling
+ * @return  : Dispatch result (Done, Continue, or Reject)
+ *
+ * This type is used for both framework-level handlers and application
+ * callbacks.
+ */
+typedef twin_dispatch_result_t (*twin_widget_proc_t)(twin_widget_t *widget,
+                                                     twin_event_t *event,
+                                                     void *closure);
 
 typedef struct _twin_widget_layout {
     twin_coord_t width, height;    /**< Preferred dimensions */
@@ -614,10 +643,15 @@ struct _twin_widget {
     twin_widget_t *next;   /**< Next sibling widget */
     twin_box_t *parent;    /**< Parent container */
 
-    /* Widget behavior */
-    twin_dispatch_proc_t dispatch; /**< Event dispatch handler */
-    twin_rect_t extents;           /**< Current geometry */
-    twin_widget_t *copy_geom;      /**< Geometry source widget */
+    /* Event handling:
+     * - handler: Framework event handler (processes paint, configure, etc.)
+     * - callback: Application callback (optional, receives button clicks, etc.)
+     */
+    twin_widget_proc_t handler;  /**< Widget event handler (framework) */
+    twin_widget_proc_t callback; /**< Application callback (optional) */
+    void *callback_data;         /**< Callback user data */
+    twin_rect_t extents;         /**< Current geometry */
+    twin_widget_t *copy_geom;    /**< Geometry source widget */
 
     /* Widget state */
     bool paint;      /**< Needs painting */
@@ -659,41 +693,24 @@ typedef struct _twin_label {
     twin_align_t align;       /**< Text alignment */
 } twin_label_t;
 
-typedef enum _twin_button_signal {
-    TwinButtonSignalDown /**< Sent when button pressed */,
-    TwinButtonSignalUp /**< Sent when button released inside widget */
-} twin_button_signal_t;
-
 typedef struct _twin_button twin_button_t;
 
-typedef void (*twin_button_signal_proc_t)(twin_button_t *button,
-                                          twin_button_signal_t signal,
-                                          void *closure);
+/**
+ * Button click callback signature
+ * @button : Button that was clicked
+ * @data   : User data provided when callback was registered
+ *
+ * Similar to GTK's "clicked" signal.
+ * Fires when the button is pressed and released.
+ */
+typedef void (*twin_button_callback_t)(twin_button_t *button, void *data);
 
 struct _twin_button {
-    twin_label_t label;               /**< Base label widget */
-    bool pressed;                     /**< Button pressed state */
-    bool active;                      /**< Button active state */
-    twin_button_signal_proc_t signal; /**< Signal callback */
-    void *closure;                    /**< Callback closure */
-};
-
-typedef enum _twin_scroll_signal {
-    TwinScrollSignalUpArrow /**< Up arrow clicked */,
-    TwinScrollSignalDownArrow /**< Down arrow clicked */,
-    TwinScrollSignalThumb /**< Thumb/slider clicked */,
-    TwinScrollSignalAboveThumb /**< Area above thumb clicked */,
-    TwinScrollSignalBelowThumb /**< Area below thumb clicked */
-} twin_scroll_signal_t;
-
-typedef struct _twin_scroll twin_scroll_t;
-
-typedef void (*twin_scroll_signal_proc_t)(twin_scroll_t *scroll,
-                                          twin_scroll_signal_t signal,
-                                          void *closure);
-
-struct _twin_scroll {
-    twin_widget_t widget; /**< Base widget */
+    twin_label_t label;                    /**< Base label widget */
+    bool pressed;                          /**< Button pressed state */
+    bool active;                           /**< Button active state */
+    twin_button_callback_t click_callback; /**< Modern click callback */
+    void *click_data;                      /**< User data for click callback */
 };
 
 typedef struct _twin_context {
@@ -726,6 +743,37 @@ twin_button_t *twin_button_create(twin_box_t *parent,
                                   twin_fixed_t font_size,
                                   twin_style_t font_style);
 
+/**
+ * Register callback for button clicks
+ * @button   : Button widget
+ * @callback : Function to call when button is clicked
+ * @data     : User data to pass to callback
+ *
+ * The callback is invoked when the button is pressed and released (clicked).
+ *
+ * Example:
+ *   void on_button_clicked(twin_button_t *btn, void *data) {
+ *       printf("Button clicked!\n");
+ *   }
+ *   twin_button_on_clicked(my_button, on_button_clicked, my_data);
+ */
+void twin_button_on_clicked(twin_button_t *button,
+                            twin_button_callback_t callback,
+                            void *data);
+
+/**
+ * Set application callback for widget events (low-level API)
+ * @widget   : Widget to configure
+ * @callback : Application callback function
+ * @data     : User data passed to callback
+ *
+ * Allows applications to respond to widget events (e.g., button clicks).
+ * The callback receives events after the widget's core handler processes them.
+ */
+void twin_widget_set_callback(twin_widget_t *widget,
+                              twin_widget_proc_t callback,
+                              void *data);
+
 /**
  * Create default mouse cursor pixmap
  * @hx : Output hotspot X coordinate
@@ -1376,14 +1424,14 @@ twin_fixed_t twin_widget_height(twin_widget_t *widget);
 /* Request widget repaint */
 void twin_widget_queue_paint(twin_widget_t *widget);
 
-/* Create widget with custom dispatch handler */
-twin_widget_t *twin_widget_create_with_dispatch(twin_box_t *parent,
-                                                twin_argb32_t background,
-                                                twin_coord_t width,
-                                                twin_coord_t height,
-                                                twin_stretch_t hstretch,
-                                                twin_stretch_t vstretch,
-                                                twin_dispatch_proc_t dispatch);
+/* Create widget with custom event handler */
+twin_widget_t *twin_widget_create_with_handler(twin_box_t *parent,
+                                               twin_argb32_t background,
+                                               twin_coord_t width,
+                                               twin_coord_t height,
+                                               twin_stretch_t hstretch,
+                                               twin_stretch_t vstretch,
+                                               twin_widget_proc_t handler);
 
 /*
  * Custom widget support - allows creating widgets without accessing internals
@@ -1403,19 +1451,19 @@ typedef struct {
 } twin_custom_widget_t;
 
 /**
- * Create a custom widget with user-defined data and dispatch handler.
+ * Create a custom widget with user-defined data and event handler.
  *
  * @parent       : Parent box widget to contain this widget
  * @background   : Background color (ARGB32 format)
  * @width        : Preferred width in pixels (0 for flexible)
  * @height       : Preferred height in pixels (0 for flexible)
  * @hstretch     : Horizontal stretch factor for layout
  * @vstretch     : Vertical stretch factor for layout
- * @dispatch     : Custom event dispatch function for this widget
+ * @handler      : Custom event handler function for this widget
  * @data_size    : Size of custom data to allocate (0 for no data)
  * @return       : Newly created custom widget, or NULL on failure
  *
- * The dispatch function will be called for all events sent to this widget.
+ * The handler function will be called for all events sent to this widget.
  * Custom data (if requested) is zero-initialized and accessible via
  * twin_custom_widget_data().
  */
@@ -1425,7 +1473,7 @@ twin_custom_widget_t *twin_custom_widget_create(twin_box_t *parent,
                                                 twin_coord_t height,
                                                 twin_stretch_t hstretch,
                                                 twin_stretch_t vstretch,
-                                                twin_dispatch_proc_t dispatch,
+                                                twin_widget_proc_t handler,
                                                 size_t data_size);
 
 /**