displaypad-lib 1.0.0__tar.gz

displaypad_lib-1.0.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: displaypad-lib
+Version: 1.0.0
+Summary: A library to easily interact with the Mountain Displaypad
+License: MIT
+Author: AnnikenToGo
+Author-email: anniken@annikentogo.de
+Requires-Python: >=3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: displaypad-driver (>=1.0.0)
+Requires-Dist: pillow (>=12.1.0,<13.0.0)
+Description-Content-Type: text/markdown
+
+# displaypad-lib package
+
+`displaypad-lib` provides a high-level, multi-page library for interacting with the Mountain DisplayPad device, built on top of `displaypad-driver`.
+
+## Acknowledgments
+Multi-page layout engine design, auto-timeout page transitions, and responsive async rendering were built with inspiration from [ramisotti13-eng/BaseCamp-Linux](https://github.com/ramisotti13-eng/BaseCamp-Linux).
+
+## Key Features
+
+- **Multi-Page Layout Engine (`Page`, `PageManager`)**: Create named 12-key pages with navigation stacks and auto-timeout transitions (`mode: "after" | "idle"`). See [docs/lib/page.md](../../docs/lib/page.md).
+- **Key Abstractions (`displaypad_lib.key`)**:
+  - `Key` (base class) — Implement `render(ctx: KeyContext)` and optional lifecycle hooks (`on_mount`, `on_press`, `on_release`, `on_double_press`, `on_long_press`, `on_tick`).
+  - `GifKey` — Play animated GIFs at native frame rates with rotation support.
+  - `IconKey` — Static image icons with aspect-ratio scaling and margins.
+  - `LabelKey` — Dynamic centered text labels with customizable colors.
+  - `FramerateLimitedKey` — Rate-limited key rendering.
+  - `LoggerKey` — Diagnostics key logging presses and releases.
+- **Drawing Context (`KeyContext`)**:
+  - Key-relative drawing primitives: `center_text`, `text`, `rectangle`, `ellipse`, `line`, `polygon`, `arc`, `fill`, `clear`, `paste_image`. Supports both `color` and `fill` parameter aliases.
+- **Async Queue & Hybrid Batch Rendering**:
+  - Background thread drains key updates with frame deduplication. Single-key updates use fast per-button tile uploads; layout changes automatically batch update the full panel.
+
+For usage examples, see [lib_example.py](../../examples/lib_example.py) and [clock.py](../../examples/clock.py).

displaypad_lib-1.0.0/README.md

@@ -0,0 +1,23 @@
+# displaypad-lib package
+
+`displaypad-lib` provides a high-level, multi-page library for interacting with the Mountain DisplayPad device, built on top of `displaypad-driver`.
+
+## Acknowledgments
+Multi-page layout engine design, auto-timeout page transitions, and responsive async rendering were built with inspiration from [ramisotti13-eng/BaseCamp-Linux](https://github.com/ramisotti13-eng/BaseCamp-Linux).
+
+## Key Features
+
+- **Multi-Page Layout Engine (`Page`, `PageManager`)**: Create named 12-key pages with navigation stacks and auto-timeout transitions (`mode: "after" | "idle"`). See [docs/lib/page.md](../../docs/lib/page.md).
+- **Key Abstractions (`displaypad_lib.key`)**:
+  - `Key` (base class) — Implement `render(ctx: KeyContext)` and optional lifecycle hooks (`on_mount`, `on_press`, `on_release`, `on_double_press`, `on_long_press`, `on_tick`).
+  - `GifKey` — Play animated GIFs at native frame rates with rotation support.
+  - `IconKey` — Static image icons with aspect-ratio scaling and margins.
+  - `LabelKey` — Dynamic centered text labels with customizable colors.
+  - `FramerateLimitedKey` — Rate-limited key rendering.
+  - `LoggerKey` — Diagnostics key logging presses and releases.
+- **Drawing Context (`KeyContext`)**:
+  - Key-relative drawing primitives: `center_text`, `text`, `rectangle`, `ellipse`, `line`, `polygon`, `arc`, `fill`, `clear`, `paste_image`. Supports both `color` and `fill` parameter aliases.
+- **Async Queue & Hybrid Batch Rendering**:
+  - Background thread drains key updates with frame deduplication. Single-key updates use fast per-button tile uploads; layout changes automatically batch update the full panel.
+
+For usage examples, see [lib_example.py](../../examples/lib_example.py) and [clock.py](../../examples/clock.py).

displaypad_lib-1.0.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "displaypad-lib"
+version = "1.0.0"
+description = "A library to easily interact with the Mountain Displaypad"
+authors = [
+    {name = "AnnikenToGo",email = "anniken@annikentogo.de"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "pillow (>=12.1.0,<13.0.0)",
+    "displaypad-driver>=1.0.0"
+]
+
+
+
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

displaypad_lib-1.0.0/src/displaypad_lib/__init__.py

@@ -0,0 +1,22 @@
+"""DisplayPad Library Package"""
+
+from .displaypad import DisplayPad
+from .key import Key, FramerateLimitedKey, LoggerKey, IconKey, GifKey, LabelKey
+from .page import Page, PageManager
+
+__version__ = "1.0.0"
+
+
+__all__ = [
+    '__version__',
+    'DisplayPad',
+
+    'Key',
+    'FramerateLimitedKey',
+    'LoggerKey',
+    'IconKey',
+    'GifKey',
+    'LabelKey',
+    'Page',
+    'PageManager',
+]

displaypad_lib-1.0.0/src/displaypad_lib/displaypad.py

@@ -0,0 +1,324 @@
+from PIL import Image, ImageDraw
+from .key import Key
+from .keycontext import KeyContext
+from displaypad_driver import DisplayPad as Driver
+from logging import getLogger
+
+log = getLogger(__name__)
+
+class DisplayPad:
+    """Main DisplayPad class managing keys, multi-page layouts, and async display rendering."""
+
+import logging
+import queue
+import threading
+import time
+from typing import Dict, List, Optional, Union
+from PIL import Image, ImageDraw
+
+from displaypad_driver import DisplayPad as Driver, ICON_SIZE, KEYS_PER_ROW, NUM_KEYS
+from displaypad_driver.image import image_to_bgr102, split_image_to_tiles
+from .key import Key
+from .keycontext import KeyContext
+from .page import Page, PageManager
+
+log = logging.getLogger(__name__)
+
+
+class DisplayPad:
+    """Main DisplayPad high-level manager class.
+
+    Usage:
+    ```python
+    pad = DisplayPad()
+    pad[0] = LoggerKey(0)
+    while True:
+        pad.update()
+    ```
+    """
+
+    def __init__(self, rotation: int = 0, debounce_sec: float = 0.01, dc_window: float = 0.6):
+        self.driver = Driver()
+        self.width = 800
+        self.height = 240
+        self.rotation = rotation
+        self.debounce_sec = debounce_sec
+        self.dc_window = dc_window
+        self.dc_antibounce = 0.02
+
+
+        self.image_buffer = Image.new("RGB", (self.width, self.height))
+        self.page_manager = PageManager()
+        self._synced_keys: List[Optional[object]] = [object()] * NUM_KEYS
+        self._key_down_state: List[bool] = [False] * NUM_KEYS
+
+        # Input timing state
+        self._last_fire_time: Dict[int, float] = {}
+        self._press_start_time: Dict[int, float] = {}
+        self._dc_timers: Dict[int, float] = {}  # key_index -> timer_start_time
+        self._dc_pending_single: Dict[int, bool] = {}
+
+        # Async tile render queue & lock
+        self._render_queue: queue.Queue = queue.Queue()
+        self._queue_worker_stop = threading.Event()
+        self._worker_thread = threading.Thread(target=self._async_render_loop, daemon=True)
+        self._worker_thread.start()
+
+    # --- Property Shortcuts ---
+
+    @property
+    def keys(self) -> List[Optional[Key]]:
+        return self.page_manager.get_current_page().keys
+
+    def __getitem__(self, index: int) -> Optional[Key]:
+        return self.page_manager.get_current_page()[index]
+
+    def __setitem__(self, index: int, key_instance: Optional[Key]):
+        self.page_manager.get_current_page()[index] = key_instance
+        self._synced_keys[index] = object()  # Force re-sync on next update
+
+    def add_page(self, page_id: Union[str, int], page: Page):
+        """Register a new Page layout. If adding/updating the active page, repaints the panel."""
+        self.page_manager.add_page(page_id, page)
+        current = self.page_manager.current_page_id
+        if page_id == current or page.name == current:
+            # Force re-sync of active page keys
+            self._synced_keys = [object()] * NUM_KEYS
+            current_page = self.page_manager.get_current_page()
+            draw = ImageDraw.Draw(self.image_buffer)
+            draw.rectangle([0, 0, self.width, self.height], fill=(0, 0, 0))
+            for idx in range(NUM_KEYS):
+                key = current_page.keys[idx]
+                if key:
+                    key.on_mount(idx)
+                    self._render_key_to_buffer(idx, key)
+                    key._needs_redraw = False
+            self.push_image()
+
+
+    def switch_to_page(self, page_id: Union[str, int]) -> bool:
+        """Switch active page and request full panel redraw."""
+        success = self.page_manager.switch_to(page_id)
+        if success:
+            current_page = self.page_manager.get_current_page()
+            # Render all keys of new page onto image_buffer
+            draw = ImageDraw.Draw(self.image_buffer)
+            draw.rectangle([0, 0, self.width, self.height], fill=(0, 0, 0))
+            for idx in range(NUM_KEYS):
+                key = current_page.keys[idx]
+                if key:
+                    self._render_key_to_buffer(idx, key)
+                    key._needs_redraw = False
+            self.push_image()
+        return success
+
+    def set_brightness(self, percent: int):
+        """Set hardware backlight brightness (0-100%)."""
+        self.driver.set_brightness(percent)
+
+    def disable(self):
+        """Close driver interfaces and stop worker threads."""
+        self._queue_worker_stop.set()
+        self.driver.close()
+
+    def _get_key_box(self, index: int) -> tuple[int, int, int, int]:
+        """Return (x1, y1, x2, y2) bounding box for key index in 800x240 buffer."""
+        row = index // KEYS_PER_ROW
+        col = index % KEYS_PER_ROW
+        x1 = round(col * self.width / KEYS_PER_ROW)
+        x2 = round((col + 1) * self.width / KEYS_PER_ROW)
+        y1 = round(row * self.height / 2)
+        y2 = round((row + 1) * self.height / 2)
+        return (x1, y1, x2, y2)
+
+    def _get_key_coords(self, index: int) -> tuple[int, int]:
+        box = self._get_key_box(index)
+        return (box[0], box[1])
+
+    def clear(self):
+        """Clear the full image buffer to black and update all key tiles on device."""
+        self.image_buffer = Image.new("RGB", (self.width, self.height), (0, 0, 0))
+        current_page = self.page_manager.get_current_page()
+        for idx in range(NUM_KEYS):
+            current_page.keys[idx] = None
+        self.push_image()
+
+    def screenshot(self, filename: str):
+        """Save current buffer to a file for debugging."""
+        self.image_buffer.save(filename)
+
+    def update(self, timeout: int = 20):
+        """Poll driver for inputs, process key lifecycles, and update display.
+
+        Args:
+            timeout: Input polling timeout in milliseconds (default 20ms for high responsiveness).
+        """
+        now = time.time()
+
+        # 1. Check page auto-timeouts
+        timeout_target = self.page_manager.check_timeout()
+        if timeout_target:
+            self.switch_to_page(timeout_target)
+
+        # 2. Poll Driver for key events
+        input_state = self.driver.poll_key(timeout=timeout)
+
+        # 3. Handle key presses
+        if input_state['pressed']:
+            self.page_manager.note_activity()
+            for idx in input_state['pressed']:
+                if not self._key_down_state[idx]:
+                    self._key_down_state[idx] = True
+                    self._last_fire_time[idx] = now
+                    self._press_start_time[idx] = now
+
+                    key = self[idx]
+                    if key:
+                        key.on_press()
+
+                    # Double click check (additionally trigger on_double_press if within window)
+                    if idx in self._dc_timers and (now - self._dc_timers[idx] <= self.dc_window):
+                        del self._dc_timers[idx]
+                        self._dc_pending_single[idx] = False
+                        if key:
+                            key.on_double_press()
+                    else:
+                        self._dc_timers[idx] = now
+                        self._dc_pending_single[idx] = True
+
+        # 4. Handle key releases
+        if input_state['released']:
+            for idx in input_state['released']:
+                if self._key_down_state[idx]:
+                    self._key_down_state[idx] = False
+                    start_t = self._press_start_time.pop(idx, None)
+                    if start_t and (now - start_t >= 0.8):
+                        key = self[idx]
+                        if key:
+                            key.on_long_press()
+
+                    key = self[idx]
+                    if key:
+                        key.on_release()
+                else:
+                    # Released without recorded down event (missed down poll on super fast tap)
+                    self.page_manager.note_activity()
+                    self._last_fire_time[idx] = now
+                    key = self[idx]
+                    if key:
+                        key.on_press()
+                        key.on_release()
+
+        # 5. Handle pending single presses after double-click window elapses
+        for idx in list(self._dc_timers.keys()):
+            if now - self._dc_timers[idx] > self.dc_window:
+                del self._dc_timers[idx]
+                self._dc_pending_single.pop(idx, None)
+
+        # 6. Render pass for current page keys
+        current_page = self.page_manager.get_current_page()
+        dirty_indices = []
+
+        for idx in range(NUM_KEYS):
+            key = current_page.keys[idx]
+            if key is None:
+                if self._synced_keys[idx] is not None:
+                    # Clear this slot region to black on buffer
+                    self._render_blank_key_to_buffer(idx)
+                    dirty_indices.append(idx)
+                    self._synced_keys[idx] = None
+            else:
+                if self._synced_keys[idx] is not key:
+                    key._needs_redraw = True
+                    self._synced_keys[idx] = key
+
+                key.on_tick()
+                if key._needs_redraw:
+                    self._render_key_to_buffer(idx, key)
+                    key._needs_redraw = False
+                    dirty_indices.append(idx)
+
+        # 7. Upload pass: if 3 or more keys are dirty, batch update the whole panel!
+        if len(dirty_indices) >= 3:
+            self.push_image()
+        elif dirty_indices:
+            for idx in dirty_indices:
+                self._request_tile_upload(idx)
+
+    def _render_key_to_buffer(self, idx: int, key: Key):
+        """Render a single key into the global image buffer."""
+        box = self._get_key_box(idx)
+        w, h = box[2] - box[0], box[3] - box[1]
+        draw = ImageDraw.Draw(self.image_buffer)
+        ctx = KeyContext(draw, x_offset=box[0], y_offset=box[1], image=self.image_buffer)
+        ctx.width = w
+        ctx.height = h
+        key.render(ctx)
+
+    def _render_blank_key_to_buffer(self, idx: int):
+        """Render a solid black tile for an unassigned key slot into global image buffer."""
+        box = self._get_key_box(idx)
+        draw = ImageDraw.Draw(self.image_buffer)
+        draw.rectangle(box, fill=(0, 0, 0))
+
+    def _request_tile_upload(self, idx: int):
+        """Extract a key's 102x102 tile from image_buffer and queue for USB transmission."""
+        box = self._get_key_box(idx)
+        tile_crop = self.image_buffer.crop(box)
+        bgr_bytes = image_to_bgr102(tile_crop, rotation=self.rotation)
+        self._render_queue.put((idx, bgr_bytes))
+
+
+    def push_image(self, image_or_path: Optional[Union[str, Image.Image]] = None):
+        """Slice full image buffer (or given image/path) into 12 key tiles and push to device immediately."""
+        if image_or_path is not None:
+            if isinstance(image_or_path, str):
+                self.image_buffer = Image.open(image_or_path).convert("RGB")
+            else:
+                self.image_buffer = image_or_path.convert("RGB")
+            if self.image_buffer.size != (self.width, self.height):
+                self.image_buffer = self.image_buffer.resize((self.width, self.height), Image.LANCZOS)
+            for idx in range(NUM_KEYS):
+                self._synced_keys[idx] = "CUSTOM_IMAGE"
+
+        tiles_bgr = split_image_to_tiles(self.image_buffer, rotation=self.rotation)
+        try:
+            self.driver.upload_panel(tiles_bgr)
+            # Mark all slots as in sync
+            current_page = self.page_manager.get_current_page()
+            for idx in range(NUM_KEYS):
+                key = current_page.keys[idx]
+                if key:
+                    key._needs_redraw = False
+                    self._synced_keys[idx] = key
+                else:
+                    self._synced_keys[idx] = "CUSTOM_IMAGE"
+        except Exception as e:
+            log.error(f"Failed to push panel image to display: {e}")
+
+
+
+
+
+    def _async_render_loop(self):
+        """Background worker thread draining tile updates to keep key loops responsive."""
+        while not self._queue_worker_stop.is_set():
+            try:
+                latest: Dict[int, bytes] = {}
+                # Drain queue items and deduplicate per key index
+                while True:
+                    try:
+                        idx, bgr_bytes = self._render_queue.get(timeout=0.05)
+                        latest[idx] = bgr_bytes
+                    except queue.Empty:
+                        break
+
+                if latest and self.driver.connected:
+                    for idx, bgr_bytes in sorted(latest.items()):
+                        try:
+                            self.driver.upload_button(idx, bgr_bytes)
+                        except Exception as e:
+                            log.debug(f"Async upload failed for key {idx}: {e}")
+            except Exception as e:
+                log.debug(f"Error in async render loop: {e}")
+            time.sleep(0.01)

displaypad_lib-1.0.0/src/displaypad_lib/key.py

@@ -0,0 +1,195 @@
+"""Base Key class for DisplayPad keys, and specialized key implementations."""
+
+import time
+from abc import ABC, abstractmethod
+from typing import Optional, Union, List, Tuple
+from PIL import Image, ImageFont
+
+from .keycontext import KeyContext, get_default_font
+from logging import getLogger
+
+
+log = getLogger(__name__)
+
+
+class Key(ABC):
+    """Base abstract class for a DisplayPad key.
+
+    Subclass this and override `render(ctx)` and lifecycle hooks like `on_press()`.
+    """
+
+    def __init__(self):
+        self._needs_redraw = True
+        self.index: Optional[int] = None
+
+    def request_redraw(self):
+        """Call this when state changes to trigger a screen update."""
+        self._needs_redraw = True
+
+    # --- Lifecycle Hooks ---
+
+    def on_mount(self, index: int):
+        """Called when the key is assigned to a board slot (0..11)."""
+        self.index = index
+
+    def on_press(self):
+        """Called when the key is pressed down."""
+        pass
+
+    def on_release(self):
+        """Called when the key is released."""
+        pass
+
+    def on_double_press(self):
+        """Called when the key is double-tapped within the double-click window."""
+        pass
+
+    def on_long_press(self):
+        """Called when the key is held down longer than long-press duration."""
+        pass
+
+    def on_tick(self):
+        """Called every polling iteration. Useful for animations and timer checks."""
+        pass
+
+    @abstractmethod
+    def render(self, ctx: KeyContext):
+        """Render the key contents into the provided KeyContext."""
+        pass
+
+
+class FramerateLimitedKey(Key):
+    """A Key that limits redraw requests to a target frame rate (fps)."""
+
+    def __init__(self, fps: float = 10.0):
+        super().__init__()
+        self.fps = fps
+        self._last_render_time = 0.0
+
+    def on_tick(self):
+        current_time = time.time()
+        if current_time - self._last_render_time >= 1.0 / self.fps:
+            self.request_redraw()
+            self._last_render_time = current_time
+
+
+class LoggerKey(Key):
+    """A Key that logs presses and releases."""
+
+    def __init__(self, idx: int = 0):
+        super().__init__()
+        self.idx = idx
+
+    def on_press(self):
+        log.info(f"Key {self.idx} Pressed!")
+
+    def on_release(self):
+        log.info(f"Key {self.idx} Released!")
+
+    def render(self, ctx: KeyContext):
+        ctx.fill("blue")
+        ctx.center_text(f"LOG KEY {self.idx}", color="white")
+
+
+class IconKey(Key):
+    """A Key that displays a static icon image (PIL Image or file path)."""
+
+    def __init__(self, image_or_path: Union[str, Image.Image], margin: int = 10):
+        super().__init__()
+        if isinstance(image_or_path, str):
+            self.pil_image = Image.open(image_or_path).convert("RGBA")
+        else:
+            self.pil_image = image_or_path.convert("RGBA")
+        self.margin = margin
+
+    def render(self, ctx: KeyContext):
+        ctx.clear()
+        available_width = ctx.width - 2 * self.margin
+        available_height = ctx.height - 2 * self.margin
+
+        iw, ih = self.pil_image.size
+        aspect_ratio = iw / ih if ih > 0 else 1.0
+
+        if iw > available_width or ih > available_height:
+            if aspect_ratio > 1:
+                iw = available_width
+                ih = int(iw / aspect_ratio)
+            else:
+                ih = available_height
+                iw = int(ih * aspect_ratio)
+            resized = self.pil_image.resize((max(1, iw), max(1, ih)), Image.LANCZOS)
+        else:
+            resized = self.pil_image
+
+        x = self.margin + (available_width - iw) // 2
+        y = self.margin + (available_height - ih) // 2
+        ctx.paste_image(resized, x, y)
+
+
+class GifKey(Key):
+    """A Key that plays an animated GIF at its native frame rate."""
+
+    def __init__(self, gif_path_or_image: Union[str, Image.Image], rotation: int = 0):
+        super().__init__()
+        self.rotation = rotation
+        self.frames: List[Tuple[Image.Image, float]] = []  # (frame_image, duration_seconds)
+        self.current_frame_idx = 0
+        self.last_frame_time = time.time()
+        self.is_playing = True
+
+        self._load_gif(gif_path_or_image)
+
+    def _load_gif(self, src: Union[str, Image.Image]):
+        img = Image.open(src) if isinstance(src, str) else src.copy()
+        if not getattr(img, 'is_animated', False) and getattr(img, 'n_frames', 1) <= 1:
+            frame = img.convert("RGBA").resize((133, 120), Image.LANCZOS)
+            if self.rotation:
+                frame = frame.rotate(-self.rotation, expand=False)
+            self.frames = [(frame, 1.0)]
+            return
+
+        try:
+            for i in range(img.n_frames):
+                img.seek(i)
+                duration = max(img.info.get('duration', 100), 20) / 1000.0
+                frame = img.convert("RGBA").resize((133, 120), Image.LANCZOS)
+                if self.rotation:
+                    frame = frame.rotate(-self.rotation, expand=False)
+                self.frames.append((frame, duration))
+        except EOFError:
+            pass
+
+    def on_tick(self):
+        if not self.is_playing or not self.frames:
+            return
+
+        now = time.time()
+        _frame_img, duration = self.frames[self.current_frame_idx]
+        if now - self.last_frame_time >= duration:
+            self.current_frame_idx = (self.current_frame_idx + 1) % len(self.frames)
+            self.last_frame_time = now
+            self.request_redraw()
+
+    def render(self, ctx: KeyContext):
+        ctx.clear()
+        if not self.frames:
+            return
+        frame_img, _ = self.frames[self.current_frame_idx]
+        ctx.paste_image(frame_img, 0, 0)
+
+
+class LabelKey(Key):
+    """A Key that displays a simple text label with background color."""
+
+    def __init__(self, label: str, bg_color: str = "navy", text_color: str = "white", font_size: int = 18):
+        super().__init__()
+        self.label = label
+        self.bg_color = bg_color
+        self.text_color = text_color
+        self.font_size = font_size
+        self._custom_font = None
+
+    def render(self, ctx: KeyContext):
+        ctx.fill(self.bg_color)
+        font = self._custom_font or get_default_font(self.font_size)
+        ctx.center_text(self.label, color=self.text_color, font=font)

displaypad_lib-1.0.0/src/displaypad_lib/keycontext.py

@@ -0,0 +1,175 @@
+import PIL.ImageDraw as ImageDraw
+from PIL import Image, ImageFont
+
+
+def get_default_font(size: int = 18) -> ImageFont.ImageFont:
+    """Load a crisp, bold system font (size 18pt by default) for high-density key displays."""
+    font_paths = (
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+        "/usr/share/fonts/dejavu-sans-fonts/DejaVuSans-Bold.ttf",
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+        "/usr/share/fonts/truetype/freefont/FreeSansBold.ttf",
+        "/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf",
+        "/usr/share/fonts/TTF/DejaVuSans-Bold.ttf",
+    )
+    for p in font_paths:
+        try:
+            return ImageFont.truetype(p, size)
+        except Exception:
+            pass
+    try:
+        return ImageFont.load_default(size=size)
+    except Exception:
+        return ImageFont.load_default()
+
+
+class KeyContext:
+    """A drawing context for a single key on the DisplayPad.
+    Automatically offsets drawing commands to the key's position.
+    Provides helper methods for common drawing tasks."""
+    width = 800 // 6
+    height = 240 // 2
+
+    def __init__(self, pil_draw: ImageDraw.ImageDraw, x_offset, y_offset, font=None, image: Image.Image | None = None):
+        self.draw = pil_draw
+        self.ox = x_offset
+        self.oy = y_offset
+        self.font = font or get_default_font(18)
+        self.image = image
+
+    def set_font(self, font):
+        self.font = font
+
+
+    def text(self, x, y, text, fill="white", font=None, **kwargs):
+        fill = kwargs.pop('color', fill)
+        font = font or self.font
+        self.draw.text((self.ox + x, self.oy + y), text,
+                       fill=fill, font=font, **kwargs)
+
+    def rectangle(self, x, y, w, h, fill="red", **kwargs):
+        fill = kwargs.pop('color', fill)
+        self.draw.rectangle(
+            [self.ox + x, self.oy + y, self.ox + x + w, self.oy + y + h],
+            fill=fill,
+            **kwargs
+        )
+
+    def ellipse(self, x, y, w, h, fill="red", **kwargs):
+        fill = kwargs.pop('color', fill)
+        self.draw.ellipse(
+            [self.ox + x, self.oy + y, self.ox + x + w, self.oy + y + h],
+            fill=fill,
+            **kwargs
+        )
+
+    def line(self, x1, y1, x2, y2, fill="red", width=1, **kwargs):
+        fill = kwargs.pop('color', fill)
+        self.draw.line(
+            [self.ox + x1, self.oy + y1, self.ox + x2, self.oy + y2],
+            fill=fill,
+            width=width,
+            **kwargs
+        )
+
+    def polygon(self, points, fill="red", **kwargs):
+        fill = kwargs.pop('color', fill)
+        offset_points = [(self.ox + x, self.oy + y) for (x, y) in points]
+        self.draw.polygon(offset_points, fill=fill, **kwargs)
+
+    def pixel(self, x, y, fill="red", **kwargs):
+        fill = kwargs.pop('color', fill)
+        self.draw.point((self.ox + x, self.oy + y), fill=fill, **kwargs)
+        
+    def point(self, x, y, fill="red", **kwargs):
+        fill = kwargs.pop('color', fill)
+        self.draw.point((self.ox + x, self.oy + y), fill=fill, **kwargs)
+
+    def paste_image(self, pil_image: Image.Image, x=0, y=0):
+        """Paste an image into the key bounds, clipping to this key's area."""
+        if self.image is None:
+            raise ValueError("KeyContext needs a base image to paste onto")
+
+        src = pil_image.convert("RGBA")
+
+        dest_left = self.ox + x
+        dest_top = self.oy + y
+        dest_right = dest_left + src.width
+        dest_bottom = dest_top + src.height
+
+        key_left, key_top = self.ox, self.oy
+        key_right, key_bottom = self.ox + self.width, self.oy + self.height
+
+        clip_left = max(dest_left, key_left)
+        clip_top = max(dest_top, key_top)
+        clip_right = min(dest_right, key_right)
+        clip_bottom = min(dest_bottom, key_bottom)
+
+        if clip_left >= clip_right or clip_top >= clip_bottom:
+            return
+
+        crop_left = clip_left - dest_left
+        crop_top = clip_top - dest_top
+        cropped = src.crop((crop_left, crop_top, crop_left +
+                           (clip_right - clip_left), crop_top + (clip_bottom - clip_top)))
+
+        alpha = cropped.getchannel("A") if "A" in cropped.getbands() else None
+        rgb = cropped.convert("RGB")
+        self.image.paste(rgb, (clip_left, clip_top), mask=alpha)
+
+    def arc(self, x1, y1, x2, y2, start, end, fill="red", width=1, **kwargs):
+        fill = kwargs.pop('color', fill)
+        self.draw.arc(
+            [self.ox + x1, self.oy + y1, self.ox + x2, self.oy + y2],
+            start,
+            end,
+            fill=fill,
+            width=width, **kwargs
+        )
+
+    # Layout helpers
+    def center_text(self, text, y=None, fill="white", font=None, **kwargs):
+        fill = kwargs.pop('color', fill)
+        font = font or self.font
+        bbox = self.draw.textbbox((0, 0), text, font=font)
+        w = bbox[2] - bbox[0]
+        h = bbox[3] - bbox[1]
+        x = (self.width - w) // 2 - bbox[0]
+        calc_y = ((self.height - h) // 2 - bbox[1]) if y is None else (y - bbox[1])
+        self.text(x, calc_y, text, fill=fill, font=font, **kwargs)
+
+
+    def fill(self, fill="black", **kwargs):
+        fill = kwargs.pop('color', fill)
+        self.rectangle(0, 0, self.width, self.height, fill=fill, **kwargs)
+
+        
+    
+
+    def clear(self):
+        self.fill("black")
+
+    def apply_alpha_mask(self, alpha_mask: Image.Image):
+        """Apply an alpha mask to the key's image area."""
+        if self.image is None:
+            raise ValueError(
+                "KeyContext needs a base image to apply alpha mask onto")
+
+        # Support both key-sized masks and full-panel masks.
+        if alpha_mask.size == (self.width, self.height):
+            mask_cropped = alpha_mask
+        elif alpha_mask.size == self.image.size:
+            mask_cropped = alpha_mask.crop(
+                (self.ox, self.oy, self.ox + self.width, self.oy + self.height))
+        else:
+            # Fallback: resize to key area
+            mask_cropped = alpha_mask.resize((self.width, self.height))
+
+        key_area = self.image.crop(
+            (self.ox, self.oy, self.ox + self.width, self.oy + self.height)).convert("RGBA")
+        key_area.putalpha(mask_cropped)
+        self.image.paste(key_area, (self.ox, self.oy))
+
+    def textbbox(self, text, font=None, **kwargs):
+        font = font or self.font
+        return self.draw.textbbox((0, 0), text, font=font, **kwargs)

displaypad_lib-1.0.0/src/displaypad_lib/page.py

@@ -0,0 +1,111 @@
+"""Multi-page layout management and page auto-timeout engine for DisplayPad."""
+
+import time
+from typing import Dict, List, Optional, Union
+from .key import Key
+
+
+class Page:
+    """Represents a single 12-key page layout with optional auto-timeout behavior."""
+
+    def __init__(self, name: str = "Main",
+                 timeout_mode: str = "off",
+                 timeout_seconds: int = 10,
+                 timeout_target: Union[str, int] = "prev"):
+        self.name = name
+        self.keys: List[Optional[Key]] = [None] * 12
+        self.timeout_mode = timeout_mode  # "off", "after", "idle"
+        self.timeout_seconds = timeout_seconds
+        self.timeout_target = timeout_target
+
+    def __getitem__(self, index: int) -> Optional[Key]:
+        if 0 <= index < 12:
+            return self.keys[index]
+        raise IndexError(f"Key index {index} out of range (0..11)")
+
+    def __setitem__(self, index: int, key_instance: Optional[Key]):
+        if 0 <= index < 12:
+            self.keys[index] = key_instance
+            if key_instance is not None:
+                key_instance.on_mount(index)
+                key_instance.request_redraw()
+        else:
+            raise IndexError(f"Key index {index} out of range (0..11)")
+
+
+class PageManager:
+    """Manages page registration, active page switching, and auto-timeout transitions."""
+
+    def __init__(self, main_page: Optional[Page] = None):
+        self.pages: Dict[Union[str, int], Page] = {}
+        self.current_page_id: Union[str, int] = "Main"
+        self.previous_page_id: Union[str, int] = "Main"
+
+        self.last_switch_time: float = time.time()
+        self.last_activity_time: float = time.time()
+
+        default_main = main_page or Page(name="Main")
+        self.add_page("Main", default_main)
+
+    def add_page(self, page_id: Union[str, int], page: Page):
+        self.pages[page_id] = page
+        if page.name and page.name not in self.pages:
+            self.pages[page.name] = page
+
+    def get_current_page(self) -> Page:
+        return self.pages.get(self.current_page_id) or self.pages.get("Main") or list(self.pages.values())[0]
+
+    def switch_to(self, page_id: Union[str, int]) -> bool:
+        if page_id not in self.pages:
+            return False
+
+        if page_id == self.current_page_id:
+            return True
+
+        self.previous_page_id = self.current_page_id
+        self.current_page_id = page_id
+        now = time.time()
+        self.last_switch_time = now
+        self.last_activity_time = now
+
+        current_page = self.get_current_page()
+        for idx, key in enumerate(current_page.keys):
+            if key:
+                key.request_redraw()
+
+        return True
+
+    def back(self) -> bool:
+        return self.switch_to(self.previous_page_id)
+
+    def note_activity(self):
+        """Reset the inactivity timer for 'idle' mode timeouts."""
+        self.last_activity_time = time.time()
+
+    def check_timeout(self) -> Optional[Union[str, int]]:
+        """Check if current page timeout condition has expired.
+
+        Returns target page_id to switch to, or None.
+        """
+        page = self.get_current_page()
+        if not page or page.timeout_mode == "off" or page.timeout_seconds <= 0:
+            return None
+
+        now = time.time()
+        target = page.timeout_target
+        if target == "prev":
+            resolved_target = self.previous_page_id
+        else:
+            resolved_target = target
+
+        if resolved_target == self.current_page_id:
+            return None
+
+        if page.timeout_mode == "after":
+            if now - self.last_switch_time >= page.timeout_seconds:
+                return resolved_target
+        elif page.timeout_mode == "idle":
+            if now - self.last_activity_time >= page.timeout_seconds:
+                return resolved_target
+
+        return None