Skip to content

help

This directory contains the implementation of the interactive, voice-controlled help system. It provides on-screen graphical overlays (using Talon’s imgui module) to display list definitions, active contexts, active commands, available formatting styles, programming operators, and current Talon scope properties.

Overview

The help system functions as a dynamic reference manual. When a help screen is open, the system injects context-specific voice commands—such as pagination ("help next") or closure ("help close")—that are only active while the overlay is visible. This allows users to browse system documentation, search for specific verbal commands, and inspect their current Talon configuration state without using a mouse or keyboard.

Key Components

The help system is split into Python backend logic (managing data models, search matching, and UI rendering) and Talon files (defining the spoken triggers).

Backend & UI Logic

  • help.py: The primary coordinator of the help system. It processes context mappings, maintains pagination state, handles text wrapping, and indexes active rules for real-time word searching. It renders several imgui displays:

    • Context Help: Displays active or all command contexts, grouped by specificity (Application-specific, Context-dependent, or Global).
    • List Help: Dynamically extracts items and descriptions from internal registries (e.g., symbols, websites, search engines) and displays them.
    • Operators & Formatters: Displays language-specific coding operators and formatting patterns (e.g., camelCase, snake_case) on demand.

  • help_scope.py: A developer-focused utility that renders the current Talon Scope overlay. It lists currently active modes, active tags, and miscellaneous key-value pairs (like screen names or current application details). This is crucial for debugging why certain commands might or might not be firing in a given context.

Spoken Trigger Definitions

  • help.talon: The main list of commands used to launch various help menus. Example triggers include:

    • help alphabet or help symbols to look up spoken phonetic forms.
    • help context or help active to inspect current rules.
    • help search <text> to filter available rules by word.
    • help scope to toggle the scope inspection panel.

  • help_open.talon: Activates the tag user.help_open when any primary help GUI is displayed. This dynamically enables navigation controls like help next, help previous, and help close. By restricting these commands to this specific tag, they do not clutter the global command space during regular dictation.

  • help_scope_open.talon: Similar to help_open.talon, this activates when the scope inspector is displayed (using tag user.help_scope_open), enabling voice commands to hide/close the scope.

  • help_dictation.talon: Ensures basic help triggers (like help active or help context) are accessible even while in dictation mode by locking them to start-of-utterance anchors (^).

How They Work Together

  1. Requesting Help: A user says a command like "help search select".
  2. Activating UI: Talon matches the command in help.talon, calling actions.user.help_search("select") defined in help.py.
  3. Rendering: help.py filters the cached command-to-rule index for the word "select", formats pages, sets the state tag user.help_open, and opens gui_context_help.
  4. Navigation: The presence of user.help_open activates help_open.talon, allowing the user to say "help next" to turn the page.
  5. Teardown: Saying "help close" invokes help_hide(), which hides the active IMGUI, unregisters active update listeners, and clears the navigation tags to return Talon to its standard state.