Callback System

Every pgwidgets object inherits from the Callback base class, which provides a consistent event system across all widgets.

Core API

enable_callback(action)

Register a new callback action type on this object. Widgets call this internally for their supported actions.

add_callback(action, cb_fn)

Add a listener for action. The function receives (widget, ...args) when triggered. Throws if action has not been enabled.

remove_callback(action, cb_fn)

Remove a previously added listener.

clear_callback(action)

Remove all listeners for action.

make_callback(action, ...args)

Fire all listeners for action, passing args after the widget reference. Widgets call this internally when events occur.

has_callback(action)

Returns true if action has been enabled on this object.

Example

let button = new Widgets.Button("Click me");

// add_callback: first arg is always the widget itself
button.add_callback('activated', (widget) => {
    console.log("Button clicked!", widget.wid);
});

// Multiple listeners on the same action
button.add_callback('activated', (widget) => {
    document.title = "Clicked!";
});

// Remove a specific listener
function myHandler(widget) { /* ... */ }
button.add_callback('activated', myHandler);
button.remove_callback('activated', myHandler);

Common Callbacks

All visual widgets support:

  • resize – fired as (widget, width_px, height_px) whenever the widget’s size changes.

  • child-added – fired on container widgets when a child is added.

  • child-removed – fired on container widgets when a child is removed.

Interactive widgets (Image, Canvas) support pointer and keyboard events:

  • pointer-down, pointer-up, pointer-move – mouse/touch events

  • enter, leave – pointer enters/leaves the widget

  • click, dblclick – click events

  • scroll – scroll wheel

  • key-down, key-up, key-press – keyboard events

  • focus-in, focus-out – focus changes

  • contextmenu – right-click context menu

Drop Events

Image and Canvas widgets support drag-and-drop file events:

  • drop-start – a file drop has begun

  • drop-progress – progress update during file reading

  • drop-end – file data is available

  • drag-over – a dragged item is hovering over the widget

Widget-Specific Callbacks

Each widget documents its own callback actions. Common patterns:

  • activated – the primary action (button click, value change, selection)

  • page-switch – tab, stack, or MDI page changed

  • page-close – tab or MDI sub-window closed

  • expired, cancelled – timer events

  • pick – color selected

  • changed, cursor_moved – text editor events

  • child-added – child widget added to a container

  • child-removed – child widget removed from a container

  • sizing – splitter pane sizes changed

  • toggled – expander collapsed/expanded

  • scrolled – scroll position changed (ScrollArea, MDIWidget)

  • cell_edited – table/tree cell edited by user

See the individual widget reference pages for the full list of callbacks each widget supports.