Skip to content

screenshot

The community/plugin/screenshot directory contains the code for a screenshot utility in Talon. It allows users to take screenshots of their entire screen, specific windows, or selected areas, and save them to a file or the clipboard.

The core logic is in screenshot.py, which defines the following actions:

  • screenshot(screen_number: Optional[int] = None): Takes a screenshot of the entire screen. It accepts an optional screen number to capture a specific screen in a multi-monitor setup. If no screen number is provided, the main screen is used.
  • screenshot_window(): Takes a screenshot of the active window.
  • screenshot_selection(): Triggers the system's built-in screenshot selection tool.
  • screenshot_selection_clip(): Triggers the system's built-in screenshot selection tool and copies the result to the clipboard.
  • screenshot_settings(): Opens the system screenshot settings UI (currently only implemented for macOS).
  • screenshot_clipboard(screen_number: Optional[int] = None): Takes a screenshot of the entire screen and copies it to the clipboard. It also accepts an optional screen number.
  • screenshot_window_clipboard(): Takes a screenshot of the active window and copies it to the clipboard.
  • screenshot_rect(rect: ui.Rect, title: str = "", screen_num: Optional[int] = None): Takes a screenshot of a given rectangle on the screen. This is a lower-level function intended for use by other parts of Talon.

The screenshot.py file also includes helper functions like clipboard_rect, get_screenshot_path, flash_rect, and get_screen. Notably, the get_screenshot_path function determines where to save the screenshot based on a user setting and includes a timestamp in the filename. The flash_rect function briefly flashes a white rectangle on the screen before taking a screenshot to provide visual feedback to the user.

Context-specific actions for triggering selection screenshots are defined for Mac, Windows, and Linux in the screenshot.py file, using separate Context objects: ctx_mac, ctx_win, and ctx_linux. They trigger OS-specific commands using actions.key().

The file screenshot.talon defines the voice commands that invoke the actions defined in screenshot.py. It provides a straightforward way to trigger the screenshot actions through voice commands. For example, saying "grab screen" will trigger user.screenshot(), and "grab window clip" will trigger user.screenshot_window_clipboard(). The grammar includes an optional screen number to choose a particular screen to screenshot.