How Keyboard Shortcuts Are Registered and Managed Globally in TUUI

TUUI uses Electron's globalShortcut API to register application-wide hotkeys through a centralized system in the main process that unregisters old bindings, loads user configuration, and registers new accelerators on every application start.

TUUI implements a robust global keyboard shortcut system that allows users to trigger actions even when the application window is not focused. This article examines how the Electron-based application registers and manages these shortcuts globally using a centralized configuration and registration pipeline defined in the main process.

Understanding TUUI's Global Shortcut Architecture

TUUI's shortcut system is split into three tightly-coupled layers that handle configuration, accelerator construction, and runtime registration.

Configuration and Default Shortcuts

The foundation of the system lives in src/main/aid/config.ts, which defines the Shortcut type and supplies default keybindings through loadSettings(). The configuration object specifies modifier keys (alt, ctrl, shift, meta) and the primary key.

By default, TUUI ships with Ctrl+Alt+T bound to the command action:

// src/main/aid/config.ts
export interface Shortcut {
  alt?: boolean;
  ctrl?: boolean;
  shift?: boolean;
  meta?: boolean;
  key: string;
}

export const loadSettings = (): Configuration => ({
  shortcuts: {
    command: {
      key: 'T',
      ctrl: true,
      alt: true
    }
  }
});

Accelerator Construction and Registration

The src/main/aid/shortcuts.ts file handles the conversion of configuration objects into Electron-compatible accelerator strings and manages the lifecycle of global registrations.

The shortcutAccelerator() function transforms a Shortcut object into the format Electron expects (e.g., Alt+Control+T):

// src/main/aid/shortcuts.ts
const shortcutAccelerator = (shortcut: Shortcut): string => {
  const parts: string[] = [];
  if (shortcut.ctrl) parts.push('Control');
  if (shortcut.alt) parts.push('Alt');
  if (shortcut.shift) parts.push('Shift');
  if (shortcut.meta) parts.push('Command');
  parts.push(shortcut.key.toUpperCase());
  return parts.join('+');
};

The private registerShortcut() method then binds this accelerator using globalShortcut.register():

// src/main/aid/shortcuts.ts
const registerShortcut = (
  shortcut: Shortcut,
  callback: () => void
): boolean => {
  const accelerator = shortcutAccelerator(shortcut);
  return globalShortcut.register(accelerator, callback);
};

Application Bootstrap Process

The registration pipeline is triggered when Electron's app emits the ready event. In src/main/index.ts, TUUI initializes the Commander subsystem before calling registerShortcuts() to ensure all dependencies are ready:

// src/main/index.ts
import { shortcuts } from './aid/shortcuts';
import { Commander } from './aid/commander';

const registerShortcuts = async () => {
  const initState = await Commander.init();
  if (initState) {
    shortcuts.registerShortcuts({
      command: () => Commander.initCommand()
    });
  }
};

app.whenReady().then(() => {
  // ... window creation logic
  registerShortcuts();
});

Because registration occurs in the main process, shortcuts remain active even when no renderer window is focused, which is essential for a desktop assistant like TUUI.

Step-by-Step Registration Flow

When TUUI registers and manages global keyboard shortcuts, it follows this deterministic pipeline:

1. Clear existing bindings – registerShortcuts() calls globalShortcut.unregisterAll() to prevent duplicate registrations.
2. Load configuration – loadSettings() retrieves the current shortcut map from config.ts.
3. Build accelerators – shortcutAccelerator() converts each shortcut object into an Electron-compatible string.
4. Register with Electron – globalShortcut.register(accelerator, callback) binds each hotkey to its handler.
5. Delegate to business logic – Callbacks route to Commander.initCommand() or other handlers defined in the bootstrap.

This reload-safe design allows TUUI to update shortcuts at runtime by simply re-invoking registerShortcuts() after configuration changes.

Customizing Global Keyboard Shortcuts in TUUI

To add or modify global keyboard shortcuts in TUUI, you must update both the configuration schema and the registration call.

Example: Adding a "Show Help" shortcut (Ctrl+H):

First, extend the types in src/main/aid/config.ts:

export type ShortcutsConfig = {
  command: Shortcut;
  help: Shortcut;  // New entry
};

export const loadSettings = (): Configuration => ({
  shortcuts: {
    command: { key: 'T', ctrl: true, alt: true },
    help: { key: 'H', ctrl: true }  // Ctrl+H
  }
});

Then, update the bootstrap in src/main/index.ts:

shortcuts.registerShortcuts({
  command: () => Commander.initCommand(),
  help: () => Commander.showHelp()  // Your custom handler
});

The existing pipeline in shortcuts.ts automatically handles the new shortcut without further modifications.

Summary

• TUUI registers global keyboard shortcuts using Electron's globalShortcut API in the main process.
• Configuration lives in src/main/aid/config.ts, defining the Shortcut type and default keybindings like Ctrl+Alt+T.
• src/main/aid/shortcuts.ts converts shortcuts to accelerators and manages registration lifecycle via registerShortcuts(), shortcutAccelerator(), and globalShortcut.register().
• The system calls globalShortcut.unregisterAll() before registering new shortcuts to prevent duplicates and enable runtime updates.
• Registration occurs in src/main/index.ts when the app.ready event fires, ensuring shortcuts work globally even without a focused window.

Frequently Asked Questions

What Electron API does TUUI use for global keyboard shortcuts?

TUUI uses the globalShortcut module from Electron's main process API. Specifically, it calls globalShortcut.register() to bind accelerators and globalShortcut.unregisterAll() to clear existing bindings before reloading configuration. This API allows the application to listen for keyboard events even when the application does not have keyboard focus.

Where are the default keyboard shortcuts defined in TUUI?

Default shortcuts are defined in src/main/aid/config.ts within the loadSettings() function. The default configuration includes a command shortcut mapped to Ctrl+Alt+T (represented as { key: 'T', ctrl: true, alt: true }). This file also exports the Shortcut interface that defines the shape of all shortcut objects used throughout the application.

Can I register multiple global shortcuts in TUUI?

Yes, you can register multiple shortcuts by extending the ShortcutsConfig type in src/main/aid/config.ts to include additional shortcut keys, providing default values in loadSettings(), and passing corresponding callback functions to shortcuts.registerShortcuts() in src/main/index.ts. The existing registration pipeline automatically iterates over all defined shortcuts and registers each with Electron's globalShortcut module.

Why do TUUI shortcuts work even when the window is not focused?

TUUI shortcuts work globally because they are registered in Electron's main process using the globalShortcut API, which operates at the operating system level rather than the renderer level. Unlike renderer-process keyboard listeners that require window focus, globalShortcut registers system-wide hotkeys that capture keystrokes regardless of which application currently has focus, which is essential for a desktop assistant utility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}