Skip to main content

​
Overview

Focus actions enable keyboard-driven navigation between windows based on their spatial relationship. Instead of cycling through windows with Cmd+Tab, you can move focus directionally (up, down, left, right) or through window stacking order. Defined in the static focus array (line 86): 
static var focus: [WindowDirection] { 
    [.focusUp, .focusDown, .focusRight, .focusLeft, 
     .focusNextInStack] 
}

​
Computed Property

​
willFocusWindow
Bool
Returns true for all focus actions (line 96)
var willFocusWindow: Bool { 
    WindowDirection.focus.contains(self) 
}
Used to identify actions that change window focus without resizing or moving the focused window.

​
Directional Focus

Directional focus actions move keyboard focus to the nearest window in the specified direction.

​
focusLeft

​
focusLeft
WindowDirection
Moves focus to the nearest window positioned to the left.Raw Value: "FocusLeft"URL Scheme: loop://FocusLeftBehavior:
  • Activates the window whose center point is nearest to the left
  • Searches within the same screen/Space
  • No effect if no window exists to the left
  • Does not move or resize any windows
Navigation Direction: .left (line 151)Visual:
┌────────┐  ┌────────┐  ┌────────┐
│ Window │  │Current │  │        │
│   A    │  │ (You)  │  │        │
└────────┘  └────────┘  └────────┘
    ↑
 Focus moves here

​
focusRight

​
focusRight
WindowDirection
Moves focus to the nearest window positioned to the right.Raw Value: "FocusRight"URL Scheme: loop://FocusRightBehavior:
  • Activates the window whose center point is nearest to the right
  • Searches within the same screen/Space
  • No effect if no window exists to the right
  • Does not move or resize any windows
Navigation Direction: .right (line 152)Visual:
┌────────┐  ┌────────┐  ┌────────┐
│        │  │Current │  │ Window │
│        │  │ (You)  │  │   B    │
└────────┘  └────────┘  └────────┘
                            ↑
                     Focus moves here

​
focusUp

​
focusUp
WindowDirection
Moves focus to the nearest window positioned above.Raw Value: "FocusUp"URL Scheme: loop://FocusUpBehavior:
  • Activates the window whose center point is nearest above
  • Searches within the same screen/Space
  • No effect if no window exists above
  • Does not move or resize any windows
Navigation Direction: .top (line 153)Visual:
     ┌────────┐
     │ Window │ ← Focus moves here
     │   C    │
     └────────┘
     ┌────────┐
     │Current │
     │ (You)  │
     └────────┘

​
focusDown

​
focusDown
WindowDirection
Moves focus to the nearest window positioned below.Raw Value: "FocusDown"URL Scheme: loop://FocusDownBehavior:
  • Activates the window whose center point is nearest below
  • Searches within the same screen/Space
  • No effect if no window exists below
  • Does not move or resize any windows
Navigation Direction: .bottom (line 154)Visual:
     ┌────────┐
     │Current │
     │ (You)  │
     └────────┘
     ┌────────┐
     │ Window │ ← Focus moves here
     │   D    │
     └────────┘

​
Stack-Based Focus

​
focusNextInStack

​
focusNextInStack
WindowDirection
Moves focus to the next window in the stacking order.Raw Value: "FocusNextInStack"URL Scheme: loop://FocusNextInStackBehavior:
  • Cycles through windows in z-order (front to back)
  • Similar to Cmd+Tab but for visible windows only
  • Wraps around to first window after reaching last
  • Works within current screen/Space
  • Does not move or resize any windows
Stacking Order:
Window 1 (Front) → Window 2 → Window 3 → Window 1 (cycles)
Use Case: Cycle through overlapping windows without spatial reasoning
Focus actions map to NavigationDirection for internal routing (lines 149-157): 
var focusDirection: NavigationDirection? {
    switch self {
    case .focusLeft: .left
    case .focusRight: .right
    case .focusUp: .top
    case .focusDown: .bottom
    default: nil
    }
}
This property enables directional window discovery algorithms.

​
Usage Examples

​
Vim-Style Navigation

# Navigate windows with directional keys
open "loop://FocusLeft"   # h
open "loop://FocusDown"   # j
open "loop://FocusUp"     # k
open "loop://FocusRight"  # l
Bind to keyboard shortcuts:
  • Cmd+Ctrl+H: Focus left
  • Cmd+Ctrl+J: Focus down
  • Cmd+Ctrl+K: Focus up
  • Cmd+Ctrl+L: Focus right

