Skip to content

mouse_grid

The mouse grid directory implements a powerful, voice-controlled recursive 3x3 grid positioning system. Instead of moving the mouse cursor manually, users can segment their screen (or active window) into nine numbered regions, choosing smaller and smaller sub-regions to home in on a precise target.

How It Works

This feature relies on a Python backend defining the layout geometry, canvas rendering, and state management, integrated with Talon files that bind voice commands to specific grid operations.

Python Implementation

mouse_grid.py implements the main logic through the MouseSnapNine class. When activated, the grid draws overlay lines and numbers onto a custom Talon canvas layout representing a 3x3 grid.

  • Narrowing and Navigation: Selecting a number shrinks the boundaries of the grid to that sub-region. Users can narrow multiple times to target individual pixels. It also keeps track of selection history, allowing users to go back if they miscalculate.
  • Talon Tracking Integration: To prevent conflict with other eye-tracking or head-tracking tools, the grid temporarily deactivates Talon's control mouse, zoom mouse, and control1 mouse functions when it opens, and restores their previous states on close.
  • Magnification & Screenshots: For high-precision clicks when the grid becomes too small to view comfortably, the class captures a screenshot of the grid boundary and presents a zoomed-in overlay at the center of the screen once a narrowing threshold is reached (controlled by grid_show_zoomed).
  • Settings:
    • user.grid_narrow_expansion: Dynamically inflates the size of narrowed regions by a defined pixel count to prevent targets from being awkwardly cut off on edges.
    • user.grids_put_one_bottom_left: Determines if the grid behaves like a telephone layout (1 at top-left) or a standard computer numpad (1 at bottom-left).
    • user.grid_show_zoomed: Toggles the magnified visualization once the grid gets sufficiently small.

Voice Commands

The system splits its vocabulary into global commands and context-specific commands:

  • mouse_grid_always.talon provides commands to launch the grid anytime:

    • "mouse grid": Places the grid on the primary monitor.
    • "grid win": Centers the grid specifically over the currently active window.
    • "grid screen <number>": Directs the grid to target a specific physical monitor.
    • "grid <user.number_key>+": Allows chaining a sequence of zones in a single breath (for example, saying "grid five nine two" directly targets region 5, then region 9 within 5, then region 2 within 9).

  • mouse_grid_open.talon is active only when the grid is visible on screen (tag: user.mouse_grid_showing). It provides short-form navigation instructions:

    • Simply calling out a number narrows the focus down further.
    • "grid back": Reverts the last narrowing action.
    • "grid reset": Redraws the grid to its maximum size on the designated screen.
    • "grid close" / "grid off": Shuts the grid down and restores active eye trackers.