Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

Add macOS mouse button hotkeys (#755)

Muhammad Doukmak4b40417b643e
diff --git a/main.js b/main.js
index 19b4d8000..6346f0d83 100644
--- a/main.js
+++ b/main.js
@@ -934,7 +934,7 @@ async function startApp() {
updateManager.checkForUpdatesOnStartup();
if (process.platform === "darwin") {
- const { isGlobeLikeHotkey } = require("./src/helpers/hotkeyManager");
+ const { isGlobeLikeHotkey, isMouseButtonHotkey } = require("./src/helpers/hotkeyManager");
let globeKeyDownTime = 0;
let globeKeyIsRecording = false;
let globeLastStopTime = 0;
@@ -1094,7 +1094,89 @@ async function startApp() {
}
});
+ const syncSuppressedMouseButtons = () => {
+ const buttons = [];
+ const currentHotkey = hotkeyManager.getCurrentHotkey && hotkeyManager.getCurrentHotkey();
+ if (isMouseButtonHotkey(currentHotkey)) buttons.push(currentHotkey);
+
+ const agentHotkey = hotkeyManager.getSlotHotkey("agent");
+ if (isMouseButtonHotkey(agentHotkey)) buttons.push(agentHotkey);
+
+ globeKeyManager.setSuppressedMouseButtons(buttons);
+ };
+
+ // Mouse Button 4/5 handling (e.g., Logitech MX Master side buttons)
+ let mouseButtonDownTime = 0;
+ let mouseButtonIsRecording = false;
+ let mouseButtonLastStopTime = 0;
+
+ globeKeyManager.on("mouse-button-down", async (button) => {
+ if (hotkeyManager.isInListeningMode && hotkeyManager.isInListeningMode()) return;
+ if (!isMouseButtonHotkey(button)) return;
+
+ const currentHotkey = hotkeyManager.getCurrentHotkey && hotkeyManager.getCurrentHotkey();
+ const agentHotkey = hotkeyManager.getSlotHotkey("agent");
+
+ if (agentHotkey === button) {
+ windowManager.toggleAgentOverlay();
+ }
+
+ if (currentHotkey !== button) return;
+ if (!isLiveWindow(windowManager.mainWindow)) return;
+
+ const activationMode = windowManager.getActivationMode();
+ if (textEditMonitor) textEditMonitor.captureTargetPid();
+
+ if (activationMode === "push") {
+ const now = Date.now();
+ if (now - mouseButtonLastStopTime < POST_STOP_COOLDOWN_MS) return;
+ windowManager.showDictationPanel();
+ const pressTime = now;
+ mouseButtonDownTime = pressTime;
+ mouseButtonIsRecording = false;
+ setTimeout(() => {
+ if (mouseButtonDownTime === pressTime && !mouseButtonIsRecording) {
+ mouseButtonIsRecording = true;
+ windowManager.sendStartDictation();
+ }
+ }, MIN_HOLD_DURATION_MS);
+ } else {
+ windowManager.sendToggleDictation();
+ }
+ });
+
+ globeKeyManager.on("mouse-button-up", async (button) => {
+ if (hotkeyManager.isInListeningMode && hotkeyManager.isInListeningMode()) return;
+ if (!isMouseButtonHotkey(button)) return;
+
+ const currentHotkey = hotkeyManager.getCurrentHotkey && hotkeyManager.getCurrentHotkey();
+ if (currentHotkey !== button) return;
+ if (!isLiveWindow(windowManager.mainWindow)) return;
+
+ const activationMode = windowManager.getActivationMode();
+ if (activationMode === "push") {
+ mouseButtonDownTime = 0;
+ mouseButtonLastStopTime = Date.now();
+ if (mouseButtonIsRecording) {
+ mouseButtonIsRecording = false;
+ windowManager.sendStopDictation();
+ } else {
+ windowManager.hideDictationPanel();
+ }
+ }
+ });
+
+ syncSuppressedMouseButtons();
globeKeyManager.start();
+ hotkeyManager.once("hotkey-loaded", syncSuppressedMouseButtons);
+
+ ipcMain.on("hotkey-listening-mode-changed", (_event, enabled) => {
+ if (enabled) {
+ globeKeyManager.setSuppressedMouseButtons([]);
+ } else {
+ syncSuppressedMouseButtons();
+ }
+ });
// After starting globe-listener, check if accessibility is granted.
// If not, notify the control panel so it can prompt the user.
@@ -1128,6 +1210,10 @@ async function startApp() {
rightModDownTime = 0;
rightModIsRecording = false;
rightModLastStopTime = 0;
+ mouseButtonDownTime = 0;
+ mouseButtonIsRecording = false;
+ mouseButtonLastStopTime = 0;
+ syncSuppressedMouseButtons();
});
}
diff --git a/resources/macos-globe-listener.swift b/resources/macos-globe-listener.swift
index f103d1d5b..7b32a6f26 100644
--- a/resources/macos-globe-listener.swift
+++ b/resources/macos-globe-listener.swift
@@ -4,6 +4,13 @@ import Darwin
var fnIsDown = false
var lastModifierFlags: NSEvent.ModifierFlags = []
+let suppressedMouseButtons = Set(
+ CommandLine.arguments.dropFirst()
+ .flatMap { $0.split(separator: ",") }
+ .map { String($0).trimmingCharacters(in: .whitespacesAndNewlines) }
+ .filter { !$0.isEmpty }
+)
+
let rightModifiers: [(UInt16, NSEvent.ModifierFlags, String)] = [
(61, .option, "RightOption"),
(54, .command, "RightCommand"),
@@ -25,6 +32,65 @@ func emit(_ message: String) {
fflush(stdout)
}
+func mouseButtonName(_ buttonNumber: Int) -> String? {
+ switch buttonNumber {
+ case 3:
+ return "MouseButton4"
+ case 4:
+ return "MouseButton5"
+ default:
+ return nil
+ }
+}
+
+func emitMouseEvent(_ type: CGEventType, _ event: CGEvent) -> Bool {
+ guard type == .otherMouseDown || type == .otherMouseUp else { return false }
+
+ let buttonNumber = Int(event.getIntegerValueField(.mouseEventButtonNumber))
+ guard let buttonName = mouseButtonName(buttonNumber) else { return false }
+
+ emit(type == .otherMouseDown ? "MOUSE_BUTTON_DOWN:\(buttonName)" : "MOUSE_BUTTON_UP:\(buttonName)")
+ return suppressedMouseButtons.contains(buttonName)
+}
+
+let mouseEventMask =
+ (1 << CGEventType.otherMouseDown.rawValue) |
+ (1 << CGEventType.otherMouseUp.rawValue)
+
+var mouseEventTapPort: CFMachPort?
+
+let mouseEventTap = CGEvent.tapCreate(
+ tap: .cgSessionEventTap,
+ place: .headInsertEventTap,
+ options: .defaultTap,
+ eventsOfInterest: CGEventMask(mouseEventMask),
+ callback: { _, type, event, _ in
+ if type == .tapDisabledByTimeout || type == .tapDisabledByUserInput {
+ if let mouseEventTapPort {
+ CGEvent.tapEnable(tap: mouseEventTapPort, enable: true)
+ }
+ return Unmanaged.passUnretained(event)
+ }
+
+ if emitMouseEvent(type, event) {
+ return nil
+ }
+
+ return Unmanaged.passUnretained(event)
+ },
+ userInfo: nil
+)
+
+var mouseRunLoopSource: CFRunLoopSource?
+if let mouseEventTap {
+ mouseEventTapPort = mouseEventTap
+ mouseRunLoopSource = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, mouseEventTap, 0)
+ CFRunLoopAddSource(CFRunLoopGetMain(), mouseRunLoopSource, .commonModes)
+ CGEvent.tapEnable(tap: mouseEventTap, enable: true)
+} else {
+ FileHandle.standardError.write("Failed to create mouse event tap\n".data(using: .utf8)!)
+}
+
guard let monitor = NSEvent.addGlobalMonitorForEvents(matching: .flagsChanged, handler: { event in
let flags = event.modifierFlags
let containsFn = flags.contains(.function)
@@ -64,6 +130,12 @@ let signalSource = DispatchSource.makeSignalSource(signal: SIGTERM, queue: .main
signal(SIGTERM, SIG_IGN)
signalSource.setEventHandler {
NSEvent.removeMonitor(monitor)
+ if let mouseEventTap {
+ CGEvent.tapEnable(tap: mouseEventTap, enable: false)
+ }
+ if let mouseRunLoopSource {
+ CFRunLoopRemoveSource(CFRunLoopGetMain(), mouseRunLoopSource, .commonModes)
+ }
exit(0)
}
signalSource.resume()
diff --git a/src/components/ui/HotkeyInput.tsx b/src/components/ui/HotkeyInput.tsx
index 69d2b065c..19461cfc2 100644
--- a/src/components/ui/HotkeyInput.tsx
+++ b/src/components/ui/HotkeyInput.tsx
@@ -396,6 +396,20 @@ export function HotkeyInput({
[disabled, buildModifierOnlyHotkey, finalizeCapture]
);
+ const handleMouseDown = useCallback(
+ (e: React.MouseEvent<HTMLDivElement>) => {
+ if (disabled || !isCapturing) return;
+
+ const mouseHotkey = e.button === 3 ? "MouseButton4" : e.button === 4 ? "MouseButton5" : null;
+ if (!mouseHotkey) return;
+
+ e.preventDefault();
+ e.stopPropagation();
+ finalizeCapture(mouseHotkey);
+ },
+ [disabled, isCapturing, finalizeCapture]
+ );
+
const handleFocus = useCallback(() => {
if (!disabled) {
setIsCapturing(true);
@@ -469,6 +483,7 @@ export function HotkeyInput({
data-capturing={isCapturing || undefined}
onKeyDown={handleKeyDown}
onKeyUp={handleKeyUp}
+ onMouseDown={handleMouseDown}
onFocus={handleFocus}
onBlur={handleBlur}
className={`
@@ -573,6 +588,7 @@ export function HotkeyInput({
data-capturing={isCapturing || undefined}
onKeyDown={handleKeyDown}
onKeyUp={handleKeyUp}
+ onMouseDown={handleMouseDown}
onFocus={handleFocus}
onBlur={handleBlur}
className={`
diff --git a/src/helpers/globeKeyManager.js b/src/helpers/globeKeyManager.js
index 997a2487d..871e32cc2 100644
--- a/src/helpers/globeKeyManager.js
+++ b/src/helpers/globeKeyManager.js
@@ -26,6 +26,25 @@ class GlobeKeyManager extends EventEmitter {
this._isStopping = false;
this._restartCount = 0;
this._restartResetTimer = null;
+ this.suppressedMouseButtons = [];
+ }
+
+ setSuppressedMouseButtons(buttons = []) {
+ const normalized = [...new Set(buttons.filter((button) => /^MouseButton[45]$/i.test(button)))];
+ const unchanged =
+ normalized.length === this.suppressedMouseButtons.length &&
+ normalized.every((button, index) => button === this.suppressedMouseButtons[index]);
+
+ if (unchanged) {
+ return;
+ }
+
+ this.suppressedMouseButtons = normalized;
+
+ if (this.process) {
+ this.stop();
+ this.start();
+ }
}
start() {
@@ -75,8 +94,12 @@ class GlobeKeyManager extends EventEmitter {
}
this.hasReportedError = false;
- this.process = spawn(listenerPath);
- debugLogger.info("[GlobeKeyManager] Process spawned", { pid: this.process.pid });
+ const child = spawn(listenerPath, this.suppressedMouseButtons);
+ this.process = child;
+ debugLogger.info("[GlobeKeyManager] Process spawned", {
+ pid: child.pid,
+ suppressedMouseButtons: this.suppressedMouseButtons,
+ });
// After sustained uptime, reset the restart counter so future sleep/wake
// cycles get a fresh set of restart attempts
@@ -89,8 +112,8 @@ class GlobeKeyManager extends EventEmitter {
}
}, RESTART_RESET_MS);
- this.process.stdout.setEncoding("utf8");
- this.process.stdout.on("data", (chunk) => {
+ child.stdout.setEncoding("utf8");
+ child.stdout.on("data", (chunk) => {
chunk
.split(/\r?\n/)
.map((line) => line.trim())
@@ -115,12 +138,22 @@ class GlobeKeyManager extends EventEmitter {
if (modifier) {
this.emit("modifier-up", modifier);
}
+ } else if (line.startsWith("MOUSE_BUTTON_DOWN:")) {
+ const button = line.replace("MOUSE_BUTTON_DOWN:", "").trim();
+ if (button) {
+ this.emit("mouse-button-down", button);
+ }
+ } else if (line.startsWith("MOUSE_BUTTON_UP:")) {
+ const button = line.replace("MOUSE_BUTTON_UP:", "").trim();
+ if (button) {
+ this.emit("mouse-button-up", button);
+ }
}
});
});
- this.process.stderr.setEncoding("utf8");
- this.process.stderr.on("data", (data) => {
+ child.stderr.setEncoding("utf8");
+ child.stderr.on("data", (data) => {
const message = data.toString().trim();
if (message.length > 0) {
if (message.includes("Failed to create event monitor")) {
@@ -131,14 +164,19 @@ class GlobeKeyManager extends EventEmitter {
}
});
- this.process.on("error", (error) => {
+ child.on("error", (error) => {
debugLogger.info("[GlobeKeyManager] Process error", { error: error.message });
this.reportError(error);
- this.process = null;
+ if (this.process === child) this.process = null;
});
- this.process.on("exit", (code, signal) => {
+ child.on("exit", (code, signal) => {
debugLogger.info("[GlobeKeyManager] Process exited", { code, signal });
+ // Only clear instance state if this is still the current process — a prior
+ // stop()+start() (e.g. setSuppressedMouseButtons) may have already replaced it.
+ if (this.process !== child) {
+ return;
+ }
this.process = null;
if (this._restartResetTimer) {
clearTimeout(this._restartResetTimer);
diff --git a/src/helpers/hotkeyManager.js b/src/helpers/hotkeyManager.js
index c6ba4febf..c7d9bda17 100644
--- a/src/helpers/hotkeyManager.js
+++ b/src/helpers/hotkeyManager.js
@@ -1,3 +1,4 @@
+const EventEmitter = require("events");
const { globalShortcut, BrowserWindow } = require("electron");
const debugLogger = require("./debugLogger");
const GnomeShortcutManager = require("./gnomeShortcut");
@@ -58,6 +59,10 @@ function isGlobeLikeHotkey(hotkey) {
return hotkey === "GLOBE" || hotkey === "Fn";
}
+function isMouseButtonHotkey(hotkey) {
+ return /^MouseButton[45]$/i.test(hotkey || "");
+}
+
function normalizeToAccelerator(hotkey) {
let accelerator = hotkey.startsWith("Fn+") ? hotkey.slice(3) : hotkey;
accelerator = accelerator
@@ -74,8 +79,9 @@ const SUGGESTED_HOTKEYS = {
compound: ["Control+Super", "Control+Alt", "Control+Shift+Space", "Alt+F7"],
};
-class HotkeyManager {
+class HotkeyManager extends EventEmitter {
constructor() {
+ super();
this.slots = new Map();
const defaultDictation = process.platform === "darwin" ? "GLOBE" : "Control+Super";
this.slots.set("dictation", { hotkey: defaultDictation, callback: null, accelerator: null });
@@ -276,7 +282,12 @@ class HotkeyManager {
}
const hk = slot.hotkey;
- if (!isGlobeLikeHotkey(hk) && !isRightSideModifier(hk) && !isModifierOnlyHotkey(hk)) {
+ if (
+ !isGlobeLikeHotkey(hk) &&
+ !isMouseButtonHotkey(hk) &&
+ !isRightSideModifier(hk) &&
+ !isModifierOnlyHotkey(hk)
+ ) {
const accel = normalizeToAccelerator(hk);
try {
globalShortcut.unregister(accel);
@@ -308,6 +319,7 @@ class HotkeyManager {
if (
hotkey === slot.hotkey &&
!isGlobeLikeHotkey(hotkey) &&
+ !isMouseButtonHotkey(hotkey) &&
!isRightSideModifier(hotkey) &&
!isModifierOnlyHotkey(hotkey) &&
globalShortcut.isRegistered(checkAccelerator)
@@ -324,6 +336,7 @@ class HotkeyManager {
if (
previousHotkey &&
!isGlobeLikeHotkey(previousHotkey) &&
+ !isMouseButtonHotkey(previousHotkey) &&
!isRightSideModifier(previousHotkey) &&
!isModifierOnlyHotkey(previousHotkey)
) {
@@ -342,6 +355,21 @@ class HotkeyManager {
const conflict = this._findSlotConflict(slotName, hotkey);
if (conflict) return conflict;
+ if (isMouseButtonHotkey(hotkey)) {
+ if (process.platform !== "darwin") {
+ return {
+ success: false,
+ error: i18nMain.t("hotkey.errors.mouseButtonOnlyMac"),
+ };
+ }
+ slot.hotkey = hotkey;
+ slot.accelerator = null;
+ debugLogger.log(
+ `[HotkeyManager] Mouse button "${hotkey}" set - using macOS native listener`
+ );
+ return { success: true, hotkey };
+ }
+
if (isGlobeLikeHotkey(hotkey)) {
if (process.platform !== "darwin") {
debugLogger.log("[HotkeyManager] GLOBE key rejected - not on macOS");
@@ -424,7 +452,10 @@ class HotkeyManager {
_findSlotConflict(slotName, hotkey) {
const accelerator =
- isGlobeLikeHotkey(hotkey) || isRightSideModifier(hotkey) || isModifierOnlyHotkey(hotkey)
+ isGlobeLikeHotkey(hotkey) ||
+ isMouseButtonHotkey(hotkey) ||
+ isRightSideModifier(hotkey) ||
+ isModifierOnlyHotkey(hotkey)
? null
: normalizeToAccelerator(hotkey);
@@ -454,6 +485,7 @@ class HotkeyManager {
if (
!previousHotkey ||
isGlobeLikeHotkey(previousHotkey) ||
+ isMouseButtonHotkey(previousHotkey) ||
isRightSideModifier(previousHotkey) ||
isModifierOnlyHotkey(previousHotkey)
) {
@@ -815,6 +847,8 @@ class HotkeyManager {
this.notifyHotkeyFailure(defaultHotkey, result);
} catch (err) {
debugLogger.error("Failed to initialize hotkey", { error: err.message }, "hotkey");
+ } finally {
+ this.emit("hotkey-loaded", this.currentHotkey);
}
}
@@ -976,6 +1010,20 @@ class HotkeyManager {
return { success: false, message: conflict.error, reason: conflict.reason };
}
+ if (isMouseButtonHotkey(hotkey)) {
+ const result = this.setupShortcuts(hotkey, callback);
+ if (result.success) {
+ const saved = await this.saveHotkeyToRenderer(hotkey);
+ if (!saved) {
+ debugLogger.warn(
+ "[HotkeyManager] Mouse button hotkey set but failed to persist to localStorage"
+ );
+ }
+ return { success: true, message: `Hotkey updated to: ${hotkey}` };
+ }
+ return { success: false, message: result.error };
+ }
+
if (this.useGnome && this.gnomeManager) {
debugLogger.log(`[HotkeyManager] Updating GNOME hotkey to "${hotkey}"`);
const gnomeHotkey = GnomeShortcutManager.convertToGnomeFormat(hotkey);
@@ -1157,3 +1205,4 @@ module.exports = HotkeyManager;
module.exports.isGlobeLikeHotkey = isGlobeLikeHotkey;
module.exports.isModifierOnlyHotkey = isModifierOnlyHotkey;
module.exports.isRightSideModifier = isRightSideModifier;
+module.exports.isMouseButtonHotkey = isMouseButtonHotkey;
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.js
index 25e12d84c..8cdd69e0c 100644
--- a/src/helpers/ipcHandlers.js
+++ b/src/helpers/ipcHandlers.js
@@ -2093,6 +2093,7 @@ class IPCHandlers {
if (this._hotkeyCaptureMode === enabled) return { success: true, skipped: true };
this._hotkeyCaptureMode = enabled;
this.windowManager.setHotkeyListeningMode(enabled);
+ ipcMain.emit("hotkey-listening-mode-changed", null, enabled);
const hotkeyManager = this.windowManager.hotkeyManager;
// When exiting capture mode with a new hotkey, use that to avoid reading stale state
@@ -2102,10 +2103,12 @@ class IPCHandlers {
isGlobeLikeHotkey,
isModifierOnlyHotkey,
isRightSideModifier,
+ isMouseButtonHotkey,
} = require("./hotkeyManager");
const usesNativeListener = (hotkey) =>
!hotkey ||
isGlobeLikeHotkey(hotkey) ||
+ isMouseButtonHotkey(hotkey) ||
isModifierOnlyHotkey(hotkey) ||
isRightSideModifier(hotkey);
diff --git a/src/locales/de/translation.json b/src/locales/de/translation.json
index d0a2482be..e81abc505 100644
--- a/src/locales/de/translation.json
+++ b/src/locales/de/translation.json
@@ -87,6 +87,7 @@
"errors": {
"callbackRequired": "Eine Callback-Funktion ist für das Hotkey-Setup erforderlich",
"globeOnlyMac": "Die Globe-Taste ist nur auf macOS verfügbar.",
+ "mouseButtonOnlyMac": "Maustasten-Hotkeys werden derzeit nur auf macOS unterstützt.",
"alreadyRegistered": "\"{{hotkey}}\" ist bereits von einer anderen Anwendung registriert.",
"osReserved": "\"{{hotkey}}\" ist möglicherweise von Ihrer Desktop-Umgebung reserviert.",
"registrationFailed": "\"{{hotkey}}\" konnte nicht registriert werden. Möglicherweise wird es von einer anderen Anwendung verwendet.",
diff --git a/src/locales/en/translation.json b/src/locales/en/translation.json
index ddbab00f9..a58aacc76 100644
--- a/src/locales/en/translation.json
+++ b/src/locales/en/translation.json
@@ -87,6 +87,7 @@
"errors": {
"callbackRequired": "Callback function is required for hotkey setup",
"globeOnlyMac": "The Globe key is only available on macOS.",
+ "mouseButtonOnlyMac": "Mouse button hotkeys are currently supported on macOS only.",
"alreadyRegistered": "\"{{hotkey}}\" is already registered by another application.",
"osReserved": "\"{{hotkey}}\" may be reserved by your desktop environment.",
"registrationFailed": "Could not register \"{{hotkey}}\". It may be in use by another application.",
diff --git a/src/locales/es/translation.json b/src/locales/es/translation.json
index de16ac702..4c529163d 100644
--- a/src/locales/es/translation.json
+++ b/src/locales/es/translation.json
@@ -87,6 +87,7 @@
"errors": {
"callbackRequired": "Se requiere una función callback para configurar el atajo",
"globeOnlyMac": "La tecla Globe solo está disponible en macOS.",
+ "mouseButtonOnlyMac": "Los atajos con botones del ratón solo son compatibles con macOS por ahora.",
"alreadyRegistered": "\"{{hotkey}}\" ya está registrada por otra aplicación.",
"osReserved": "\"{{hotkey}}\" puede estar reservada por tu entorno de escritorio.",
"registrationFailed": "No se pudo registrar \"{{hotkey}}\". Puede estar en uso por otra aplicación.",
diff --git a/src/locales/fr/translation.json b/src/locales/fr/translation.json
index edc3684bd..d14c4eb8a 100644
--- a/src/locales/fr/translation.json
+++ b/src/locales/fr/translation.json
@@ -87,6 +87,7 @@
"errors": {
"callbackRequired": "Une fonction callback est requise pour configurer le raccourci",
"globeOnlyMac": "La touche Globe est disponible uniquement sur macOS.",
+ "mouseButtonOnlyMac": "Les raccourcis avec les boutons de la souris ne sont actuellement pris en charge que sur macOS.",
"alreadyRegistered": "\"{{hotkey}}\" est déjà enregistré par une autre application.",
"osReserved": "\"{{hotkey}}\" peut être réservé par votre environnement de bureau.",
"registrationFailed": "Impossible d'enregistrer \"{{hotkey}}\". Il est peut-être utilisé par une autre application.",
diff --git a/src/locales/it/translation.json b/src/locales/it/translation.json
index 2d6b7e0c7..cbfede877 100644
--- a/src/locales/it/translation.json
+++ b/src/locales/it/translation.json
@@ -87,6 +87,7 @@
"errors": {
"callbackRequired": "È necessaria una funzione callback per configurare la scorciatoia",
"globeOnlyMac": "Il tasto Globe è disponibile solo su macOS.",
+ "mouseButtonOnlyMac": "Le scorciatoie con i tasti del mouse sono attualmente supportate solo su macOS.",
"alreadyRegistered": "\"{{hotkey}}\" è già registrata da un'altra applicazione.",
"osReserved": "\"{{hotkey}}\" potrebbe essere riservata dal sistema operativo.",
"registrationFailed": "Impossibile registrare \"{{hotkey}}\". Potrebbe essere in uso da un'altra applicazione.",
diff --git a/src/locales/ja/translation.json b/src/locales/ja/translation.json
index c6e0acabe..5b237fd3d 100644
--- a/src/locales/ja/translation.json
+++ b/src/locales/ja/translation.json
@@ -87,6 +87,7 @@
"errors": {
"callbackRequired": "ホットキー設定にはコールバック関数が必要です",
"globeOnlyMac": "Globe キーは macOS でのみ利用できます。",
+ "mouseButtonOnlyMac": "マウスボタンのホットキーは現在 macOS でのみサポートされています。",
"alreadyRegistered": "\"{{hotkey}}\" は別のアプリケーションで既に登録されています。",
"osReserved": "\"{{hotkey}}\" はデスクトップ環境で予約されている可能性があります。",
"registrationFailed": "\"{{hotkey}}\" を登録できませんでした。別のアプリケーションで使用されている可能性があります。",
diff --git a/src/locales/pt/translation.json b/src/locales/pt/translation.json
index 306fdb1fe..94f4a767b 100644
--- a/src/locales/pt/translation.json
+++ b/src/locales/pt/translation.json
@@ -87,6 +87,7 @@
"errors": {
"callbackRequired": "Uma função de callback é obrigatória para configurar o atalho",
"globeOnlyMac": "A tecla Globe está disponível apenas no macOS.",
+ "mouseButtonOnlyMac": "Atalhos com botões do mouse atualmente são compatíveis apenas no macOS.",
"alreadyRegistered": "\"{{hotkey}}\" já está registrada por outro aplicativo.",
"osReserved": "\"{{hotkey}}\" pode estar reservada pelo seu ambiente de desktop.",
"registrationFailed": "Não foi possível registrar \"{{hotkey}}\". Pode estar em uso por outro aplicativo.",
diff --git a/src/locales/ru/translation.json b/src/locales/ru/translation.json
index d2031431f..06ecd30b6 100644
--- a/src/locales/ru/translation.json
+++ b/src/locales/ru/translation.json
@@ -87,6 +87,7 @@
"errors": {
"callbackRequired": "Для настройки горячей клавиши необходима функция обратного вызова",
"globeOnlyMac": "Клавиша Globe доступна только на macOS.",
+ "mouseButtonOnlyMac": "Горячие клавиши на кнопках мыши в настоящее время поддерживаются только на macOS.",
"alreadyRegistered": "«{{hotkey}}» уже зарегистрирована другим приложением.",
"osReserved": "«{{hotkey}}» может быть зарезервирована вашей операционной системой.",
"registrationFailed": "Не удалось зарегистрировать «{{hotkey}}». Возможно, она используется другим приложением.",
diff --git a/src/locales/zh-CN/translation.json b/src/locales/zh-CN/translation.json
index b17b8d986..cf24c0f9e 100644
--- a/src/locales/zh-CN/translation.json
+++ b/src/locales/zh-CN/translation.json
@@ -87,6 +87,7 @@
"errors": {
"callbackRequired": "设置快捷键需要回调函数",
"globeOnlyMac": "Globe 键仅在 macOS 上可用。",
+ "mouseButtonOnlyMac": "鼠标按键快捷键目前仅在 macOS 上受支持。",
"alreadyRegistered": "\"{{hotkey}}\" 已被其他应用注册。",
"osReserved": "\"{{hotkey}}\" 可能被系统保留。",
"registrationFailed": "无法注册 \"{{hotkey}}\",该快捷键可能已被其他应用占用。",
diff --git a/src/locales/zh-TW/translation.json b/src/locales/zh-TW/translation.json
index d07d5ce7c..abee22d57 100644
--- a/src/locales/zh-TW/translation.json
+++ b/src/locales/zh-TW/translation.json
@@ -87,6 +87,7 @@
"errors": {
"callbackRequired": "設定快捷鍵需要回呼函式",
"globeOnlyMac": "Globe 鍵僅在 macOS 上可用。",
+ "mouseButtonOnlyMac": "滑鼠按鍵快捷鍵目前僅在 macOS 上受支援。",
"alreadyRegistered": "\"{{hotkey}}\" 已被其他應用程式註冊。",
"osReserved": "\"{{hotkey}}\" 可能被你的作業系統保留。",
"registrationFailed": "無法註冊「{{hotkey}}」。可能已被其他應用程式使用。",
diff --git a/src/utils/hotkeyValidator.ts b/src/utils/hotkeyValidator.ts
index 238596445..8daf31d65 100644
--- a/src/utils/hotkeyValidator.ts
+++ b/src/utils/hotkeyValidator.ts
@@ -1,4 +1,4 @@
-import { formatHotkeyLabelForPlatform, isGlobeLikeHotkey } from "./hotkeys";
+import { formatHotkeyLabelForPlatform, isGlobeLikeHotkey, isMouseButtonHotkey } from "./hotkeys";
export type Platform = "darwin" | "win32" | "linux";
@@ -374,6 +374,8 @@ function normalizeKeyToken(part: string): string {
if (lowered === "backspace") return "Backspace";
if (lowered === "globe") return "GLOBE";
if (lowered === "fn") return "Fn";
+ if (lowered === "mousebutton4") return "MouseButton4";
+ if (lowered === "mousebutton5") return "MouseButton5";
const functionMatch = lowered.match(/^f(\d{1,2})$/);
if (functionMatch) {
@@ -528,6 +530,25 @@ export function validateHotkey(
return { valid: true };
}
+ if (isMouseButtonHotkey(hotkey)) {
+ if (platform !== "darwin") {
+ return {
+ valid: false,
+ error: "Mouse button hotkeys are currently supported on macOS only.",
+ };
+ }
+ return { valid: true };
+ }
+
+ // Mouse buttons cannot be combined with keyboard modifiers — they're handled
+ // by a separate native event tap, not Electron's globalShortcut.
+ if (/mousebutton[45]/i.test(hotkey)) {
+ return {
+ valid: false,
+ error: "Mouse button hotkeys cannot be combined with other keys.",
+ };
+ }
+
const parts = hotkey
.split("+")
.map((part) => part.trim())
diff --git a/src/utils/hotkeys.ts b/src/utils/hotkeys.ts
index 7b869ce9b..d309ee190 100644
--- a/src/utils/hotkeys.ts
+++ b/src/utils/hotkeys.ts
@@ -9,6 +9,10 @@ export function isGlobeLikeHotkey(hotkey: string): boolean {
return hotkey === "GLOBE" || hotkey === "Fn";
}
+export function isMouseButtonHotkey(hotkey: string): boolean {
+ return /^MouseButton[45]$/i.test(hotkey || "");
+}
+
function formatModifierPart(part: string, platform: Platform): string {
switch (part) {
case "CommandOrControl":
@@ -64,6 +68,10 @@ export function formatHotkeyLabelForPlatform(hotkey: string, platform: Platform)
return "Globe/Fn";
}
+ if (isMouseButtonHotkey(hotkey)) {
+ return hotkey === "MouseButton4" ? "Mouse Button 4" : "Mouse Button 5";
+ }
+
// Right-side single modifiers
const rightSideMap: Record<string, string> = {
RightOption: platform === "darwin" ? "Right Option" : "Right Alt",
@@ -148,7 +156,7 @@ export function isValidHotkeyFormat(hotkey: string): boolean {
return false;
}
- if (isGlobeLikeHotkey(hotkey)) {
+ if (isGlobeLikeHotkey(hotkey) || isMouseButtonHotkey(hotkey)) {
return true;
}