User Input¶

Datoviz supports interactive user input via mouse and keyboard event callbacks. These events can be attached to a Figure using the @app.connect() decorator, which automatically routes events based on the function name.

Overview¶

Event callbacks respond to:

Mouse events (click, drag, wheel, move)
Keyboard events (key press and release)

Each event is handled per figure and can be accessed using a simple decorator-based API.

Connecting input events¶

To register input callbacks, decorate a function with:

@app.connect(figure) def on_mouse(ev): ...

The function name determines the event type:

Function name	Triggered by
`on_mouse`	Mouse actions
`on_keyboard`	Keyboard actions

Mouse events¶

Mouse events include actions like move, click, drag, and scroll:

@app.connect(figure) def on_mouse(ev): action = ev.mouse_event() x, y = ev.pos() print(f'{action} at ({x:.0f}, {y:.0f})') if action in ('click', 'double_click'): print(f'{ev.button_name()} button') if action in ('drag', 'drag_start', 'drag_stop'): print(f'{ev.button_name()} drag from {ev.press_pos()}') if action == 'wheel': print(f'wheel scroll {ev.wheel()}')

Mouse event properties¶

Method	Description
`ev.mouse_event()`	Current mouse event name
`ev.pos()`	Current mouse position `(x, y)`
`ev.press_pos()`	Mouse press position during a drag
`ev.button()`	Raw button enum (int)
`ev.button_name()`	Button name: `'left'`, `'right'`, `'middle'`
`ev.wheel()`	Vertical wheel scroll amount (float)

Example¶

import datoviz as dvz app = dvz.App() figure = app.figure() @app.connect(figure) def on_mouse(ev): action = ev.mouse_event() x, y = ev.pos() print(f'{action} ({x:.0f}, {y:.0f}) ', end='') if action in ('click', 'double_click'): button = ev.button_name() print(f'{button} button', end='') if action in ('drag_start', 'drag_stop', 'drag'): button = ev.button_name() xd, yd = ev.press_pos() print(f'{button} button pressed at ({xd:.0f}, {yd:.0f})', end='') if action == 'wheel': w = ev.wheel() print(f'wheel direction {w}', end='') print() app.run() app.destroy()

Keyboard events¶

Keyboard callbacks receive key presses and releases:

@app.connect(figure) def on_keyboard(ev): print(f'{ev.key_event()} key {ev.key()} ({ev.key_name()})')

Each event contains:

key(): the integer key code
key_name(): the name of the key (e.g. 'Escape', 'A')
key_event(): 'press' or 'release'

Keyboard event properties¶

Method	Description
`ev.key_event()`	Current keyboard event name
`ev.key()`	Raw key code enum (int)
`ev.key_name()`	Key name string, e.g. `'a'`, `'Escape'`

Example¶

import datoviz as dvz app = dvz.App() figure = app.figure() @app.connect(figure) def on_keyboard(ev): print(f'{ev.key_event()} key {ev.key()} ({ev.key_name()})') app.run() app.destroy()

Summary¶

✔️ Simple decorator-based API
✔️ Per-figure event handling
✔️ Full mouse and keyboard support