Skip to content
Feeding a clanker? Grab this page as raw .md →

AnnotationWidget API#

Bases: AnyWidget

Annotation input widget with buttons, keyboard shortcuts, gamepad, and speech-to-text.

This widget provides a UI input surface for annotation workflows. It does NOT render the object being annotated — the notebook handles content display and reacts to the action traitlet.

The action_timestamp traitlet changes on every action, even repeated ones, so observe always fires.

Examples:

from wigglystuff import AnnotationWidget

widget = AnnotationWidget()
widget
Source code in wigglystuff/annotation.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def __init__(
    self,
    *,
    actions: Optional[Sequence[str]] = None,
    keyboard_mapping: Optional[dict[str, str]] = None,
    gamepad_mapping: Optional[dict[str, str]] = None,
    debounce_ms: Optional[int] = None,
    width: Optional[int] = None,
    **kwargs: Any,
) -> None:
    init_kwargs: dict[str, Any] = {}
    if actions is not None:
        init_kwargs["actions"] = list(actions)
    if keyboard_mapping is not None:
        init_kwargs["keyboard_mapping"] = dict(keyboard_mapping)
    if gamepad_mapping is not None:
        init_kwargs["gamepad_mapping"] = dict(gamepad_mapping)
    if debounce_ms is not None:
        init_kwargs["debounce_ms"] = debounce_ms
    if width is not None:
        init_kwargs["width"] = width
    super().__init__(**init_kwargs, **kwargs)

Synced traitlets#

Traitlet Type Notes
action str Name of the most recently triggered action (e.g., accept, fail).
action_timestamp float Timestamp (ms since epoch) of the latest action; changes on every trigger so observe always fires, even for repeats.
note str Free-form note text, populated by typing or speech-to-text.
listening bool True while speech-to-text is actively transcribing.
disabled bool When True, all input controls are inert.
show_save bool Toggles visibility of the Save button.
actions list[str] Ordered list of action button labels. Defaults to ["previous", "accept", "fail", "defer", "save"].
keyboard_mapping dict[str, str] Maps keys to action names. The special target mic toggles the speech-to-text microphone.
gamepad_mapping dict[str, str] Maps gamepad button indices (as strings) to action names. The mic target works here too.
debounce_ms int Minimum interval between accepted action triggers, in milliseconds.
width int Widget width in pixels.