Skip to content

screens

This directory contains the core functionality for managing and identifying multiple monitors (screens) within the Talon voice control environment. It provides a simple voice command to overlay large, temporary numbers on each connected screen, making it easy to determine which screen is which when using multi-monitor setups.

How It Works

The functionality is split between a Talon command file that defines the voice trigger and a Python module that interacts with Talon's window management APIs (ui) and graphics canvas (Canvas).

Voice Trigger

The screens.talon file defines a single voice command:

  • "screen numbers": Calls the action user.screens_show_numbering() to visually identify all connected monitors.

Screen Management and Overlay Logic

The screens.py file implements the action logic and provides helpers for navigating screens:

  • Visual Overlay (screens_show_numbering): This action retrieves the list of active monitors using ui.screens() and displays a 1-based index on each monitor. It instantiates a Talon Canvas spanning the entire bounding rectangle of each screen.

    The overlay rendering (show_screen_number) performs the following steps: * Dynamic Scaling: To prevent oversized text on portrait displays, the text size is computed using the minimum of the screen's width and height (min(width, height) / 2). * Centering: Standard typographic bounding box math is used to precisely center the number on each monitor. * High Contrast Rendering: The number is drawn twice—once with a light gray fill and once with a black outline (stroke). This dual-color layout ensures the number is legible against any background (e.g., light-mode documents or dark-mode IDEs). * Auto-dismissal: The canvas is frozen for performance, and a cron.after callback is scheduled to automatically close the overlay after 3 seconds.

  • Screen Navigation Helpers: In addition to numbering screens, screens.py provides internal APIs for other Talon modules to query and cycle through monitors:

    • screens_get_by_number(screen_number): Retrieves a specific screen by its visual index, with safety checks to ensure the requested number is within bounds.
    • screens_get_next(screen) / screens_get_previous(screen): Enables seamless, wrapping navigation between screens (using modulo arithmetic to cycle back to the first screen when moving past the last, and vice-versa).