A custom widget for returning mouse and keyboard events to Python

2.0.4 · active · verified Wed Apr 15

ipyevents provides a custom widget for capturing and returning mouse and keyboard events from Jupyter widgets to Python. It enables adding interactive features like keyboard shortcuts, reacting to clicks on images, and handling arbitrary mouse/keyboard events within a Jupyter environment. The current version is 2.0.4, targeting JupyterLab 3 and above. Releases are driven by compatibility with JupyterLab versions and feature additions.

Warnings

breaking ipyevents versions 2.0.0 and higher are only built for JupyterLab 3 and up. If you are using JupyterLab 2, you must use ipyevents version 0.9.0 or earlier.
Fix: Ensure your ipyevents version matches your JupyterLab version. Upgrade JupyterLab to version 3+ for ipyevents 2.x, or downgrade ipyevents to 0.9.0 or earlier for JupyterLab 2.
gotcha When watching keyboard events, ipyevents will grab the focus of the browser on the source widget. This prevents key presses from being passed to the notebook's default handlers (e.g., for cell navigation or commands).
Fix: Be aware that keyboard input will be directed to the watched widget. This is intended behavior to prevent accidental notebook actions. You can style the focused element (e.g., with a blue border) to make it clear which element has focus.
gotcha High-frequency events like 'mousemove' or 'wheel' can generate a large volume of messages between the frontend and backend, potentially leading to performance issues.
Fix: Utilize the `throttle_or_debounce` and `wait` parameters of the `Event` widget to limit the rate at which events are passed to Python. 'throttle' is good for `mousemove`/`wheel`, 'debounce' for limiting repeated key strokes or clicks.
gotcha The `prevent_default_action` property may not function correctly for 'wheel' events, meaning the browser's default scroll behavior might still occur.
Fix: If `prevent_default_action` is critical for 'wheel' events, test thoroughly. Consider alternative approaches or monitor the GitHub issues for a fix. There is no direct workaround mentioned in documentation.

Install

pip install ipyevents Install with pip

Imports

Event
```
from ipyevents import Event
```

Quickstart

This quickstart creates a Label widget and an Event listener attached to it. It watches for 'click', 'keydown', and 'mouseenter' events, displaying event information in an HTML widget. This demonstrates how to capture browser events and process them in Python.

from ipywidgets import Label, HTML, display
from ipyevents import Event

l = Label('Click or type on me!')
l.layout.border = '2px solid red'
h = HTML('Event info')

d = Event(source=l, watched_events=['click', 'keydown', 'mouseenter'])

def handle_event(event):
    lines = [f'{k}: {v}' for k, v in event.items()]
    content = '<br>'.join(lines)
    h.value = content

d.on_dom_event(handle_event)

display(l, h)

view raw JSON →