Global Hotkeys

Namespace: web.hotkey

Overview

The web.hotkey namespace lets you register system-wide keyboard shortcuts (global hotkeys) that fire even when your app is minimized, hidden in the system tray, or another window has focus. This uses the Windows RegisterHotKey API under the hood.

Global hotkeys are ideal for:

Quick-launch: Bring the app to front from anywhere with a keypress
Clipboard tools: Capture clipboard contents on demand
Tray utilities: Restore a tray-resident app without clicking the tray icon
Quick-capture: Screenshot tools, note-taking, time tracking toggles

Limits

Hotkey IDs must be integers >= 1 — no upper limit on how many you can register
If another application has already registered the same key combination, standard registration returns false
Passthrough hotkeys (passthrough: true) use a keyboard hook instead of RegisterHotKey and are not subject to key-conflict failures

Standard vs Passthrough

	Standard	Passthrough
Mechanism	Windows `RegisterHotKey`	`WH_KEYBOARD_LL` hook
Key consumed?	Yes — not sent to foreground app	No — key passes through
Modifier support	Yes	No (bare VK only)
Use case	Shortcuts, restore-from-tray	Soundboards while typing

Pass passthrough: true to web.hotkey.register to use the hook-based mode. See register for full details.

Available Methods

Method	Description
`register`	Register a global hotkey
`unregister`	Unregister a single hotkey by ID
`unregisterAll`	Unregister all hotkeys at once

Event	Fires when...
`web.events.onHotkey`	A registered global hotkey is pressed anywhere in Windows

Quick Start

document.addEventListener('DOMContentLoaded', async () => {

    // 1. Set up the event handler
    web.events.onHotkey = function(hotkeyId) {
        if (hotkeyId === 1) {
            alert('Hotkey pressed!');
        }
    };

    // 2. Register a hotkey: Ctrl+Alt+H
    const ok = await web.hotkey.register({ id: 1, key: 'H', modifiers: 'ctrl+alt' });
    if (!ok) {
        console.log('Could not register — key combo may be taken');
    }
});

Notes

All registered hotkeys are automatically unregistered when the app closes — no manual cleanup needed
Re-registering an existing ID with a different key combination automatically unregisters the old one first
The onHotkey event fires on the Delphi side via WM_HOTKEY and is forwarded to JavaScript — there may be a brief delay if the app window is hidden
Hotkeys work alongside the web.appMenu and web.trayMenu APIs — use hotkeys for keyboard-driven access and menus for mouse-driven access