Skip to content

talon_draft_window

The Talon Draft Window plugin provides a task-specific user interface (UI) to edit prose-style text more efficiently using voice commands.

Rather than relying on tedious cursor movement commands in standard application textareas, this plugin spawns an overlay window where every word is assigned a dynamic single-character letter "anchor" (e.g., 'a', 'b', 'c'). Users can manipulate words directly by referencing their anchors (e.g., "replace charlie with error", "clear air through bat").

Core Architecture and UI Rendering

The logical engine behind the draft window handles window rendering, style customization, and the complex calculation of word-level anchors.

  • draft_ui.py: This module contains the main DraftManager class, which interacts with Talon’s experimental TextArea UI. It manages window actions (showing, hiding, resizing, positioning) and styling (colors, sizes, and dark/light themes). Crucially, it implements calculate_text_anchors(), an algorithm that parses the visible text into word spans and assigns letter anchors to them. To ensure the most relevant words are always targetable, the algorithm centers the limited pool of 26 letter anchors around the active cursor position.
  • test_draft_ui.py: A test suite that verifies the behavior of calculate_text_anchors(). It ensures that anchors are generated correctly for various word splits (spaces, line breaks) and that they dynamically adjust to cluster around the cursor position.
  • init.py: A standard initialization file used to enable Python testing (via tools like pytest) from the parent directory.

Integration and Helper Logic

To make the draft window responsive to Talon’s voice engine, Python-level actions, settings, and custom behaviors are registered to bridge the UI with Talon.

  • draft_talon_helpers.py: This file declares the settings, tags, and actions associated with the draft window.
    • Context Triggers: It sets up ctx to manage the user.draft_window_showing tag, and ctx_focused to trigger specifically when the draft window itself is focused.
    • Undo Workaround: Because Talon's experimental TextArea has a known limitation where undo steps operate character-by-character, this file implements a debounced UndoWorkaround class. It runs a background timer to snapshot text states every second, bundling them into distinct history milestones for efficient undo/redo actions.
    • Action Class implementations: Overrides default dictation behaviors to enable "Smart dictation mode" (via dictation_peek) and registers custom window placement options (e.g., moving the window to "top", "bottom", "left", etc.).

Voice Command Interfaces

The interaction model is split across three .talon files, each defining voice commands that are active during specific application states.

  • draft_global.talon: These commands are globally active in Command Mode. They allow the user to open the draft window (draft show), size it (draft show small, draft show large), or grab text directly from their current active editor (draft edit to grab selection, draft edit all to grab everything).
  • draft_window_open.talon: Active anytime the draft window is visible (even if it isn't the focused window). It provides the vital draft submit command, which copies the text currently inside the draft UI, hides the draft window, and types/pastes the finalized text back into the user's primary application.
  • draft_window.talon: Active only when the draft window is focused. This contains the primary editing interface, enabling anchor-based commands such as:
    • Selection: take <anchor> or take <anchor> through <anchor>
    • Modification: replace <anchor> with <text>
    • Deletion: clear <anchor>
    • Navigation: cursor before <anchor> / cursor after <anchor>
    • Formatting: <formatter> word <anchor> or <formatter> <anchor> through <anchor>

Support Files

  • settings.talon.example: Provides template settings for customizing the visual appearance of the draft window, including font size, label size, and colors.
  • README.md: Contains user-facing instructions, a step-by-step example workflow, instructions for running the unit tests, and a demonstration GIF.
  • LICENSE: The MIT License covering the usage and distribution of this plugin.