Global hotkeys

Plugin hotkeys are registered by the host on the Qt main thread (RegisterHotKey); you only declare them or call the API. Plugins are forbidden from calling ctypes.RegisterHotKey themselves (binding on the wrong thread fails silently).

---

Declarative (recommended)

"hotkeys": [
  { "action": "translate_selection", "default": "Alt+T", "name": "划词翻译" }
]

• Once the plugin is enabled the host registers them automatically, and the user can rebind them in Settings → Hotkeys.
• action maps to the action_<action> method in your implementation.
• On trigger the host calls handle_action(action, {"source": "hotkey"}) → (default implementation) action_<action>(**params).

---

Runtime API

host.register_plugin_hotkey(plugin_id: str, action: str, key_seq: str, name: str = "") -> bool
host.unregister_plugin_hotkeys(plugin_id: str) -> bool
host.get_plugin_hotkeys() -> list[dict]

• Compatible aliases: registerPluginHotkey / unregisterPluginHotkeys / getPluginHotkeys.
• Callable from any thread; the host internally hops to the main thread to run RegisterHotKey.
• Internally the action key is plugin:{plugin_id}:{action}.
• Conflict detection is the same as for built-in hotkeys (a failed registration returns False — do not silently ignore it).
• Plugins without a hotkeys declaration can still register at runtime (e.g. adding them dynamically from config).

---

Lifecycle

• Register runtime hotkeys in initialize();
• Call host.unregister_plugin_hotkeys(self.id) in shutdown() (the host cleans up as a fallback, but doing it yourself is safer);
• When the user changes config, re-register in update_config() (the key combination may have changed).

---

Trigger path

user presses the hotkey
   → host dispatches the hotkey.triggered event (delivered to this plugin only)
   → calls handle_action(action, {"source": "hotkey"})
   → action_<action>(**params)        default implementation

Put heavy work in action_* via self.run_in_background(...); do not block the calling thread.

---

Related

• Event bus — hotkey.triggered
• Threading contract
• tool