# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""App: devices, events, display refresh and lifecycle, on multimer's timers.
An ``App`` owns no timer machinery of its own. ``app.every(ms, fn)`` is
``multimer.every``; the device service tick and each display's refresh are
ordinary timers you can see in ``multimer.report()``; and staying alive past
the end of the script body is ``multimer.keepalive``, which the App sets
when it has a display or a subscription. So a script that builds its UI and
ends keeps running, at the prompt under ``-i`` and in the exit hook
otherwise, with or without LVGL, and ``app.run()`` is only for a program
that wants to block.
"""
import sys
import events
import keys
import multimer
from multimer import _hostloop
from .devices import (
ENCODER,
HOST,
JOYSTICK,
KEYPAD,
POINTER,
Encoder,
HostEvents,
Joystick,
Keypad,
Touch,
)
DEFAULT_REFRESH_MS = 33
SERVICE_TICK_MS = 10
class _RefreshClaim:
def __init__(self, app):
self._app = app
def release(self):
self._app.resume_refresh()
class _PollingClaim:
def __init__(self, app):
self._app = app
def release(self):
self._app.resume_polling()
class _RefreshPaused:
def __init__(self, app):
self._app = app
self._claim = None
def __enter__(self):
self._claim = self._app.pause_refresh()
return self._claim
def __exit__(self, exc_type, exc_val, exc_tb):
if self._claim is not None:
self._claim.release()
return False
[docs]
class App:
"""Application coordinator: devices, event dispatch, display refresh, lifecycle."""
_current = None
events = events
keys = keys
HOST = HOST
POINTER = POINTER
ENCODER = ENCODER
KEYPAD = KEYPAD
JOYSTICK = JOYSTICK
[docs]
@classmethod
def current(cls):
"""Return the currently active App instance, or None."""
return cls._current
def __init__(
self,
board_config=None,
*,
displays=None,
host_read=None,
touch_read=None,
touch_rotation_table=None,
refresh_period=None,
):
prev = App._current
if prev is not None and prev is not self:
# A second App in one process (sequential apps, a test suite):
# the first one's timers must not keep dispatching into it.
try:
prev.stop_timers()
except Exception:
pass
App._current = self
self.devices = []
self._event_callbacks = {}
self._subscriptions = []
self._before_quit = None
self._on_quit = []
self._quit_requested = False
self._exit_code = None
self._refresh_timers = []
self._refresh_period = refresh_period
self._refresh_paused = False
self._refresh_claim = None
self._service_timer = None
self._polling_claim = None
self._app_drives_poll = False
self._in_service_poll = False
self._teardown_done = False
if displays is not None:
self._displays = list(displays)
elif board_config is not None and getattr(board_config, "display_drv", None) is not None:
self._displays = [board_config.display_drv]
elif board_config is not None and hasattr(board_config, "width") and hasattr(board_config, "height"):
self._displays = [board_config]
else:
self._displays = []
for drv in self._displays:
try:
drv.app = self
except Exception:
pass
primary = self.primary
effective_host_read = (
host_read
if host_read is not None
else getattr(board_config, "host_read", None) or getattr(board_config, "get_events", None)
)
if effective_host_read is not None:
self.host_dev = HostEvents(host_read=effective_host_read, display=primary)
self.register(self.host_dev)
else:
self.host_dev = None
effective_touch_read = touch_read if touch_read is not None else getattr(board_config, "touch_read", None)
effective_touch_table = (
touch_rotation_table
if touch_rotation_table is not None
else getattr(board_config, "touch_rotation_table", None)
)
if effective_touch_read is not None:
self.touch_dev = self.add_touch(
effective_touch_read, display=primary, rotation_table=effective_touch_table
)
else:
self.touch_dev = None
keypad_read = getattr(board_config, "keypad_read", None)
if keypad_read is not None:
self.add_keypad(keypad_read)
else:
self.keypad_dev = None
encoder_read = getattr(board_config, "encoder_read", None)
if encoder_read is not None:
self.add_encoder(encoder_read, button_read=getattr(board_config, "encoder_button_read", None))
else:
self.encoder_dev = None
joystick_driver = getattr(board_config, "joystick_driver", None)
if joystick_driver is not None:
emulate_digital = getattr(board_config, "joystick_emulate_digital", None)
self.add_joystick(joystick_driver=joystick_driver, emulate_digital=emulate_digital)
else:
self.joystick_dev = None
_hostloop.on_stop(self._teardown_from_loop)
if self._displays:
self._wire_display_refresh(self._refresh_period)
self._keep_alive()
# -- properties --------------------------------------------------------
@property
def strategy(self):
"""How the program stays alive past the script body (see ``multimer.strategy``)."""
return multimer.strategy()
@property
def displays(self):
return tuple(self._displays)
@property
def primary(self):
return self._displays[0] if self._displays else None
@property
def quit_requested(self):
return self._quit_requested
@property
def before_quit(self):
return self._before_quit
@before_quit.setter
def before_quit(self, value):
if value is not None and not callable(value):
raise ValueError("before_quit must be callable")
self._before_quit = value
[docs]
def on_quit(self, callback):
"""Call *callback()* at quit, after ``before_quit``, in the order added.
Unlike ``before_quit``, any number of callbacks can be added, and
adding one never replaces another. Returns *callback*, so it works
as a decorator. An exception in one is printed and the rest still run.
"""
if not callable(callback):
raise ValueError("on_quit needs a callable")
self._on_quit.append(callback)
return callback
@property
def timers(self):
"""The App's own timers: service, refresh and every() subscriptions."""
out = []
if self._service_timer is not None:
out.append(self._service_timer)
out.extend(self._refresh_timers)
out.extend(t for t in self._subscriptions if t.running)
return tuple(out)
# -- displays and devices ---------------------------------------------
def add_display(self, drv):
if drv is None:
raise ValueError("drv is required")
if drv in self._displays:
return drv
first = not self._displays
self._displays.append(drv)
try:
drv.app = self
except Exception:
pass
if first:
self._wire_display_refresh(self._refresh_period)
self._keep_alive()
elif getattr(drv, "needs_refresh", False):
self._wire_one_refresh(drv, self._refresh_period)
return drv
def remove_display(self, drv):
if drv not in self._displays:
return
was_primary = drv is self.primary
self._displays.remove(drv)
for t in tuple(self._refresh_timers):
if getattr(t, "_display", None) is drv:
t.deinit()
self._refresh_timers.remove(t)
try:
drv.app = None
except Exception:
pass
if callable(getattr(drv, "quit", None)):
try:
drv.quit()
except Exception:
pass
elif callable(getattr(drv, "deinit", None)):
try:
drv.deinit()
except Exception:
pass
if was_primary or not self._displays:
self.request_quit()
def add_touch(self, read, *, display=None, rotation_table=None):
if display is None:
display = self.primary
if display is None:
raise ValueError("Touch requires a display")
touch = Touch(read=read, display=display, rotation_table=rotation_table)
self.register(touch)
if display is self.primary:
self.touch_dev = touch
return touch
def add_keypad(self, read):
keypad = Keypad(read=read)
self.register(keypad)
self.keypad_dev = keypad
return keypad
def add_encoder(self, read, *, button_read=None, button=2):
encoder = Encoder(read=read, button_read=button_read, button=button)
self.register(encoder)
self.encoder_dev = encoder
return encoder
def add_joystick(self, joystick_driver, *, emulate_digital=None, digital_threshold=0.5):
joystick = Joystick(
joystick_driver=joystick_driver,
emulate_digital=emulate_digital,
digital_threshold=digital_threshold,
)
self.register(joystick)
self.joystick_dev = joystick
return joystick
def register(self, dev):
dev.app = self
if dev not in self.devices:
self.devices.append(dev)
self._arm_service()
def unregister(self, dev):
if dev in self.devices:
self.devices.remove(dev)
dev.app = None
# -- events ---------------------------------------------------------------
[docs]
def on(self, event_type_or_list, callback=None):
"""Subscribe callback to one or more event types, or use as a decorator."""
if callback is None:
return lambda fn: self.on(event_type_or_list, fn)
if not callable(callback):
raise ValueError("callback must be callable")
if isinstance(event_type_or_list, (list, tuple, set)):
for et in event_type_or_list:
self.on(et, callback)
return callback
callback_set = self._event_callbacks.get(event_type_or_list)
if callback_set is None:
callback_set = set()
self._event_callbacks[event_type_or_list] = callback_set
callback_set.add(callback)
return callback
[docs]
def off(self, event_type_or_list, callback):
"""Unsubscribe callback from one or more event types."""
if isinstance(event_type_or_list, (list, tuple, set)):
for et in event_type_or_list:
self.off(et, callback)
return
callback_set = self._event_callbacks.get(event_type_or_list)
if callback_set:
callback_set.discard(callback)
# -- timers -----------------------------------------------------------
[docs]
def every(self, ms=None, callback=None, *, period=None, name=None):
"""A periodic ``multimer.Timer`` calling ``callback(timer)`` every *ms*.
The callback receives the timer, so a method needs the signature
``def step(self, timer=None)``. Usable as a decorator
(``@app.every(1000)``). The App keeps the
process alive while any subscription runs; ``timer.deinit()`` (or
``cancel()``) ends one.
"""
if period is not None:
if callable(ms) and callback is None:
callback = ms
ms = period
if ms is None and period is None:
ms = SERVICE_TICK_MS
if callback is None:
if callable(ms):
callback = ms
ms = SERVICE_TICK_MS
else:
return lambda fn: self.every(ms, fn, name=name)
if not callable(callback):
raise ValueError("callback must be callable")
tim = multimer.every(int(ms), callback, name=name)
self._subscriptions.append(tim)
self._keep_alive()
return tim
[docs]
def on_tick(self, callback, period=SERVICE_TICK_MS, **_ignored):
"""Schedule a periodic callback (alias of `every`)."""
return self.every(period, callback)
[docs]
def stop_timers(self):
"""Stop the service tick, every refresh and every subscription."""
st = self._service_timer
self._service_timer = None
if st is not None:
st.deinit()
for t in self._refresh_timers:
t.deinit()
self._refresh_timers = []
for t in self._subscriptions:
t.deinit()
self._subscriptions = []
self._refresh_paused = False
self._refresh_claim = None
stop_timer = stop_timers
def _keep_alive(self):
multimer.keepalive(True)
# -- refresh ----------------------------------------------------------
[docs]
def pause_refresh(self):
"""Pause display refresh while a GUI renders frames."""
if self._refresh_claim is not None:
raise RuntimeError("display refresh already claimed/paused")
self._refresh_paused = True
self._refresh_claim = _RefreshClaim(self)
return self._refresh_claim
[docs]
def resume_refresh(self):
"""Resume display refresh after pausing."""
if self._refresh_claim is None:
return
self._refresh_paused = False
self._refresh_claim = None
[docs]
def refresh_paused(self):
"""Context manager to pause display refresh within a block."""
return _RefreshPaused(self)
[docs]
def pause_polling(self):
"""Stop the service tick reading the devices: the caller reads them.
A GUI that polls the input devices itself (LVGL reads its indevs
from its own timers) claims the devices with this, or the service
tick consumes the events first. ``release()`` the claim to resume.
"""
if self._polling_claim is not None:
raise RuntimeError("device polling already claimed")
self._polling_claim = _PollingClaim(self)
return self._polling_claim
def resume_polling(self):
self._polling_claim = None
def _wire_display_refresh(self, refresh_period):
self._arm_service()
for display in self._displays:
self._wire_one_refresh(display, refresh_period)
def _wire_one_refresh(self, display, refresh_period):
if refresh_period is None:
if not getattr(display, "needs_refresh", False):
return
period = int(getattr(display, "refresh_period_ms", 0) or DEFAULT_REFRESH_MS)
else:
period = int(refresh_period)
if period <= 0:
return
if not callable(getattr(display, "show", None)):
return
# Look show up on every tick: a wrapper installed after the App started
# (displaydev's measure_fps) must be the one that is called.
def _show(timer_obj, _display=display):
if self._refresh_paused:
return
_display.show(timer_obj)
name = "refresh:%s" % (getattr(display, "__class__", type(display)).__name__,)
tim = multimer.every(period, _show, name=name)
tim._display = display
self._refresh_timers.append(tim)
# -- service ----------------------------------------------------------
def _arm_service(self):
if self._service_timer is not None or not self.devices and not self._displays:
return
self._service_timer = multimer.every(SERVICE_TICK_MS, self._service_tick, name="app.service")
def _service_tick(self, timer_obj):
if self._quit_requested or self._app_drives_poll or self._polling_claim is not None:
return
self._in_service_poll = True
try:
self.poll()
finally:
self._in_service_poll = False
[docs]
def poll(self):
"""Poll registered devices and dispatch any pending events.
A program that calls this from its own loop takes over from the
service timer; delivery of every other timer happens here too.
"""
if not self._in_service_poll:
self._app_drives_poll = True
multimer.pump()
multimer.run_deadline_hook()
eventlist = []
for device in tuple(self.devices):
dev_events = device.poll()
if dev_events:
eventlist.extend(dev_events)
for event in dev_events:
if event.type == events.QUIT:
self._handle_quit()
callbacks = self._event_callbacks.get(event.type)
if callbacks:
for cb in tuple(callbacks):
cb(event)
return eventlist
# -- lifecycle --------------------------------------------------------
[docs]
def run(self, tick_ms=SERVICE_TICK_MS):
"""Block until quit, delivering timers and events. Optional.
Returns at once where the host already owns a loop that keeps the
program running (a REPL under ``-i``, a browser page, a notebook).
"""
if multimer.strategy() == _hostloop.AMBIENT:
return
_hostloop.claim()
try:
multimer.run_until(lambda: self._teardown_done, tick_ms)
finally:
_hostloop.release()
self._raise_exit_code()
[docs]
def run_async(self, coro_or_fn):
"""Run a coroutine (or a factory of one) under the host's asyncio loop.
Schedules it as a task where a loop is already running (Jupyter,
PyScript) and returns the task; otherwise ``asyncio.run`` blocks.
"""
aio = multimer.asyncio
if aio is None:
raise RuntimeError("asyncio is not available")
async def runner():
coro = coro_or_fn() if callable(coro_or_fn) else coro_or_fn
return await coro
if multimer.loop_running():
return aio.create_task(runner())
return aio.run(runner())
[docs]
def request_quit(self, code=None):
"""Request a clean application shutdown."""
if code is not None:
self._exit_code = int(code)
self._handle_quit()
def _handle_quit(self):
if self._quit_requested:
return
self._quit_requested = True
self._refresh_paused = True
self._perform_teardown()
def _teardown_from_loop(self):
self._perform_teardown()
def _perform_teardown(self):
if self._teardown_done:
return
self._teardown_done = True
self._quit_requested = True
if App._current is self:
App._current = None
if self._before_quit is not None:
try:
self._before_quit()
except Exception:
pass
for callback in tuple(self._on_quit):
try:
callback()
except Exception as exc:
pe = getattr(sys, "print_exception", None)
if pe is not None:
pe(exc)
else:
import traceback
traceback.print_exception(type(exc), exc, exc.__traceback__)
self.stop_timers()
for display in tuple(self._displays):
if callable(getattr(display, "quit", None)):
try:
display.quit()
except Exception:
pass
self._displays.clear()
# Nothing of ours is left to keep the process alive.
multimer.keepalive(False)
def _raise_exit_code(self):
code = self._exit_code
if code is not None:
self._exit_code = None
raise SystemExit(code)