Interface WindowAPI

interface WindowAPI {
    GetActive(): WindowInfo;
    Find(query: WindowQuery): WindowInfo[];
    Focus(windowId: string): boolean;
    Move(
        windowId: string,
        x: number,
        y: number,
        w?: number,
        h?: number,
    ): boolean;
    Close(windowId: string): void;
    OnActivated(callback: (win: WindowInfo) => void): void;
}

Methods

GetActive Find Focus Move Close OnActivated

Methods

GetActive

  • GetActive(): WindowInfo

    Returns information about the currently active (foreground) window, or null if no window is focused.

    Returns WindowInfo

    Remarks

    ALWAYS check for null before accessing properties — the return value is null when the desktop or no focusable window is active.

    Example

    const win = Window.GetActive();
    if (win) {
    Console.Log(win.title + " — " + win.processName);
    }

Find

  • Find(query: WindowQuery): WindowInfo[]

    Finds all visible windows matching the given filter criteria.

    Parameters

    • query: WindowQuery

      Object with optional title and/or process filters.

    Returns WindowInfo[]

    An array of matching WindowInfo objects. Empty array if none match.

    Remarks

    The title filter is treated as a regular expression when valid, falling back to substring match if the pattern is invalid. The process filter is always a case-insensitive substring match on the executable name.

    Example

    // By process name
    const chromeWins = Window.Find({ process: "chrome.exe" });

    // By title regex
    const notepadWins = Window.Find({ title: "Notepad" });

    // Combine both filters
    const [win] = Window.Find({ process: "code.exe", title: "my-script" });

Focus

  • Focus(windowId: string): boolean

    Brings the specified window to the foreground.

    Parameters

    • windowId: string

      The id from a WindowInfo object.

    Returns boolean

    true if the window was successfully focused.

    Example

    const [win] = Window.Find({ process: "notepad.exe" });
    if (win) {
    const ok = Window.Focus(win.id);
    Console.Log(ok ? "focused" : "focus failed");
    }

Move

  • Move(windowId: string, x: number, y: number, w?: number, h?: number): boolean

    Moves and optionally resizes a window.

    Parameters

    • windowId: string

      The id from a WindowInfo object.

    • x: number

      New left edge X coordinate in pixels.

    • y: number

      New top edge Y coordinate in pixels.

    • Optionalw: number

      New width in pixels. Omit to keep the current width.

    • Optionalh: number

      New height in pixels. Omit to keep the current height.

    Returns boolean

    true if the operation succeeded.

    Example

    const [win] = Window.Find({ process: "notepad.exe" });
    Window.Move(win.id, 0, 0, 1920, 1080); // full-screen position
    Window.Move(win.id, 100, 100);          // reposition only

Close

  • Close(windowId: string): void

    Sends a close request (WM_CLOSE) to the specified window. The window may prompt the user before closing.

    Parameters

    • windowId: string

      The id from a WindowInfo object.

    Returns void

    Remarks

    Equivalent to clicking the X button — the application handles the message and may show a save dialog or ignore the request. Use with care on unsaved documents.

    Example

    const [win] = Window.Find({ title: "Untitled - Notepad" });
    if (win) Window.Close(win.id);

OnActivated

  • OnActivated(callback: (win: WindowInfo) => void): void

    Registers a callback that fires whenever a different window becomes the foreground window. The script enters an event loop and stays alive as long as this handler is registered.

    Parameters

    • callback: (win: WindowInfo) => void

      Handler receiving the newly activated window's WindowInfo.

    Returns void

    Remarks

    USE CASE: Profile-style window-aware automation — run different logic depending on which application is currently focused.

    Example

    Window.OnActivated((win) => {
    Console.Log("Active: " + win.processName);
    });

Settings

Member Visibility

On This Page

Methods