Skip to content

screenshot

This directory provides a hands-free, cross-platform screenshot utility for Talon. It allows users to capture the entire screen, specific monitors, individual active windows, or custom selections, saving the output either directly to a file or copy-pasting it into the system clipboard.

The functionality is split across two main files:

  • screenshot.talon - Defines the voice commands.
  • screenshot.py - Implements the screenshot capture logic, OS-specific adaptations, and configuration settings.

How It Works

The screenshot plugin integrates Talon's UI, Screen, Canvas, and Clipboard APIs to handle image capture, file storage, and OS-native command mapping.

1. Voice Commands

The screenshot.talon file exposes voice triggers using the prefix "grab". These commands map directly to python actions defined in the backend implementation.

Key commands include: * "grab screen [number]": Captures the main monitor or a specific monitor identified by its number. * "grab window": Captures the boundaries of the currently active window. * "grab selection": Triggers the operating system's native area selection tool. * "... clip" suffix: Variations of the commands above (e.g., "grab screen clip", "grab window clip") write the resulting image to the clipboard instead of saving a file.

The entire set of commands can be deactivated programmatically by enabling the user.screenshot_disabled tag.

2. Core Logic

The Python implementation in screenshot.py orchestrates the capture workflow:

  • File Storage and Configuration: It registers a setting called user.screenshot_folder to define where screenshots are saved. By default, it detects the operating system to choose an appropriate fallback folder, such as OneDrive/Pictures or Pictures.
  • Image Capture: When saving to a file, Talon's screen.capture_rect captures the requested area, and the write_file method writes the raw image as a PNG.
  • Dynamic Naming: Filenames are automatically generated with an ISO-like timestamp and, if capturing a specific window, the application's name (e.g., Screenshot 2023-10-27T14-30-00 - Firefox.png).
  • Visual Feedback: The helper function flash_rect uses a temporary Talon Canvas to draw a solid white overlay over the captured region. This canvas is destroyed after 150ms using cron.after, providing a brief camera-flash effect.

3. Cross-Platform Adaptations

While full-screen and active-window captures are handled directly through Talon's native API, region selection relies on native OS tools. screenshot.py resolves this by using context-specific overrides for different operating systems:

  • macOS: Triggers the system screenshot utility via cmd-shift-4 (for selection) and cmd-ctrl-shift-4 (for selection to clipboard). It also maps cmd-shift-5 to open the screenshot settings pane.
  • Windows: Simulates the Snipping Tool / Snip & Sketch shortcut via super-shift-s.
  • Linux: Triggers region selection via shift-printscr.