PowerKeys Scripting API
    Preparing search index...

    Interface MouseAPI

    interface MouseAPI {
        GetPos(): MousePosition;
        Move(x: number, y: number, smooth?: boolean): Promise<void>;
        Click(button?: MouseClickButton, clicks?: number): Promise<void>;
        Down(button?: MouseClickButton): Promise<void>;
        Up(button?: MouseClickButton): Promise<void>;
        Drag(
            startX: number,
            startY: number,
            endX: number,
            endY: number,
        ): Promise<void>;
        Scroll(lines: number): Promise<void>;
        OnRawEvent(callback: EventCallback<[event: RawMouseEvent]>): void;
        OnButton(
            combo: string,
            callback: EventCallback,
            options?: MouseButtonOptions,
        ): void;
        OnDown(
            combo: string,
            callback: EventCallback,
            options?: MouseButtonOptions,
        ): void;
        OnUp(
            combo: string,
            callback: EventCallback,
            options?: MouseButtonOptions,
        ): void;
    }
    Index
    GetPos Move Click Down Up Drag Scroll OnRawEvent OnButton OnDown OnUp

    • Returns the cursor's absolute position in physical Windows virtual-screen coordinates.

      Returns MousePosition

      The cursor's absolute physical virtual-screen x/y coordinates at the time of the call.

      const { x, y } = Mouse.GetPos();
      Console.Log(`Cursor at ${x}, ${y}`);

    • Moves the cursor to an absolute position in physical Windows virtual-screen coordinates.

      Parameters

      • x: number

        Absolute target X coordinate.

      • y: number

        Absolute target Y coordinate.

      • Optionalsmooth: boolean

        When true, the cursor glides to the target over ~100 ms. Defaults to false.

      Returns Promise<void>

      Resolves after the cursor reaches the target.

      Coordinates share a space with Screen.FindImage, Screen.GetPixelColor, WindowInfo.bounds, and overlay bounds. Preserve each value's documented reference point: for example, Screen.FindImage returns an image center while overlay Move expects a top-left. The primary monitor starts at (0, 0); monitors to its left or above use negative coordinates. No DPI scaling is applied. Coordinates outside the current virtual desktop are clamped to its nearest edge.

      await Mouse.Move(960, 540);        // instant warp to center
      await Mouse.Move(960, 540, true); // smooth glide over ~100ms

      mouse

    • Injects a complete button press-and-release at the current cursor position. Sends both the DOWN and UP events as a matched pair. To inject only the DOWN or only the UP, use Mouse.Down and Mouse.Up instead.

      Parameters

      • Optionalbutton: MouseClickButton

        Which button to click. Defaults to "left".

      • Optionalclicks: number

        Positive integer count of consecutive clicks. Defaults to 1; use 2 for a double-click.

      Returns Promise<void>

      Resolves after every requested click and inter-click delay completes.

      await Mouse.Click();             // left click
      await Mouse.Click("right");      // right click
      await Mouse.Click("left", 2);    // double-click

      mouse

    • Injects a button-down (press) event without a matching release. Use Mouse.Up with the same button to release it. Useful for simulating held button states or custom drag sequences.

      Parameters

      • Optionalbutton: MouseClickButton

        Button to press: "left", "right", "middle", "x1", "x2". Defaults to "left".

      Returns Promise<void>

      Resolves after the button-down event is injected.

      await Mouse.Down("left");   // press and hold left button
      // ... do work ...
      await Mouse.Up("left");     // release

      mouse

    • Injects a button-up (release) event without a preceding press. Intended to pair with a prior Mouse.Down call.

      Parameters

      • Optionalbutton: MouseClickButton

        Button to release: "left", "right", "middle", "x1", "x2". Defaults to "left".

      Returns Promise<void>

      Resolves after the button-up event is injected.

      await Mouse.Down("left");
      // ... do work ...
      await Mouse.Up("left");

      mouse

    • Performs a left-button drag between two absolute physical virtual-screen positions. The cursor is moved to the start position, the button is pressed, the cursor glides to the end position, then the button is released.

      Parameters

      • startX: number

        Absolute starting X coordinate.

      • startY: number

        Absolute starting Y coordinate.

      • endX: number

        Absolute ending X coordinate.

      • endY: number

        Absolute ending Y coordinate.

      Returns Promise<void>

      Resolves after the drag finishes and the button is released.

      Coordinates use the same signed physical-pixel space as Mouse.Move and Screen.FindImage; monitors left of or above the primary monitor have negative coordinates. Start or end coordinates outside the current virtual desktop are clamped to its nearest edge.

      await Mouse.Drag(100, 200, 400, 200); // drag horizontally

      mouse

    • Emits vertical mouse-wheel detents at the current cursor position.

      Parameters

      • lines: number

        Signed detent count. Positive values scroll up; negative values scroll down.

      Returns Promise<void>

      Resolves after the wheel event is injected.

      Each integer unit emits one Windows WHEEL_DELTA step (120). The operating system and target application decide how many text lines or pixels that step scrolls, so the historical parameter name lines is not a literal row count.

      await Mouse.Scroll(3);  // three wheel detents up
      await Mouse.Scroll(-3); // three wheel detents down

      mouse

    • Registers a callback that fires on every raw mouse event. The script enters an event loop and stays alive as long as this handler is registered.

      Parameters

      Returns void

      USE CASE: Per-device mouse filtering using event.device_id, or reacting to specific button flags without using a hotkey binding.

      Mouse.OnRawEvent((e) => {
      Console.Log("flags: " + e.button_flags);
      });

      mouse

    • Registers a callback that fires when a mouse button is pressed down, optionally requiring modifier keys to be held at the same time.

      Combo format: optional modifier tokens joined with +, with the button name last. Either-side modifiers: Ctrl, Shift, Alt, Win. Lateral modifiers: LCtrl, RCtrl, LShift, RShift, LAlt, RAlt, LWin, RWin.

      Button names (case-insensitive): LButton, RButton, MButton, XButton1, XButton2. Long aliases LeftButton, RightButton, MiddleButton, Mouse4, Mouse5 are also accepted.

      Blocking (default block: true): Both the button-down and its paired button-up are suppressed from reaching other applications. The modifier keys themselves are not suppressed. Use Keyboard.Press to send any needed cleanup. Set block: false to observe the click while passing it through.

      Parameters

      • combo: string

        Button combination string, e.g. "LButton", "Shift+LButton", "Ctrl+Alt+RButton".

      • callback: EventCallback

        Function invoked when the combo fires (on button-down).

      • Optionaloptions: MouseButtonOptions

        Optional configuration. See MouseButtonOptions for details.

      Returns void

      // Intercept Shift+LButton
      Mouse.OnButton("Shift+LButton", () => {
      const pos = Mouse.GetPos();
      Console.Log(`shift-clicked at ${pos.x}, ${pos.y}`);
      });

      // Non-blocking observe-only
      Mouse.OnButton("Ctrl+RButton", () => {
      Console.Log("ctrl right-click");
      }, { block: false });

      mouse

    • Registers a callback that fires when a mouse button is pressed down, identical in behavior to Mouse.OnButton.

      Use this when you want to be explicit that you are reacting to the press phase and may also register an OnUp handler for the release phase.

      Button names and modifiers: same as Mouse.OnButton. Blocking: same as Mouse.OnButton, both down and its paired up are suppressed when block: true (default).

      Parameters

      • combo: string

        Button combination string, e.g. "LButton", "Shift+LButton".

      • callback: EventCallback

        Function invoked on button-down.

      • Optionaloptions: MouseButtonOptions

        Optional configuration. See MouseButtonOptions for details.

      Returns void

      let heldAt = 0;
      Mouse.OnDown("XButton1", () => { heldAt = Date.now(); });
      Mouse.OnUp("XButton1", () => {
      Console.Log("held for " + (Date.now() - heldAt) + "ms");
      });

      mouse

    • Registers a callback that fires when a mouse button is released.

      Button names and modifiers: same as Mouse.OnButton.

      Blocking: defaults to false. Set block: true in options to also suppress the button-up event from reaching other applications.

      Pairing with OnDown: When a button-down was blocked by OnButton or OnDown, the button-up is already suppressed automatically. Register OnUp on the same button to observe or act on the release without needing to set block: true on the OnUp handler.

      Parameters

      • combo: string

        Button combination string, e.g. "LButton", "Shift+LButton".

      • callback: EventCallback

        Function invoked on button-up.

      • Optionaloptions: MouseButtonOptions

        Optional configuration. See MouseUpOptions for details.

      Returns void

      // Measure LButton hold duration
      let pressedAt = 0;
      Mouse.OnDown("LButton", () => { pressedAt = Date.now(); });
      Mouse.OnUp("LButton", () => {
      Console.Log("held for " + (Date.now() - pressedAt) + "ms");
      });

      mouse

    Settings
    Member Visibility

    On This Page
    Methods