onHotkey

Category: Events

Namespace: web.events.onHotkey

Description

Fires when a registered global hotkey is pressed anywhere in Windows — even when the app is minimized, hidden in the system tray, or another application has focus.

This event works in tandem with web.hotkey.register(). You must register at least one hotkey for this event to fire.

Syntax

web.events.onHotkey = function(hotkeyId) {
    // hotkeyId is the integer id passed to web.hotkey.register()
};

Parameters

The callback receives one argument:

• hotkeyId integer — The ID of the hotkey that was pressed (1–6), matching the id passed to web.hotkey.register().

Returns

Nothing. This is an event handler assignment, not a function call.

Examples

Basic — respond to a single hotkey

document.addEventListener('DOMContentLoaded', async () => {
    web.events.onHotkey = function(id) {
        if (id === 1) {
            document.getElementById('status').textContent = 'Hotkey pressed!';
        }
    };

    await web.hotkey.register({ id: 1, key: 'H', modifiers: 'ctrl+alt' });
});

Restore from minimized — bring app to front with a keypress

This is the most common use case: the app is minimized to the taskbar, and the user presses a hotkey to bring it back instantly.

document.addEventListener('DOMContentLoaded', async () => {
    web.events.onHotkey = async function(id) {
        if (id === 1) {
            // Restore the window from minimized/hidden state
            await web.app.windowRestore();
        }
    };

    // Register Ctrl+Shift+R as the "show app" hotkey
    const ok = await web.hotkey.register({ id: 1, key: 'R', modifiers: 'ctrl+shift' });
    if (ok) {
        await web.window.setTitle({ title: 'My App — Press Ctrl+Shift+R to restore' });
    }
});

Tray utility — restore from system tray with hotkey

For apps that minimize to the system tray (Builder's "Minimize to System Tray" setting), a global hotkey gives users a keyboard shortcut to restore the app without hunting for the tray icon.

document.addEventListener('DOMContentLoaded', async () => {
    web.events.onHotkey = async function(id) {
        switch (id) {
            case 1:
                // Restore from tray / minimized
                await web.app.windowRestore();
                break;
            case 2:
                // Quick action without restoring — grab clipboard
                const text = await web.clipboard.readText();
                if (text) {
                    // Save to a file in AppData
                    const appData = await web.directory.getAppDataDir();
                    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
                    await web.files.writeTextFile({
                        filePath: appData + '\\ClipCapture\\clip_' + timestamp + '.txt',
                        contents: text
                    });
                    await web.system.notification({
                        name: 'clip-saved',
                        title: 'Clipboard Saved',
                        message: text.substring(0, 80) + (text.length > 80 ? '...' : '')
                    });
                }
                break;
        }
    };

    // Ctrl+Alt+R = restore window
    await web.hotkey.register({ id: 1, key: 'R', modifiers: 'ctrl+alt' });
    // Ctrl+Alt+C = capture clipboard (works even when app is hidden)
    await web.hotkey.register({ id: 2, key: 'C', modifiers: 'ctrl+alt' });
});

Toggle visibility — press hotkey to show/hide

document.addEventListener('DOMContentLoaded', async () => {
    web.events.onHotkey = async function(id) {
        if (id === 1) {
            const state = await web.window.getState();
            if (state === 'minimized') {
                await web.app.windowRestore();
            } else {
                await web.app.windowMinimize();
            }
        }
    };

    // Ctrl+` (backtick) to toggle — similar to VS Code terminal toggle
    await web.hotkey.register({ id: 1, key: 'H', modifiers: 'ctrl+alt' });
});

Multiple hotkeys — keyboard-driven utility app

document.addEventListener('DOMContentLoaded', async () => {
    web.events.onHotkey = async function(id) {
        switch (id) {
            case 1: await web.app.windowRestore();       break;  // Show app
            case 2: await web.app.windowMinimize();       break;  // Hide app
            case 3: await captureScreenRegion();          break;  // Custom action
            case 4: await toggleAlwaysOnTop();            break;  // Custom action
            case 5: await quickNote();                    break;  // Custom action
            case 6: await web.app.close();                break;  // Exit app
        }
    };

    await web.hotkey.register({ id: 1, key: 'F1', modifiers: 'ctrl+shift' });
    await web.hotkey.register({ id: 2, key: 'F2', modifiers: 'ctrl+shift' });
    await web.hotkey.register({ id: 3, key: 'F3', modifiers: 'ctrl+shift' });
    await web.hotkey.register({ id: 4, key: 'F4', modifiers: 'ctrl+shift' });
    await web.hotkey.register({ id: 5, key: 'F5', modifiers: 'ctrl+shift' });
    await web.hotkey.register({ id: 6, key: 'F6', modifiers: 'ctrl+shift' });
});

User-configurable hotkey with persistence

document.addEventListener('DOMContentLoaded', async () => {
    // Load saved hotkey preference
    await web.variables.loadVariables('hotkey-prefs.json');
    const savedMod = await web.variables.getVar('hotkeyMod') || 'ctrl+alt';
    const savedKey = await web.variables.getVar('hotkeyKey') || 'H';

    web.events.onHotkey = async function(id) {
        if (id === 1) await web.app.windowRestore();
    };

    const ok = await web.hotkey.register({ id: 1, key: savedKey, modifiers: savedMod });
    if (!ok) {
        console.log('Saved hotkey combo is taken, using fallback');
        await web.hotkey.register({ id: 1, key: 'F12', modifiers: 'ctrl+shift' });
    }
});

// Called from a settings UI when user picks a new key combo
async function changeHotkey(newMod, newKey) {
    const ok = await web.hotkey.register({ id: 1, key: newKey, modifiers: newMod });
    if (ok) {
        // Save preference
        await web.variables.setVar('hotkeyMod', newMod);
        await web.variables.setVar('hotkeyKey', newKey);
        await web.variables.saveVariables('hotkey-prefs.json');
    }
    return ok;
}

Use Cases

• Restore from tray — bring a hidden/minimized app to the front instantly
• Quick capture — grab clipboard contents, take a note, start a timer — all without switching windows
• Toggle visibility — show/hide the app like a drop-down terminal
• Global shortcuts — expose up to 6 app functions as system-wide keyboard shortcuts
• Launcher/utility apps — background apps that only appear when summoned by hotkey

Notes

• Set the handler before calling web.hotkey.register() to avoid missing early key presses
• The callback fires on the main JavaScript thread — you can use async/await inside it
• Only one onHotkey handler can be active at a time (assigning a new one replaces the old one)
• The handler receives the integer ID, not the key name — use a switch or if to dispatch
• Works correctly alongside onAppMenuItemClick, onTrayMenuItemClick, onFileDrop, and all other events
• If the app is in the system tray, web.app.windowRestore() restores the window to its previous state