Skip to content

desktops

This directory contains a Talon plugin that provides cross-platform voice commands for managing virtual desktops (or workspaces) and moving windows between them.

The plugin is structured using a standard Talon design pattern: a central module defines the abstract action interface and default fallback notifications, a Talon file maps voice syntax to those actions, and platform-specific context files implement the actions utilizing native operating system features, keyboard shortcuts, or accessibility APIs.

Core Architecture

The desktop management functionality is split into an interface and concrete platform implementations:

  • desktops.py: Establishes the user action namespace for desktop operations. By default, all actions defined here notify the user that the operation is "Not supported on this operating system". This provides a fallback interface and documents the expected actions.
  • desktops.talon: Maps natural language voice commands to the abstract actions defined in the module. For example, saying "desk show" triggers user.desktop_show(), and "window move desk left" triggers user.window_move_desktop_left().

Platform-Specific Implementations

Depending on the active operating system, Talon overrides the default actions with concrete implementations:

Linux

The desktops_linux.py file implements desktop switching and window relocation using Talon's native ui API.

  • It switches workspaces using ui.switch_workspace(number).
  • It moves active windows to specific workspaces by updating the workspace property on the active window object (ui.active_window().workspace = desktop_number).

Windows

The desktops_win.py file implements basic desktop navigation by sending standard Windows keyboard shortcuts:

  • desktop_next: Sends <kbd>Win</kbd> + <kbd>Ctrl</kbd> + <kbd>Right</kbd>
  • desktop_last: Sends <kbd>Win</kbd> + <kbd>Ctrl</kbd> + <kbd>Left</kbd>
  • desktop_show: Sends <kbd>Win</kbd> + <kbd>Tab</kbd> (Task View)

Note: Window movement across desktops is not natively supported out-of-the-box via simple key combinations on Windows, so those actions remain unimplemented here.

macOS

The desktops_mac.py file handles macOS spaces. Because macOS does not natively support moving windows to arbitrary spaces via standard keyboard shortcuts, this implementation features a few advanced strategies:

  • Keyboard Shortcuts: Uses OS-level shortcuts like <kbd>Ctrl</kbd> + <kbd>Right/Left</kbd> for next/last desktop, and <kbd>Ctrl</kbd> + <kbd>Up</kbd> for Mission Control (desktop_show).
  • Window Dragging Context Manager (_drag_window_mac): To move a window to another desktop, it targets the green full-screen button of the active window using macOS accessibility APIs (AXSubrole="AXFullScreenButton"), offsets the coordinates to hover over the window's title bar, initiates a mouse drag (down=True), triggers the desktop-switch keyboard shortcut inside a Python context manager, and then releases the mouse click (up=True) once the transition is complete.
  • Amethyst Support: If the Amethyst tiling window manager is detected running (com.amethyst.Amethyst), it bypasses the mouse drag simulation and instead triggers Amethyst's native shortcuts (e.g., <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>Desktop Number</kbd>) to relocate the window.