anyplotlib.Widget

class anyplotlib.Widget(wtype, push_fn, **kwargs)

Bases: object

Base class for all overlay widgets.

Provides attribute-based state access, callbacks for interaction events, and automatic synchronization with the JavaScript renderer.

Parameters:

• wtype (str) – Widget type (e.g., ‘rectangle’, ‘circle’, ‘crosshair’).

• push_fn (Callable) – Zero-arg callback to send position updates to the JavaScript renderer.

• **kwargs (dict) – Initial widget state (position, size, color, etc.).

callbacks

Event callback registry. Register handlers via: - @widget.on_changed — fires on every drag frame - @widget.on_release — fires once when drag settles - @widget.on_click — fires on click event

Type:

CallbackRegistry

set(_push=True, **kwargs)

Update properties and send targeted update to JavaScript.

Parameters:

• _push (bool, optional) – Whether to push update to renderer. Default True. Set to False internally to avoid echo loops.

• **kwargs (dict) – Properties to update (e.g., x=100, y=50, radius=20).

Return type:

None

Notes

Updates are sent as targeted widget updates, not full panel re-renders. This is more efficient for frequent updates during dragging.

get(key, default=None)

Get a widget property by name.

Parameters:

• key (str) – Property name.

• default (optional) – Default value if property not found.

Returns:

The property value.

Return type:

object

to_dict()

Return a dict copy of the widget state.

Returns:

All widget properties including id and type.

Return type:

dict

on_changed(fn)

Decorator: register fn to fire on every drag frame.

Use this for high-frequency updates (keep handler fast).

Parameters:

fn (Callable) – Handler function receiving an Event.

Returns:

The decorated function.

Return type:

Callable

on_release(fn)

Decorator: register fn to fire once when drag settles.

Use this for expensive operations triggered after user stops dragging.

Parameters:

fn (Callable) – Handler function receiving an Event.

Returns:

The decorated function.

Return type:

Callable

on_click(fn)

Decorator: register fn to fire on widget click.

Parameters:

fn (Callable) – Handler function receiving an Event.

Returns:

The decorated function.

Return type:

Callable

disconnect(cid)

Remove the callback registered under cid.

Parameters:

cid (int or Callable) – Either the integer CID returned by callbacks.connect(), or the decorated function itself (carries a ._cid attribute).

Return type:

None

property visible: bool

True if the widget is rendered; False if hidden.

show()

Show the widget. Does not fire on_changed callbacks.

Return type:

None

hide()

Hide the widget without removing it or its callbacks.

Call show() to make it visible again. Does not fire on_changed callbacks.

Return type:

None

property id: str

Return the widget’s unique identifier.