Zonogy

CmdTab

CmdTab provides a window switcher overlay for Zonogy, allowing quick navigation between recently used managed windows using a Cmd-Tab-style keyboard chord. It is analogous to the Launcher feature but optimized for quickly switching between windows.

Overview

CmdTab shows a single list of all managed windows (both minimized and unminimized) ordered by last used (most recent first), allowing the user to quickly switch between windows using a familiar Cmd-Tab interaction pattern.

CmdTab MUST override the system app switcher for its configured shortcut. This requires macOS Input Monitoring permission and uses a keyboard CGEventTap to swallow the matching key events so the system app switcher does not appear.

Activation

• Default shortcut: Cmd-Tab (configurable in Zonogy Preferences)
• App-specific shortcut: Cmd-` (configurable in Zonogy Preferences) — shows only windows from the currently active application
• Optional focused-window retargeting: The CmdTab targets zone with focused window Targeting preference chooses which shortcuts first retarget to the zone containing the currently active managed window: Off (neither; the default), Current app only (just the app-specific Cmd- shortcut), or *All windows too* (both Cmd-Tab and Cmd-). Retargeting is always skipped while the Launcher is visible.
• CmdTab appears in the same location as the Launcher would appear when invoked
• The configured shortcut may include multiple modifiers (e.g. Control-Command-Tab)
• Targeting invariant: While CmdTab is visible, any target change re-centers CmdTab onto the new target — whether it is a floating zone, an empty tiling zone, or an occupied tiling zone. Unlike the Launcher, CmdTab does not dismiss when retargeting to an occupied tiling zone.

UI / Presentation

• No search field — unlike the Launcher, CmdTab is purely navigational
• Single flat list of all managed windows across all applications, ordered by last used (most recently used at the top)
• Window entries: Each entry displays:
  • Application icon (same style as Launcher)
  • Window title (same truncation rules as Launcher)
• Visual styling should match the Launcher (vibrancy/blur, rounded corners, selection highlight)

Navigation

• Cycling: While holding the configured modifier(s), pressing the shortcut key repeatedly (default: Tab) moves selection to the next window in the list
• Direction: Each press moves selection down the list (toward less recently used windows). Holding Shift cycles backward.
• Wrap behavior: In app-specific mode (Cmd-`), selection wraps around at list boundaries. In all-windows mode (Cmd-Tab), selection stops at the first/last item. (Wrapping works well with a few windows, but with many windows, rolling over, eg, to the least-recently-used window is unexpected.)
• On first show, CmdTab selects the second item (index 1), which is the previously active window (index 0 is the currently active window). If no managed window is currently focused, it selects the first item (index 0). If invoked with Shift held, it selects the least-recent window.

Actions

• Window activation: Releasing the modifier key activates the currently selected window
• Minimized windows: Placed using the same placement rules as Launcher. Normally this means the targeted zone, but app-specific placement exceptions may redirect to the floating zone.
• Unminimized windows: Activated in place without being moved to the targeted zone (note: this is different from Launcher)
• While CmdTab is visible, clicking a window row activates that window immediately and dismisses CmdTab (even if modifiers are still held).
• Clicks outside the CmdTab window while it’s open retarget:
  • A left-click (with or without Control-Command) inside a tiling zone targets that zone and flashes its border, just like Control-Command-click does normally.
  • A click on the floating-zone indicator targets the floating zone; while CmdTab is visible this never opens the Launcher, even if the floating zone was already targeted. Other Zonogy UI (placeholders, add-zone pill, resize bars) behaves normally.
• Dragging a window row out: Same drag-and-drop behavior as dragging a window row from the Launcher; CmdTab dismisses on drag start. A drop outside any target, or Escape mid-drag, cancels the drag and restores the pre-CmdTab target under the same rules as a CmdTab cancel.
• New window in the current app: Pressing N sends a Command-N keystroke to the current app, which opens a new window. (The activation modifier is still held while CmdTab is visible, so on the default Command-Tab shortcut this is simply Command-N.)

Dismissal

• Activate: Releasing the modifier key dismisses CmdTab and activates the selected window
• Cancel: Pressing Escape dismisses CmdTab without activating any window (even if the modifier key is still held)
• Cancel: Clicking outside every tiling zone and Zonogy UI dismisses CmdTab.
• Target restoration: While CmdTab is open, both its open-time retarget and any “Toggle Target Zone with Focused Window” retarget are tentative. They commit if your selection places a window, or if you move the target yourself (e.g. arrow navigation); otherwise, cancelling or activating an already-open window restores the target CmdTab started with.
• Launcher shortcut: Pressing the Launcher keyboard shortcut while CmdTab is visible dismisses CmdTab and opens the Launcher. The target remains wherever CmdTab had it (no additional retarget), and CmdTab’s retarget session is inherited by the Launcher so a subsequent Launcher cancel follows the same pre-CmdTab restoration rule above.
• CmdTab dismisses if its screen enters full-screen pause.

App-Specific Mode (Cmd-`)

When invoked with the app-specific shortcut (default Cmd-`), CmdTab shows only windows belonging to the currently active application:

• Header: Displays “[App Name] Windows” instead of “Switch Windows”
• Window list: Filtered to show only windows from the frontmost application
• Empty state: If the current app has no managed windows, or if the frontmost app has no bundle identifier, the empty state is shown
• All other behavior (navigation, activation, dismissal) is identical to the standard CmdTab

Settings

• Keyboard shortcut configurable in Zonogy Preferences (default: Cmd-Tab)
• App-specific shortcut configurable in Zonogy Preferences (default: Cmd-`)
• CmdTab targets zone with focused window mode in Preferences → Targeting: Off (default), Current app only, or All windows too
• The modifier(s) for cycling are derived from the configured shortcut

Implementation Notes

• Reuse Launcher components and code paths wherever possible:
  • Window list rendering
  • Window entry styling and title truncation
  • Window activation logic
  • Panel positioning and visual style
• The window order should be maintained by tracking window activation timestamps
• To avoid contaminating recency with brief intermediate activations, only record a focus-based activation if the window remains focused for at least 250ms (shorter focus changes are ignored)
• Keyboard interception should use a CGEventTap for keyDown + flagsChanged events and swallow matching events to override the system app switcher

This site is open source. Improve this page.