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