# How Vorssaint Uses macOS Accessibility APIs for Programmatic Window Positioning

> Discover how Vorssaint uses macOS Accessibility APIs for programmatic window positioning. Learn about the AX framework, Core Graphics, and AppKit for window manipulation.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-06

---

**Vorssaint relies on the native macOS Accessibility (AX) framework, Core Graphics window identifiers, and AppKit screen geometry to programmatically move, resize, and animate windows via system-level attribute manipulation.**

The open-source utility `vorssaint/vorssaint-utils` implements advanced window management by directly interfacing with macOS system APIs rather than using high-level scripting. Its programmatic window positioning logic centers on the **Accessibility framework**, which grants low-level access to UI elements through `AXUIElement` references. The implementation is concentrated in the `WindowMaximizer` service, with supplemental support from window layout and switcher modules that reuse the same primitive AX operations.

## Core macOS Accessibility Framework

Vorssaint’s window positioning engine is built on the **Accessibility (AX) framework**, a private-user-interface bridge that allows assistive technologies to inspect and control applications. The code manipulates window geometry through a six-step workflow that combines element discovery, attribute validation, and value mutation.

### Locating Target Windows

To begin repositioning, Vorssaint must first obtain a reference to the window’s underlying UI element. The system calls `AXUIElementCopyElementAtPosition` on the system-wide accessibility element to retrieve an `AXUIElement` representing the window under the cursor or at a specified coordinate. This element acts as the handle for all subsequent positioning operations.

### Reading Frame Attributes

Once the window element is acquired, Vorssaint reads its current geometry using `AXUIElementCopyAttributeValue`. The function queries for the `kAXPositionAttribute` and `kAXSizeAttribute` keys, returning `AXValue` objects that are unwrapped into `CGPoint` and `CGSize` structures. These conversions occur in helper methods within `WindowMaximizer` (referenced as `pointAttribute` and `sizeAttribute` in the source), establishing the baseline coordinates before any transformation.

### Writing Position and Size

Actual window movement happens through `AXUIElementSetAttributeValue`, the primary API for programmatic window positioning in Vorssaint. The code wraps target coordinates in `AXValue` objects using `AXValueCreate`, then writes them to the element:

```swift
func setPosition(_ point: CGPoint, on element: AXUIElement) -> Bool {
    var point = point
    guard let value = AXValueCreate(.cgPoint, &point) else { return false }
    return AXUIElementSetAttributeValue(element,
                                        kAXPositionAttribute as CFString,
                                        value) == .success
}

func setSize(_ size: CGSize, on element: AXUIElement) -> Bool {
    var size = size
    guard let value = AXValueCreate(.cgSize, &size) else { return false }
    return AXUIElementSetAttributeValue(element,
                                        kAXSizeAttribute as CFString,
                                        value) == .success
}

```

These functions return boolean success indicators based on the `AXError` status code, allowing the service to detect permission failures or unsupported windows.

### Validating Modification Permissions

Before attempting to reposition a window, Vorssaint checks whether the target attributes are writable. The `canSetFrame` method in [`Source/Vorssaint/Services/WindowMaximizer.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Source/Vorssaint/Services/WindowMaximizer.swift) calls `AXUIElementIsAttributeSettable` for both position and size attributes:

```swift
private func canSetFrame(on window: AXUIElement) -> Bool {
    var positionSettable = DarwinBoolean(false)
    var sizeSettable     = DarwinBoolean(false)

    let positionStatus = AXUIElementIsAttributeSettable(window,
                                 kAXPositionAttribute as CFString,
                                 &positionSettable)
    let sizeStatus = AXUIElementIsAttributeSettable(window,
                                 kAXSizeAttribute as CFString,
                                 &sizeSettable)

    return positionStatus == .success && sizeStatus == .success &&
           positionSettable.boolValue && sizeSettable.boolValue
}

```

This validation prevents runtime errors when encountering system windows or applications with accessibility protections enabled.

## Animation and Coordinate Translation

Beyond static positioning, Vorssaint implements smooth window transitions using a **Timer-based animation loop** that interpolates between the current `AXFrame` and the target frame, repeatedly invoking the set-attribute calls at each step. This creates the visual effect of the window gliding into position without relying on private animation APIs.

### Core Graphics Integration

To translate between the AX coordinate system and screen-space geometry, Vorssaint utilizes **CoreGraphics** (`CG...`) utilities. `CGWindowID` uniquely identifies windows for metadata retrieval, while `CGEvent` tap code intercepts mouse clicks that trigger resize operations. These identifiers bridge the gap between the accessibility element handles and the window server’s display composition.

### AppKit Screen Geometry

For calculating maximization bounds and multi-monitor positioning, Vorssaint leverages **AppKit’s** `NSScreen` enumerations. Methods like `bestScreen` and `menuBarScreenTopY` compute the target frame’s origin and dimensions based on the visible trackpad area, menu bar insets, and display scaling factors. This ensures that programmatically positioned windows respect the user’s display arrangement and dock settings.

## WindowMaximizer Implementation

The `WindowMaximizer` service orchestrates the complete positioning workflow. Its core toggle logic demonstrates how Vorssaint combines attribute reading, frame calculation, and attribute writing to switch between restored and maximized states:

```swift
// Inside WindowMaximizer.toggle(_:)
// 1️⃣ Get the current frame
guard let current = frame(of: target.window) else { return false }

// 2️⃣ Compute the maximised frame for the screen that contains the window
let maximized = axFrame(fromAppKit: screen.visibleFrame)

// 3️⃣ If the window is already near the maximised size, restore the original frame
if current.isClose(to: maximized, tolerance: frameTolerance),
   let original = originalFrames[target.windowID] {
    changeFrame(to: original, of: target) { _ in … }
} else {
    // 4️⃣ Otherwise store the original frame and move to the maximised one
    originalFrames[target.windowID] = current
    changeFrame(to: maximized, of: target) { _ in … }
}

```

This implementation stores original frames in a dictionary keyed by `CGWindowID`, enabling restoration after maximization.

### Fallback to Native Actions

When the Accessibility-based change fails (indicated by `AXUIElementSetAttributeValue` returning an error), Vorssaint falls back to `AXUIElementPerformAction` for the window’s zoom button. This native UI action triggers the application’s built-in maximize behavior as a less precise but more compatible alternative.

## Supporting Services Using the Same APIs

Several other components in `vorssaint-utils` reuse these programmatic window positioning primitives:

- **WindowLayoutService** ([`Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift)): Orchestrates tiled window layouts by invoking the same `AXUIElementSetAttributeValue` calls to snap windows into grid positions.

