Skip to content

windows_and_tabs

This directory manages operating-system-level windows and application tabs. It abstracts typical keyboard shortcuts (e.g., closing a tab or window) into cross-platform Talon actions, exposes intuitive voice commands for resizing and positioning windows, handles multi-monitor environments, and implements an advanced window arrangement engine.

Cross-Platform Shortcuts & Window Validation

To ensure voice commands work consistently across different operating systems, actions are separated into standard interfaces and platform-specific implementations:

  • Linux: windows_and_tabs_linux.py binds standard tasks (such as opening/closing tabs and hiding windows) to standard Linux/X11 shortcuts like ctrl-t and alt-f4.
  • Windows: windows_and_tabs_win.py binds actions to standard Windows OS key combinations.
  • macOS: windows_and_tabs_mac.py handles macOS keyboard mappings, incorporating standard conventions like cmd-w, cmd-m, and cmd-backtick (cmd- ) to cycle through an application's windows.
  • Universal Window Handling: For operating systems where application window cycling isn't built-in or needs custom logic, windows_and_tabs.py provides fallback behavior. It tracks active application windows and cycles through them programmatically. It includes is_window_valid(), which filters out invisible helper windows (common on Windows OS) and minuscule pop-ups using a size heuristic relative to the screen's DPI.

Tab Navigation

Tabbed interfaces are controlled through two primary files:

  • tabs.py registers standard tab action definitions (e.g., jumping to specific tab indexes, duplicating, or closing). It includes tab_close_wrapper(), which lets specific applications implement standard close delays to handle fast repetitions gracefully.
  • tabs.talon activates these definitions with natural voice commands like "tab open", "go tab <number>", and "tab duplicate".

Window Snapping and Monitor Management

One of the core features of this package is the ability to "snap" windows to specific fractions of the screen or push them to other physical monitors:

  • Grid Positions: window_snap_positions.talon-list defines spoken forms for standard screen regions (e.g., "left third", "top right", "center small", "fullscreen").
  • Coordinate Calculation & Snapping Logic: window_snap.py translates the spoken layout forms into RelativeScreenPos objects representing bounding boxes normalized from 0 to 1.
  • Multi-Monitor Support: When moving windows to other monitors, window_snap.py uses screen dimensions to resize windows appropriately. It provides a "proportional" scaling mode (scaling the window bounding box to match the destination screen ratio) and a "size aware" scaling mode. The size-aware mode preserves absolute dimensions where possible, unless the window is already maximized or docked flush against screen borders.
  • Voice Control: window_management.talon maps user speech directly to these actions, allowing phrases like "snap right", "snap screen 2", or "snap chrome left" to instantly manipulate active or background windows.

Advanced Experimental Window Layouts

For complex tasks requiring multiple side-by-side applications, the codebase provides an advanced window-arranging feature described in the README.md.

  • Configuring Splits: window_split_positions.talon-list stores predefined splits, including splitting the screen into halves ("half"), thirds ("thirds"), quadrants ("grid"), or asymmetric groups ("clock" or "counterclock").
  • Activation: Users must first enable the experimental layout tag to use these commands, as mapped in window_layout.talon: talon tag(): user.experimental_window_layout
  • Arrangement Logic: Controlled by window_layout.py, this engine selects candidate windows and places them into the chosen layout. It supports advanced layout parameters:
    • Placeholders/Gaps: Saying "gap" inside a layout sequence lets you skip a coordinate slot in the grid arrangement.
    • Specific App Focus: You can target specific apps (e.g., "layout halves chrome slack") or choose relative history indices (e.g., "second").
    • Rotations: Repeating a layout command consecutively without manually interacting with the mouse will cycle/rotate the assigned windows through the layout's slots.
    • Manual Override Detection: A background focus listener registers global application activation. If more than 1 second passes or if you manually click/focus a window, the rotation history is cleared to prevent accidental shifts.