anyplotlib.Widget#

class anyplotlib.Widget(wtype, push_fn, **kwargs)[source]#

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, *, notify=None, **kwargs)[source]#

Update properties and send targeted update to JavaScript.

Parameters:

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(x=new_x, notify=False)
```
This supersedes wrapping the call in pause_events(), which suppresses every event type for the duration rather than just this update’s echo.
_notify (bool, optional) – Older spelling of notify, kept as an alias. notify wins when both are given.
_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). Geometry is read in the widget’s coords frame, so a widget created with coords="data" takes calibrated values here.

Return type:

None

Notes

No widget has a property called notify, so the keyword cannot collide with one; _notify / _push keep their leading underscore for the same reason.

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, *, coords=None)[source]#

Get a widget property by name.

Parameters:

key (str) – Property name.
default (optional) – Default value if property not found.
coords ("pixel" | "data", optional) – Frame to report geometry in. Defaults to the widget’s coords. Ignored on panels without a pixel frame (1-D).

Returns:

The property value.

Return type:

object

to_dict(*, coords=None)[source]#

Return a dict copy of the widget state.

Parameters:: coords ("pixel" | "data", optional) – Frame to report geometry in. Defaults to the widget’s coords.
Returns:: All widget properties including id and type.
Return type:: dict

property coords: str#

"pixel" or "data".

On a 2-D image panel, "pixel" (the default) means image pixels — integer i is the centre of pixel i, row 0 at the top — and "data" means the calibrated values of the panel’s axes. Attribute reads (widget.cx), get(), to_dict() and set() all use this frame; drag callbacks therefore see calibrated values on a "data" widget. Choose it with coords= on the plot’s add_*_widget method, or change it with set_coords().

On 1-D and bar panels positions are always in data units, so this is "data".

Notes

The renderer always works in pixels, so a widget stores pixels and a "data" widget converts on every read and write. Re-calibrating the panel (set_extent()) therefore keeps the widget on the same pixels; its data-coordinate values change. This differs from coords="data" marker groups, which store data values and so keep their data position (and move on screen).

Type:: Coordinate frame of this widget’s geometry

set_coords(coords)[source]#

Switch the frame used for reading and writing geometry.

Does not move the widget.

Parameters:: coords ("pixel" | "data")
Return type:: None

property visible: bool#: True if the widget is rendered; False if hidden.

show()[source]#

Show the widget. Does not fire pointer_move callbacks.

Return type:: None

hide()[source]#

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()[source]#

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.

property kind: str#

The widget kind, e.g. "rectangle", "crosshair", "vline".

The same string add_widget() dispatches on (and widget.get("type") returns), so code holding only a widget can branch on what it is without isinstance checks.

property plot#

The plot this widget is attached to, or None.

None for a widget constructed standalone, and again once the widget has been removed (remove(), plot.remove_widget or plot.clear_widgets).