Interface HotkeyAPI

interface HotkeyAPI {
    Register(
        combo: string,
        callback: () => void,
        options?: HotkeyOptions,
    ): void;
    Unregister(combo: string): void;
    OnDown(combo: string, callback: () => void, options?: HotkeyOptions): void;
    OnUp(combo: string, callback: () => void, options?: HotkeyUpOptions): void;
}

Methods

Register Unregister OnDown OnUp

Methods

Register

  • Register(combo: string, callback: () => void, options?: HotkeyOptions): void

    Registers a global hotkey that triggers even when the PowerKeys window is not focused.

    Combo format: modifier tokens joined with +, with the main key last. Either-side modifiers: Ctrl, Shift, Alt, Win — match either physical side. Lateral modifiers: LCtrl, RCtrl, LShift, RShift, LAlt, RAlt, LWin, RWin — match only the named side. The main key can be a named key, a single character, or a hex code prefixed with VK_.

    Press-order independence: The combo fires when the last required key goes down, regardless of which order the keys were physically pressed.

    Modifier as main key: The last token can itself be a modifier (e.g. "Ctrl+Alt" where Alt is the main key). The combo fires when both are held, in any press order.

    Modifier leak cleanup (default block: true): Because modifier keys reach the foreground application individually as they are pressed, any modifier that was already down before the combo was fully recognized has already been delivered to the app. When the combo fires, synthetic key-up events are automatically injected for those leaked modifiers so the foreground application sees a clean state. Subsequent physical key-up events for those modifiers are suppressed so the application does not receive an unmatched release.

    Parameters

    • combo: string

      Key combination string, e.g. "Ctrl+Shift+T", "Ctrl+Alt", "F1".

    • callback: () => void

      Function invoked each time the hotkey fires.

    • Optionaloptions: HotkeyOptions

      Optional configuration object. See HotkeyOptions for details.

    Returns void

    Remarks

    AHK equivalent: Hotkey, Ctrl+Shift+T, MyLabel. Unlike AHK, all PowerKeys hotkeys are always active while the script is running — there is no #IfWinActive context; use Window.GetActive() inside the callback to implement window-specific behavior.

    Example

    // Simple hotkey
    Hotkey.Register("Ctrl+Shift+T", () => {
    Console.Log("triggered");
    });

    // Device-specific (only fires from one keyboard)
    Hotkey.Register("F5", () => { Console.Log("device F5"); }, {
    deviceId: "\\\\?\\HID#..."
    });

Unregister

  • Unregister(combo: string): void

    Removes a previously registered hotkey so it no longer triggers.

    Parameters

    • combo: string

      The same combo string that was passed to Hotkey.Register().

    Returns void

    Example

    Hotkey.Unregister("Ctrl+Shift+T");

OnDown

  • OnDown(combo: string, callback: () => void, options?: HotkeyOptions): void

    Registers a hotkey that fires exactly once per physical key press, suppressing auto-repeat events. The callback fires only on the initial key-down; holding the key does not repeat it. The held state is cleared when the combo keys are released, allowing the next press to fire again.

    Press-order independence: The combo fires when the last required key goes down, regardless of which order the keys were physically pressed.

    Modifier as main key: The last token can itself be a modifier (e.g. "Ctrl+Alt"). The combo fires when both are held, in any press order.

    Modifier leak cleanup (default block: true): Any modifier keys that reached the foreground application before the combo was fully recognized receive automatic synthetic key-up events when the combo fires. Subsequent physical key-ups for those modifiers are suppressed, leaving the application in a clean modifier state.

    Parameters

    • combo: string

      Key combination string, e.g. "Ctrl+Shift+T", "Ctrl+Alt", "F1".

    • callback: () => void

      Function invoked once on the initial key-down.

    • Optionaloptions: HotkeyOptions

      Optional configuration object. See HotkeyOptions for details.

    Returns void

    Remarks

    USE CASE: Toggle actions or held-key behaviors where auto-repeat would cause unwanted repeated firing. Pair with OnUp on the same combo to bracket a hold interval.

    Example

    Hotkey.OnDown("F1", () => {
    Console.Log("F1 held — fires once, not on repeat");
    });

OnUp

  • OnUp(combo: string, callback: () => void, options?: HotkeyUpOptions): void

    Registers a callback that fires when a key combination is released. Useful for held-key behaviors or measuring hold duration. Designed to be paired with OnDown on the same combo to bracket a hold.

    Modifier combos: Works with modifier-as-main-key combos (e.g. "Ctrl+Alt"). The callback fires on the physical key-up even though those keys are suppressed from reaching other applications by a paired OnDown registration.

    Note: OnUp does not itself register a block. Blocking is controlled entirely by the matching OnDown or Register call. When a key-down was blocked, the key-up is automatically suppressed even after modifiers are released — no extra configuration is needed here.

    Parameters

    • combo: string

      Key combination string, e.g. "Ctrl+Shift+T", "Ctrl+Alt", "F1".

    • callback: () => void

      Function invoked when the combo keys are released.

    • Optionaloptions: HotkeyUpOptions

      Only deviceId is accepted. Passing block or wildcard is a type error.

    Returns void

    Example

    // Measure how long F1 was held
    let pressedAt = 0;
    Hotkey.OnDown("F1", () => { pressedAt = Date.now(); });
    Hotkey.OnUp("F1", () => {
    Console.Log("held for " + (Date.now() - pressedAt) + "ms");
    });

Settings

Member Visibility

On This Page

Methods