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 codekey_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
See also:
- Interactivity for camera and panzoom controls
- Events for timers, frames, and GUI callbacks