​
Multi-Window Workflow

# Navigate through a grid of windows
# Layout:
# ┌─────┬─────┬─────┐
# │  1  │  2  │  3  │
# ├─────┼─────┼─────┤
# │  4  │  5  │  6  │
# └─────┴─────┴─────┘

# From window 5 (center):
open "loop://FocusUp"     # → Window 2
open "loop://FocusRight"  # → Window 3
open "loop://FocusDown"   # → Window 6
open "loop://FocusLeft"   # → Window 5

​
Overlapping Windows

# Cycle through stacked windows on same position
open "loop://FocusNextInStack"  # Next window in stack
open "loop://FocusNextInStack"  # Next window in stack
open "loop://FocusNextInStack"  # Cycles back to first

​
Combining with Positioning

Focus actions are particularly powerful when combined with window positioning: 
# Focus and resize workflow
open "loop://FocusLeft"     # Move focus to left window
open "loop://LeftHalf"      # Resize it to left half

open "loop://FocusRight"    # Move focus to right window
open "loop://RightHalf"     # Resize it to right half

​
Spatial Navigation Algorithm

Directional focus uses spatial proximity to determine the target window:
  1. Calculate center points of all visible windows
  2. Filter by direction (e.g., for focusLeft, only windows with center X < current window center X)
  3. Compute distances from current window center to candidate window centers
  4. Select nearest window based on Euclidean distance
  5. Activate the target window

​
Edge Cases

When multiple windows are equidistant, Loop selects based on:
  • Z-order (frontmost window preferred)
  • Window size (larger windows preferred)
If no window exists in the specified direction:
  • Focus remains on current window
  • No visual feedback or error
  • Can be combined with screen switching for cross-display navigation
For windows positioned diagonally:
  • Directional focus uses the primary axis (horizontal or vertical)
  • May require two focus actions to reach diagonal windows
  • Example: Focus right, then focus up

​
Radial Menu Behavior

Focus actions don’t have specific directional angles in the radial menu (line 102): 
var hasRadialMenuAngle: Bool {
    return !(... || willFocusWindow)
}
They appear as menu options rather than directional triggers.

​
Keyboard-Driven Workflows

Focus actions enable fully keyboard-driven window management:

​
Tiling Workflow

  1. Focus window with directional navigation
  2. Position window with positioning actions
  3. Repeat for all windows in layout

​
Quick Reference Layout

# Set up documentation + code + terminal layout
# Start with browser (docs)
open "loop://LeftTwoThirds"      # Browser: 66% left

# Move to editor (code)
open "loop://FocusRight"
open "loop://TopRightQuarter"   # Editor: top-right 25%

# Move to terminal
open "loop://FocusDown"
open "loop://BottomRightQuarter" # Terminal: bottom-right 25%

​
Accessibility Benefits

Focus actions provide significant accessibility advantages:
  • Keyboard-only navigation: No mouse required
  • Spatial reasoning: Intuitive directional movement
  • Predictable behavior: Consistent navigation patterns
  • Fast context switching: Direct window selection without cycling

​
Troubleshooting

  • Verify windows are on the same screen/Space
  • Check if target window is minimized or hidden
  • Ensure target window is actually positioned in the expected direction
  • Hidden windows and minimized windows are excluded from focus navigation
  • Only visible windows are included in stack order
  • Minimized and hidden windows are excluded
  • Stack order reflects z-order, not window creation order
  • No window exists in the specified direction
  • Current window is the only visible window
  • Target window may be on a different screen (use screen switching first)

Screen Switching

Move focus to windows on other displays

General Actions

Minimize and hide windows

Size Adjustment

Move windows after focusing them

WindowDirection Overview

Complete action reference

​
Best Practices

Combine with positioning: Use focus actions to select a window, then immediately apply a positioning action. This creates powerful keyboard-driven workflows.
Consistent keybinds: Map focus actions to easily reachable key combinations. Vim-style HJKL or arrow key combinations work well.
Multi-step navigation: For complex layouts, use multiple focus actions in sequence to reach distant windows efficiently.

Build docs developers (and LLMs) love

Get started for freeTalk to us