- **WindowLayoutSupport** ([`Sources/Vorssaint/Services/WindowLayout/WindowLayoutSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/WindowLayout/WindowLayoutSupport.swift)): Provides helper enums that translate layout actions (left-half, right-half, etc.) into specific AX position/size write operations.

- **WindowEnumerator** ([`Sources/Vorssaint/Services/Switcher/WindowEnumerator.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Switcher/WindowEnumerator.swift)): Retrieves window positions via `AXUIElementCopyAttributeValue` to build sorted navigation lists for the switcher interface.

- **WindowActivator** ([`Sources/Vorssaint/Services/Switcher/WindowActivator.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Switcher/WindowActivator.swift)): Restores window positions after activation using the stored AX position attributes, ensuring the switcher returns windows to their pre-navigation coordinates.

## Summary

- Vorssaint implements programmatic window positioning primarily through the **macOS Accessibility (AX) framework**, specifically using `AXUIElementSetAttributeValue` to modify `kAXPositionAttribute` and `kAXSizeAttribute`.
- Before moving windows, the code validates permissions via `AXUIElementIsAttributeSettable` in the `canSetFrame` method of [`WindowMaximizer.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowMaximizer.swift).
- **CoreGraphics** (`CGWindowID`, `CGEvent`) and **AppKit** (`NSScreen`) provide coordinate translation and screen geometry calculations.
- Animation is achieved through a Timer-based loop that interpolates frame changes over time, repeatedly calling the AX set-attribute methods.
- The same AX primitives are shared across `WindowMaximizer`, `WindowLayoutService`, and the window switcher components to maintain consistent behavior throughout the application.

## Frequently Asked Questions

### Which specific API does Vorssaint call to physically move a window on screen?

Vorssaint calls `AXUIElementSetAttributeValue` with the `kAXPositionAttribute` key to programmatically move windows. This function requires a valid `AXUIElement` reference and an `AXValue` wrapping a `CGPoint` structure. The call returns an `AXError` status that indicates success or failure based on the target application’s accessibility permissions.

### How does Vorssaint handle windows that refuse Accessibility-based resizing?

When `AXUIElementIsAttributeSettable` returns false or `AXUIElementSetAttributeValue` fails, Vorssaint falls back to `AXUIElementPerformAction` targeting the window’s zoom button. This triggers the native maximize behavior built into the application, providing a reliable alternative when direct frame manipulation is restricted by the target app’s sandbox or permissions.

### Does Vorssaint use any private or undocumented APIs for window positioning?

No, Vorssaint relies on documented public frameworks: the **Accessibility framework** for UI control, **CoreGraphics** for window identification, and **AppKit** for screen metrics. All function signatures used—such as `AXUIElementCopyAttributeValue`, `AXUIElementSetAttributeValue`, and `CGWindowID`—are part of Apple’s public SDK, though they require the user to grant Accessibility permissions in System Settings.

### Where is the core window positioning logic located in the repository?

The primary implementation resides in [`Sources/Vorssaint/Services/WindowMaximizer.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/WindowMaximizer.swift). This file contains the `setPosition`, `setSize`, and `canSetFrame` methods that wrap the AX APIs. Supplemental positioning logic appears in [`Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift) for tiling and [`Sources/Vorssaint/Services/Switcher/WindowEnumerator.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Switcher/WindowEnumerator.swift) for position retrieval.