PowerKeys Scripting API
    Preparing search index...

    Interface WindowAPI

    interface WindowAPI {
        GetActive(): WindowInfo | null;
        Find(query?: WindowQuery | null): WindowInfo[];
        Inspect(
            options?: WindowInspectOptions | null,
        ): Promise<WindowInspection | null>;
        Focus(windowId: string): boolean;
        Move(
            windowId: string,
            x: number,
            y: number,
            w?: number,
            h?: number,
        ): boolean;
        Close(windowId: string): void;
        OnActivated(callback: EventCallback<[win: WindowInfo | null]>): void;
    }
    Index
    GetActive Find Inspect Focus Move Close OnActivated

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

      Returns WindowInfo | null

      A snapshot of the foreground window, or null when no focusable window is active.

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

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

      window

    • Finds all visible windows matching the given filter criteria.

      Parameters

      • Optionalquery: WindowQuery | null

        Object with optional title and/or process filters. Omit or pass null to return every visible top-level window.

      Returns WindowInfo[]

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

      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.

      // 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" });

      window

    • Captures a bounded best-effort snapshot of a top-level window and its classic controls.

      Parameters

      • Optionaloptions: WindowInspectOptions | null

        Target, locked-window, and text-retrieval options. Omit or pass null for cursor targeting with fast text.

      Returns Promise<WindowInspection | null>

      Resolves with a snapshot, or null if no target window can be resolved.

      The cursor is sampled once by the host before target resolution. Cursor mode scans targetable top-level windows in z-order using cached rectangles plus a bounded native hit test; shaped and per-pixel layered surfaces remain best-effort, and a hit-test timeout conservatively selects that candidate. Foreground mode selects the active window, and windowId keeps a previously selected window locked. Every mode resolves the control under the sampled cursor within its target. Controls detected as password-style at either text-retrieval boundary are redacted. textPartial signals known or possible incompleteness from best-effort cross-process reads, redaction, timeout, truncation, access denial, or controls disappearing during capture.

      const snapshot = await Window.Inspect({ target: "cursor" });
      if (snapshot) Console.Log(snapshot.title + " / " + snapshot.className);

      windowInspection

    • 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.

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

      window

    • Moves a window to an absolute physical virtual-screen position and optionally resizes its outer bounds.

      Parameters

      • windowId: string

        The id from a WindowInfo object.

      • x: number

        Absolute new left edge.

      • y: number

        Absolute new top edge.

      • Optionalw: number

        Positive signed-32-bit outer width. Omit to keep the current width.

      • Optionalh: number

        Positive signed-32-bit outer height. Omit to keep the current height.

      Returns boolean

      true if the operation succeeded.

      x and y set the outer window's top-left corner; they are not relative offsets. The signed coordinate space is shared with Mouse, Screen, and overlays, so monitors left of or above the primary monitor use negative values. Width and height are physical pixels and are not DPI-scaled.

      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

      window

    • 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

      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.

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

      window

    • 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: EventCallback<[win: WindowInfo | null]>

        Handler receiving the newly activated window's WindowInfo, or null if it closed before dispatch.

      Returns void

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

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

      window

    Settings
    Member Visibility

    On This Page
    Methods