anyplotlib.Widget

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

Bases: _EventMixin

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.add_event_handler(fn, "pointer_move") or as a decorator: @widget.add_event_handler("pointer_move").

Common event types:

• "pointer_move" — fires on every drag frame

• "pointer_up" — fires once when drag settles

• "pointer_down" — fires on click/press event

Type:

CallbackRegistry

set(_push=True, _notify=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.

• _notify (bool, optional) –

  Whether to fire pointer_move callbacks. Default True.

  A set() from Python is otherwise indistinguishable from a user drag: handlers that react to the widget moving will run, and one that writes back to the widget feeds into itself. Pass _notify=False when you are the one moving the widget and the handlers are only meant to hear about user input:

  widget.set(_notify=False, x=new_x)
  

  This supersedes wrapping the call in pause_events(), which suppresses every event type for the duration rather than just this update’s echo.

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

Return type:

None

Notes

Both flags are spelled with a leading underscore so they can never collide with a widget property of the same name in **kwargs.

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

property visible: bool

True if the widget is rendered; False if hidden.

show()

Show the widget. Does not fire pointer_move callbacks.

Return type:

None

hide()

Hide the widget without removing it or its callbacks.

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

Return type:

None

remove()

Remove this widget from the plot that owns it.

Equivalent to plot.remove_widget(widget), but callable when you only hold the widget — handle-based APIs otherwise have to re-derive the owning plot to delete something they already have.

Removing a widget that is not attached to a plot, or removing twice, is a no-op.

Return type:

None

property id: str

Return the widget’s unique identifier.