Skip to content

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

See also: