Interactive Widgets#

widgets.py — Interactive overlay widget classes.

Each widget has a .callbacks (CallbackRegistry). Register handlers via:

@rect.on_changed        # every drag frame
def live(event): ...

@rect.on_release        # once on mouseup
def done(event): ...

@rect.on_click
def clicked(event): ...

rect.x = 40             # moves widget, sends targeted update to JS
rect.x                  # always reflects current JS position

Base Class

Widget

Base class for all overlay widgets.

Concrete Widgets

RectangleWidget

Draggable rectangle overlay widget for 2-D plots.

CircleWidget

Draggable circle overlay widget for 2-D plots.

AnnularWidget

Draggable annular (ring) overlay widget for 2-D plots.

CrosshairWidget

Draggable crosshair overlay widget for 2-D plots.

PolygonWidget

Draggable polygon overlay widget for 2-D plots.

LabelWidget

Text label overlay widget for 2-D plots.

VLineWidget

Draggable vertical line overlay widget for 1-D plots.

HLineWidget

Draggable horizontal line overlay widget for bar charts.

RangeWidget

Draggable range selection widget.

Full Reference

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

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

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

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

Return a dict copy of the widget state.

Returns:

All widget properties including id and type.

Return type:

dict

on_changed(fn)[source]

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

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

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

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

Show the widget. Does not fire on_changed 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 on_changed callbacks.

Return type:

None

property id: str

Return the widget’s unique identifier.

class anyplotlib.widgets.RectangleWidget(push_fn, *, x, y, w, h, color='#00e5ff')[source]

Bases: Widget

Draggable rectangle overlay widget for 2-D plots.

Parameters:

  • push_fn (Callable) – Update callback.

  • x (float) – Top-left corner position in pixel/data coordinates.

  • y (float) – Top-left corner position in pixel/data coordinates.

  • w (float) – Width and height in pixel/data coordinates.

  • h (float) – Width and height in pixel/data coordinates.

  • color (str, optional) – CSS colour for the rectangle outline. Default "#00e5ff".

class anyplotlib.widgets.CircleWidget(push_fn, *, cx, cy, r, color='#00e5ff')[source]

Bases: Widget

Draggable circle overlay widget for 2-D plots.

Parameters:

  • push_fn (Callable) – Update callback.

  • cx (float) – Center position in pixel/data coordinates.

  • cy (float) – Center position in pixel/data coordinates.

  • r (float) – Radius in pixel/data coordinates.

  • color (str, optional) – CSS colour for the circle outline. Default "#00e5ff".

class anyplotlib.widgets.AnnularWidget(push_fn, *, cx, cy, r_outer, r_inner, color='#00e5ff')[source]

Bases: Widget

Draggable annular (ring) overlay widget for 2-D plots.

Parameters:

  • push_fn (Callable) – Update callback.

  • cx (float) – Center position in pixel/data coordinates.

  • cy (float) – Center position in pixel/data coordinates.

  • r_outer (float) – Outer and inner radii in pixel/data coordinates. Inner radius must be less than outer radius.

  • r_inner (float) – Outer and inner radii in pixel/data coordinates. Inner radius must be less than outer radius.

  • color (str, optional) – CSS colour for the ring outline. Default "#00e5ff".

Raises:

ValueError – If r_inner >= r_outer.

class anyplotlib.widgets.CrosshairWidget(push_fn, *, cx, cy, color='#00e5ff')[source]

Bases: Widget

Draggable crosshair overlay widget for 2-D plots.

Parameters:

  • push_fn (Callable) – Update callback.

  • cx (float) – Center position in pixel/data coordinates.

  • cy (float) – Center position in pixel/data coordinates.

  • color (str, optional) – CSS colour for the crosshair. Default "#00e5ff".

class anyplotlib.widgets.PolygonWidget(push_fn, *, vertices, color='#00e5ff')[source]

Bases: Widget

Draggable polygon overlay widget for 2-D plots.

Parameters:

  • push_fn (Callable) – Update callback.

  • vertices (list of (x, y) tuples) – Polygon vertices in pixel/data coordinates. Must have at least 3 vertices.

  • color (str, optional) – CSS colour for the polygon outline. Default "#00e5ff".

Raises:

ValueError – If fewer than 3 vertices provided.

class anyplotlib.widgets.LabelWidget(push_fn, *, x, y, text='Label', fontsize=14, color='#00e5ff')[source]

Bases: Widget

Text label overlay widget for 2-D plots.

Parameters:

  • push_fn (Callable) – Update callback.

  • x (float) – Label position in pixel/data coordinates.

  • y (float) – Label position in pixel/data coordinates.

  • text (str, optional) – Label text. Default "Label".

  • fontsize (int, optional) – Font size in points. Default 14.

  • color (str, optional) – CSS colour for the text. Default "#00e5ff".

class anyplotlib.widgets.VLineWidget(push_fn, *, x, color='#00e5ff')[source]

Bases: Widget

Draggable vertical line overlay widget for 1-D plots.

Allows interactive selection of a single x-axis value. The line can be dragged left/right to change the selected position.

Parameters:

  • push_fn (Callable) – Update callback.

  • x (float) – Initial x-position in data coordinates.

  • color (str, optional) – CSS colour for the line. Default "#00e5ff".

class anyplotlib.widgets.HLineWidget(push_fn, *, y, color='#00e5ff')[source]

Bases: Widget

Draggable horizontal line overlay widget for bar charts.

Allows interactive selection of a single y-axis value. The line can be dragged up/down to change the selected value.

Parameters:

  • push_fn (Callable) – Update callback.

  • y (float) – Initial y-position in data coordinates.

  • color (str, optional) – CSS colour for the line. Default "#00e5ff".

class anyplotlib.widgets.RangeWidget(push_fn, *, x0, x1, color='#00e5ff', style='band', y=0.0)[source]

Bases: Widget

Draggable range selection widget.

Two display styles are available:

style='band' (default)

Two connected vertical lines with a translucent fill band. Either line can be dragged independently; the whole band can be dragged by clicking inside it.

style='fwhm'

Two circular handles joined by a dashed horizontal line drawn at height y (the half-maximum level). Only the x-positions of the handles are draggable. Use this to show/edit a FWHM interval on a peak.

Parameters:

  • push_fn (Callable) – Update callback.

  • x0 (float) – Initial left and right positions in data coordinates.

  • x1 (float) – Initial left and right positions in data coordinates.

  • color (str, optional) – CSS colour. Default "#00e5ff".

  • style ({'band', 'fwhm'}, optional) – Visual style. Default "band".

  • y (float, optional) – Y-position (data coordinates) for the connecting line when style='fwhm'. Ignored for style='band'. Default 0.0.