🎨 Optimize hotkey service

internal/common/hotkey/hotkey.go

@@ -0,0 +1,181 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+// Package hotkey provides the basic facility to register a system-level
+// global hotkey shortcut so that an application can be notified if a user
+// triggers the desired hotkey. A hotkey must be a combination of modifiers
+// and a single key.
+//
+// Note platform specific details:
+//
+//   - On macOS, due to the OS restriction (other platforms does not have
+//     this restriction), hotkey events must be handled on the "main thread".
+//     Therefore, in order to use this package properly, one must start an
+//     OS main event loop on the main thread, For self-contained applications,
+//     using [mainthread] package.
+//     is possible. It is uncessary or applications based on other GUI frameworks,
+//     such as fyne, ebiten, or Gio. See the "[examples]" for more examples.
+//
+//   - On Linux (X11), when AutoRepeat is enabled in the X server, the
+//     Keyup is triggered automatically and continuously as Keydown continues.
+//
+//   - On Linux (X11), some keys may be mapped to multiple Mod keys. To
+//     correctly register the key combination, one must use the correct
+//     underlying keycode combination. For example, a regular Ctrl+Alt+S
+//     might be registered as: Ctrl+Mod2+Mod4+S.
+//
+//   - If this package did not include a desired key, one can always provide
+//     the keycode to the API. For example, if a key code is 0x15, then the
+//     corresponding key is `hotkey.Key(0x15)`.
+//
+// THe following is a minimum example:
+//
+//	package main
+//
+//	import (
+//		"log"
+//
+//		"golang.design/x/hotkey"
+//		"golang.design/x/hotkey/mainthread"
+//	)
+//
+//	func main() { mainthread.Init(fn) } // Not necessary when use in Fyne, Ebiten or Gio.
+//	func fn() {
+//		hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
+//		err := hk.Register()
+//		if err != nil {
+//			log.Fatalf("hotkey: failed to register hotkey: %v", err)
+//		}
+//
+//		log.Printf("hotkey: %v is registered\n", hk)
+//		<-hk.Keydown()
+//		log.Printf("hotkey: %v is down\n", hk)
+//		<-hk.Keyup()
+//		log.Printf("hotkey: %v is up\n", hk)
+//		hk.Unregister()
+//		log.Printf("hotkey: %v is unregistered\n", hk)
+//	}
+//
+// [mainthread]: https://pkg.go.dev/golang.design/x/hotkey/mainthread
+// [examples]: https://github.com/golang-design/hotkey/tree/main/examples
+package hotkey
+
+import (
+	"fmt"
+	"runtime"
+)
+
+// Event represents a hotkey event
+type Event struct{}
+
+// Hotkey is a combination of modifiers and key to trigger an event
+type Hotkey struct {
+	platformHotkey
+
+	mods []Modifier
+	key  Key
+
+	keydownIn  chan<- Event
+	keydownOut <-chan Event
+	keyupIn    chan<- Event
+	keyupOut   <-chan Event
+}
+
+// New creates a new hotkey for the given modifiers and keycode.
+func New(mods []Modifier, key Key) *Hotkey {
+	keydownIn, keydownOut := newEventChan()
+	keyupIn, keyupOut := newEventChan()
+	hk := &Hotkey{
+		mods:       mods,
+		key:        key,
+		keydownIn:  keydownIn,
+		keydownOut: keydownOut,
+		keyupIn:    keyupIn,
+		keyupOut:   keyupOut,
+	}
+
+	// Make sure the hotkey is unregistered when the created
+	// hotkey is garbage collected.
+	runtime.SetFinalizer(hk, func(x interface{}) {
+		hk := x.(*Hotkey)
+		hk.unregister()
+		close(hk.keydownIn)
+		close(hk.keyupIn)
+	})
+	return hk
+}
+
+// Register registers a combination of hotkeys. If the hotkey has
+// registered. This function will invalidates the old registration
+// and overwrites its callback.
+func (hk *Hotkey) Register() error { return hk.register() }
+
+// Keydown returns a channel that receives a signal when the hotkey is triggered.
+func (hk *Hotkey) Keydown() <-chan Event { return hk.keydownOut }
+
+// Keyup returns a channel that receives a signal when the hotkey is released.
+func (hk *Hotkey) Keyup() <-chan Event { return hk.keyupOut }
+
+// Unregister unregisters the hotkey.
+func (hk *Hotkey) Unregister() error {
+	err := hk.unregister()
+	if err != nil {
+		return err
+	}
+
+	// Reset a new event channel.
+	close(hk.keydownIn)
+	close(hk.keyupIn)
+	hk.keydownIn, hk.keydownOut = newEventChan()
+	hk.keyupIn, hk.keyupOut = newEventChan()
+	return nil
+}
+
+// String returns a string representation of the hotkey.
+func (hk *Hotkey) String() string {
+	s := fmt.Sprintf("%v", hk.key)
+	for _, mod := range hk.mods {
+		s += fmt.Sprintf("+%v", mod)
+	}
+	return s
+}
+
+// newEventChan returns a sender and a receiver of a buffered channel
+// with infinite capacity.
+func newEventChan() (chan<- Event, <-chan Event) {
+	in, out := make(chan Event), make(chan Event)
+
+	go func() {
+		var q []Event
+
+		for {
+			e, ok := <-in
+			if !ok {
+				close(out)
+				return
+			}
+			q = append(q, e)
+			for len(q) > 0 {
+				select {
+				case out <- q[0]:
+					q[0] = Event{}
+					q = q[1:]
+				case e, ok := <-in:
+					if ok {
+						q = append(q, e)
+						break
+					}
+					for _, e := range q {
+						out <- e
+					}
+					close(out)
+					return
+				}
+			}
+		}
+	}()
+	return in, out
+}

internal/common/hotkey/hotkey_darwin.go

@@ -0,0 +1,176 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build darwin
+
+package hotkey
+
+/*
+#cgo CFLAGS: -x objective-c
+#cgo LDFLAGS: -framework Cocoa -framework Carbon
+#include <stdint.h>
+#import <Cocoa/Cocoa.h>
+#import <Carbon/Carbon.h>
+
+extern void keydownCallback(uintptr_t handle);
+extern void keyupCallback(uintptr_t handle);
+int registerHotKey(int mod, int key, uintptr_t handle, EventHotKeyRef* ref);
+int unregisterHotKey(EventHotKeyRef ref);
+*/
+import "C"
+import (
+	"errors"
+	"runtime/cgo"
+	"sync"
+)
+
+// Hotkey is a combination of modifiers and key to trigger an event
+type platformHotkey struct {
+	mu         sync.Mutex
+	registered bool
+	hkref      C.EventHotKeyRef
+}
+
+func (hk *Hotkey) register() error {
+	hk.mu.Lock()
+	defer hk.mu.Unlock()
+	if hk.registered {
+		return errors.New("hotkey already registered")
+	}
+
+	// Note: we use handle number as hotkey id in the C side.
+	// A cgo handle could ran out of space, but since in hotkey purpose
+	// we won't have that much number of hotkeys. So this should be fine.
+
+	h := cgo.NewHandle(hk)
+	var mod Modifier
+	for _, m := range hk.mods {
+		mod += m
+	}
+
+	ret := C.registerHotKey(C.int(mod), C.int(hk.key), C.uintptr_t(h), &hk.hkref)
+	if ret == C.int(-1) {
+		return errors.New("failed to register the hotkey")
+	}
+
+	hk.registered = true
+	return nil
+}
+
+func (hk *Hotkey) unregister() error {
+	hk.mu.Lock()
+	defer hk.mu.Unlock()
+	if !hk.registered {
+		return errors.New("hotkey is not registered")
+	}
+
+	ret := C.unregisterHotKey(hk.hkref)
+	if ret == C.int(-1) {
+		return errors.New("failed to unregister the current hotkey")
+	}
+	hk.registered = false
+	return nil
+}
+
+//export keydownCallback
+func keydownCallback(h uintptr) {
+	hk := cgo.Handle(h).Value().(*Hotkey)
+	hk.keydownIn <- Event{}
+}
+
+//export keyupCallback
+func keyupCallback(h uintptr) {
+	hk := cgo.Handle(h).Value().(*Hotkey)
+	hk.keyupIn <- Event{}
+}
+
+// Modifier represents a modifier.
+// See: /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks/Carbon.framework/Versions/A/Frameworks/HIToolbox.framework/Versions/A/Headers/Events.h
+type Modifier uint32
+
+// All kinds of Modifiers
+const (
+	ModCtrl   Modifier = 0x1000
+	ModShift  Modifier = 0x200
+	ModOption Modifier = 0x800
+	ModCmd    Modifier = 0x100
+)
+
+// Key represents a key.
+// See: /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks/Carbon.framework/Versions/A/Frameworks/HIToolbox.framework/Versions/A/Headers/Events.h
+type Key uint8
+
+// All kinds of keys
+const (
+	KeySpace Key = 49
+	Key1     Key = 18
+	Key2     Key = 19
+	Key3     Key = 20
+	Key4     Key = 21
+	Key5     Key = 23
+	Key6     Key = 22
+	Key7     Key = 26
+	Key8     Key = 28
+	Key9     Key = 25
+	Key0     Key = 29
+	KeyA     Key = 0
+	KeyB     Key = 11
+	KeyC     Key = 8
+	KeyD     Key = 2
+	KeyE     Key = 14
+	KeyF     Key = 3
+	KeyG     Key = 5
+	KeyH     Key = 4
+	KeyI     Key = 34
+	KeyJ     Key = 38
+	KeyK     Key = 40
+	KeyL     Key = 37
+	KeyM     Key = 46
+	KeyN     Key = 45
+	KeyO     Key = 31
+	KeyP     Key = 35
+	KeyQ     Key = 12
+	KeyR     Key = 15
+	KeyS     Key = 1
+	KeyT     Key = 17
+	KeyU     Key = 32
+	KeyV     Key = 9
+	KeyW     Key = 13
+	KeyX     Key = 7
+	KeyY     Key = 16
+	KeyZ     Key = 6
+
+	KeyReturn Key = 0x24
+	KeyEscape Key = 0x35
+	KeyDelete Key = 0x33
+	KeyTab    Key = 0x30
+
+	KeyLeft  Key = 0x7B
+	KeyRight Key = 0x7C
+	KeyUp    Key = 0x7E
+	KeyDown  Key = 0x7D
+
+	KeyF1  Key = 0x7A
+	KeyF2  Key = 0x78
+	KeyF3  Key = 0x63
+	KeyF4  Key = 0x76
+	KeyF5  Key = 0x60
+	KeyF6  Key = 0x61
+	KeyF7  Key = 0x62
+	KeyF8  Key = 0x64
+	KeyF9  Key = 0x65
+	KeyF10 Key = 0x6D
+	KeyF11 Key = 0x67
+	KeyF12 Key = 0x6F
+	KeyF13 Key = 0x69
+	KeyF14 Key = 0x6B
+	KeyF15 Key = 0x71
+	KeyF16 Key = 0x6A
+	KeyF17 Key = 0x40
+	KeyF18 Key = 0x4F
+	KeyF19 Key = 0x50
+	KeyF20 Key = 0x5A
+)

internal/common/hotkey/hotkey_darwin.m

@@ -0,0 +1,65 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build darwin
+
+#include <stdint.h>
+#import <Cocoa/Cocoa.h>
+#import <Carbon/Carbon.h>
+extern void keydownCallback(uintptr_t handle);
+extern void keyupCallback(uintptr_t handle);
+
+static OSStatus
+keydownHandler(EventHandlerCallRef nextHandler, EventRef theEvent, void *userData) {
+	EventHotKeyID k;
+	GetEventParameter(theEvent, kEventParamDirectObject, typeEventHotKeyID, NULL, sizeof(k), NULL, &k);
+	keydownCallback((uintptr_t)k.id); // use id as handle
+	return noErr;
+}
+
+static OSStatus
+keyupHandler(EventHandlerCallRef nextHandler, EventRef theEvent, void *userData) {
+	EventHotKeyID k;
+	GetEventParameter(theEvent, kEventParamDirectObject, typeEventHotKeyID, NULL, sizeof(k), NULL, &k);
+	keyupCallback((uintptr_t)k.id); // use id as handle
+	return noErr;
+}
+
+// registerHotkeyWithCallback registers a global system hotkey for callbacks.
+int registerHotKey(int mod, int key, uintptr_t handle, EventHotKeyRef* ref) {
+	__block OSStatus s;
+	dispatch_sync(dispatch_get_main_queue(), ^{
+		EventTypeSpec keydownEvent;
+		keydownEvent.eventClass = kEventClassKeyboard;
+		keydownEvent.eventKind = kEventHotKeyPressed;
+		EventTypeSpec keyupEvent;
+		keyupEvent.eventClass = kEventClassKeyboard;
+		keyupEvent.eventKind = kEventHotKeyReleased;
+		InstallApplicationEventHandler(
+			&keydownHandler, 1, &keydownEvent, NULL, NULL
+		);
+		InstallApplicationEventHandler(
+			&keyupHandler, 1, &keyupEvent, NULL, NULL
+		);
+
+		EventHotKeyID hkid = {.id = handle};
+		s = RegisterEventHotKey(
+			key, mod, hkid, GetApplicationEventTarget(), 0, ref
+		);
+	});
+	if (s != noErr) {
+		return -1;
+	}
+	return 0;
+}
+
+int unregisterHotKey(EventHotKeyRef ref) {
+	OSStatus s = UnregisterEventHotKey(ref);
+	if (s != noErr) {
+		return -1;
+	}
+	return 0;
+}

internal/common/hotkey/hotkey_darwin_test.go

@@ -0,0 +1,67 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build darwin && cgo
+
+package hotkey_test
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+	"voidraft/internal/common/hotkey"
+)
+
+// TestHotkey should always run success.
+// This is a test to run and for manually testing the registration of multiple
+// hotkeys. Registered hotkeys:
+// Ctrl+Shift+S
+// Ctrl+Option+S
+func TestHotkey(t *testing.T) {
+	tt := time.Second * 5
+	done := make(chan struct{}, 2)
+	ctx, cancel := context.WithTimeout(context.Background(), tt)
+	go func() {
+		hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
+		if err := hk.Register(); err != nil {
+			t.Errorf("failed to register hotkey: %v", err)
+			return
+		}
+		for {
+			select {
+			case <-ctx.Done():
+				cancel()
+				done <- struct{}{}
+				return
+			case <-hk.Keydown():
+				fmt.Println("triggered ctrl+shift+s")
+			}
+		}
+	}()
+
+	go func() {
+		hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModOption}, hotkey.KeyS)
+		if err := hk.Register(); err != nil {
+			t.Errorf("failed to register hotkey: %v", err)
+			return
+		}
+
+		for {
+			select {
+			case <-ctx.Done():
+				cancel()
+				done <- struct{}{}
+				return
+			case <-hk.Keydown():
+				fmt.Println("triggered ctrl+option+s")
+			}
+		}
+	}()
+
+	<-done
+	<-done
+}

internal/common/hotkey/hotkey_linux.c

@@ -0,0 +1,77 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build linux
+
+#include <stdint.h>
+#include <stdio.h>
+#include <X11/Xlib.h>
+#include <X11/Xutil.h>
+
+extern void hotkeyDown(uintptr_t hkhandle);
+extern void hotkeyUp(uintptr_t hkhandle);
+
+int displayTest() {
+	Display* d = NULL;
+	for (int i = 0; i < 42; i++) {
+		d = XOpenDisplay(0);
+		if (d == NULL) continue;
+		break;
+	}
+	if (d == NULL) {
+		return -1;
+	}
+	return 0;
+}
+
+// FIXME: handle bad access properly.
+// int handleErrors( Display* dpy, XErrorEvent* pErr )
+// {
+//     printf("X Error Handler called, values: %d/%lu/%d/%d/%d\n",
+//         pErr->type,
+//         pErr->serial,
+//         pErr->error_code,
+//         pErr->request_code,
+//         pErr->minor_code );
+//     if( pErr->request_code == 33 ){  // 33 (X_GrabKey)
+//         if( pErr->error_code == BadAccess ){
+//             printf("ERROR: key combination already grabbed by another client.\n");
+//             return 0;
+//         }
+//     }
+//     return 0;
+// }
+
+// waitHotkey blocks until the hotkey is triggered.
+// this function crashes the program if the hotkey already grabbed by others.
+int waitHotkey(uintptr_t hkhandle, unsigned int mod, int key) {
+	Display* d = NULL;
+	for (int i = 0; i < 42; i++) {
+		d = XOpenDisplay(0);
+		if (d == NULL) continue;
+		break;
+	}
+	if (d == NULL) {
+		return -1;
+	}
+	int keycode = XKeysymToKeycode(d, key);
+	XGrabKey(d, keycode, mod, DefaultRootWindow(d), False, GrabModeAsync, GrabModeAsync);
+	XSelectInput(d, DefaultRootWindow(d), KeyPressMask);
+	XEvent ev;
+	while(1) {
+		XNextEvent(d, &ev);
+		switch(ev.type) {
+		case KeyPress:
+			hotkeyDown(hkhandle);
+			continue;
+		case KeyRelease:
+			hotkeyUp(hkhandle);
+			XUngrabKey(d, keycode, mod, DefaultRootWindow(d));
+			XCloseDisplay(d);
+			return 0;
+		}
+	}
+}

internal/common/hotkey/hotkey_linux.go

@@ -0,0 +1,210 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build linux
+
+package hotkey
+
+/*
+#cgo LDFLAGS: -lX11
+
+#include <stdint.h>
+
+int displayTest();
+int waitHotkey(uintptr_t hkhandle, unsigned int mod, int key);
+*/
+import "C"
+import (
+	"context"
+	"errors"
+	"runtime"
+	"runtime/cgo"
+	"sync"
+)
+
+const errmsg = `Failed to initialize the X11 display, and the clipboard package
+will not work properly. Install the following dependency may help:
+
+	apt install -y libx11-dev
+If the clipboard package is in an environment without a frame buffer,
+such as a cloud server, it may also be necessary to install xvfb:
+	apt install -y xvfb
+and initialize a virtual frame buffer:
+	Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
+	export DISPLAY=:99.0
+Then this package should be ready to use.
+`
+
+func init() {
+	if C.displayTest() != 0 {
+		panic(errmsg)
+	}
+}
+
+type platformHotkey struct {
+	mu         sync.Mutex
+	registered bool
+	ctx        context.Context
+	cancel     context.CancelFunc
+	canceled   chan struct{}
+}
+
+// Nothing needs to do for register
+func (hk *Hotkey) register() error {
+	hk.mu.Lock()
+	if hk.registered {
+		hk.mu.Unlock()
+		return errors.New("hotkey already registered.")
+	}
+	hk.registered = true
+	hk.ctx, hk.cancel = context.WithCancel(context.Background())
+	hk.canceled = make(chan struct{})
+	hk.mu.Unlock()
+
+	go hk.handle()
+	return nil
+}
+
+// Nothing needs to do for unregister
+func (hk *Hotkey) unregister() error {
+	hk.mu.Lock()
+	defer hk.mu.Unlock()
+	if !hk.registered {
+		return errors.New("hotkey is not registered.")
+	}
+	hk.cancel()
+	hk.registered = false
+	<-hk.canceled
+	return nil
+}
+
+// handle registers an application global hotkey to the system,
+// and returns a channel that will signal if the hotkey is triggered.
+func (hk *Hotkey) handle() {
+	runtime.LockOSThread()
+	defer runtime.UnlockOSThread()
+	// KNOWN ISSUE: if a hotkey is grabbed by others, C side will crash the program
+
+	var mod Modifier
+	for _, m := range hk.mods {
+		mod = mod | m
+	}
+	h := cgo.NewHandle(hk)
+	defer h.Delete()
+
+	for {
+		select {
+		case <-hk.ctx.Done():
+			close(hk.canceled)
+			return
+		default:
+			_ = C.waitHotkey(C.uintptr_t(h), C.uint(mod), C.int(hk.key))
+		}
+	}
+}
+
+//export hotkeyDown
+func hotkeyDown(h uintptr) {
+	hk := cgo.Handle(h).Value().(*Hotkey)
+	hk.keydownIn <- Event{}
+}
+
+//export hotkeyUp
+func hotkeyUp(h uintptr) {
+	hk := cgo.Handle(h).Value().(*Hotkey)
+	hk.keyupIn <- Event{}
+}
+
+// Modifier represents a modifier.
+type Modifier uint32
+
+// All kinds of Modifiers
+// See /usr/include/X11/X.h
+const (
+	ModCtrl  Modifier = (1 << 2)
+	ModShift Modifier = (1 << 0)
+	Mod1     Modifier = (1 << 3)
+	Mod2     Modifier = (1 << 4)
+	Mod3     Modifier = (1 << 5)
+	Mod4     Modifier = (1 << 6)
+	Mod5     Modifier = (1 << 7)
+)
+
+// Key represents a key.
+// See /usr/include/X11/keysymdef.h
+type Key uint16
+
+// All kinds of keys
+const (
+	KeySpace Key = 0x0020
+	Key1     Key = 0x0030
+	Key2     Key = 0x0031
+	Key3     Key = 0x0032
+	Key4     Key = 0x0033
+	Key5     Key = 0x0034
+	Key6     Key = 0x0035
+	Key7     Key = 0x0036
+	Key8     Key = 0x0037
+	Key9     Key = 0x0038
+	Key0     Key = 0x0039
+	KeyA     Key = 0x0061
+	KeyB     Key = 0x0062
+	KeyC     Key = 0x0063
+	KeyD     Key = 0x0064
+	KeyE     Key = 0x0065
+	KeyF     Key = 0x0066
+	KeyG     Key = 0x0067
+	KeyH     Key = 0x0068
+	KeyI     Key = 0x0069
+	KeyJ     Key = 0x006a
+	KeyK     Key = 0x006b
+	KeyL     Key = 0x006c
+	KeyM     Key = 0x006d
+	KeyN     Key = 0x006e
+	KeyO     Key = 0x006f
+	KeyP     Key = 0x0070
+	KeyQ     Key = 0x0071
+	KeyR     Key = 0x0072
+	KeyS     Key = 0x0073
+	KeyT     Key = 0x0074
+	KeyU     Key = 0x0075
+	KeyV     Key = 0x0076
+	KeyW     Key = 0x0077
+	KeyX     Key = 0x0078
+	KeyY     Key = 0x0079
+	KeyZ     Key = 0x007a
+
+	KeyReturn Key = 0xff0d
+	KeyEscape Key = 0xff1b
+	KeyDelete Key = 0xffff
+	KeyTab    Key = 0xff1b
+
+	KeyLeft  Key = 0xff51
+	KeyRight Key = 0xff53
+	KeyUp    Key = 0xff52
+	KeyDown  Key = 0xff54
+
+	KeyF1  Key = 0xffbe
+	KeyF2  Key = 0xffbf
+	KeyF3  Key = 0xffc0
+	KeyF4  Key = 0xffc1
+	KeyF5  Key = 0xffc2
+	KeyF6  Key = 0xffc3
+	KeyF7  Key = 0xffc4
+	KeyF8  Key = 0xffc5
+	KeyF9  Key = 0xffc6
+	KeyF10 Key = 0xffc7
+	KeyF11 Key = 0xffc8
+	KeyF12 Key = 0xffc9
+	KeyF13 Key = 0xffca
+	KeyF14 Key = 0xffcb
+	KeyF15 Key = 0xffcc
+	KeyF16 Key = 0xffcd
+	KeyF17 Key = 0xffce
+	KeyF18 Key = 0xffcf
+	KeyF19 Key = 0xffd0
+	KeyF20 Key = 0xffd1
+)

internal/common/hotkey/hotkey_linux_test.go

@@ -0,0 +1,41 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build linux && cgo
+
+package hotkey_test
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"voidraft/internal/common/hotkey"
+)
+
+// TestHotkey should always run success.
+// This is a test to run and for manually testing, registered combination:
+// Ctrl+Alt+A (Ctrl+Mod2+Mod4+A on Linux)
+func TestHotkey(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	hk := hotkey.New([]hotkey.Modifier{
+		hotkey.ModCtrl, hotkey.Mod2, hotkey.Mod4}, hotkey.KeyA)
+	if err := hk.Register(); err != nil {
+		t.Errorf("failed to register hotkey: %v", err)
+		return
+	}
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-hk.Keydown():
+			fmt.Println("triggered")
+		}
+	}
+}

internal/common/hotkey/hotkey_nocgo.go

@@ -0,0 +1,26 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build !windows && !cgo
+
+package hotkey
+
+type platformHotkey struct{}
+
+// Modifier represents a modifier
+type Modifier uint32
+
+// Key represents a key.
+type Key uint8
+
+func (hk *Hotkey) register() error {
+	panic("hotkey: cannot use when CGO_ENABLED=0")
+}
+
+// unregister deregisteres a system hotkey.
+func (hk *Hotkey) unregister() error {
+	panic("hotkey: cannot use when CGO_ENABLED=0")
+}

internal/common/hotkey/hotkey_nocgo_test.go

@@ -0,0 +1,34 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build (linux || darwin) && !cgo
+
+package hotkey_test
+
+import (
+	"testing"
+
+	"voidraft/internal/common/hotkey"
+)
+
+// TestHotkey should always run success.
+// This is a test to run and for manually testing, registered combination:
+// Ctrl+Alt+A (Ctrl+Mod2+Mod4+A on Linux)
+func TestHotkey(t *testing.T) {
+	defer func() {
+		if r := recover(); r != nil {
+			return
+		}
+		t.Fatalf("expect to fail when CGO_ENABLED=0")
+	}()
+
+	hk := hotkey.New([]hotkey.Modifier{}, hotkey.Key(0))
+	err := hk.Register()
+	if err != nil {
+		t.Fatal(err)
+	}
+	hk.Unregister()
+}

internal/common/hotkey/hotkey_test.go

@@ -0,0 +1,19 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+package hotkey_test
+
+import (
+	"os"
+	"testing"
+	"voidraft/internal/common/hotkey/mainthread"
+)
+
+// The test cannot be run twice since the mainthread loop may not be terminated:
+// go test -v -count=1
+func TestMain(m *testing.M) {
+	mainthread.Init(func() { os.Exit(m.Run()) })
+}

internal/common/hotkey/hotkey_windows.go

@@ -0,0 +1,224 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build windows
+
+package hotkey
+
+import (
+	"errors"
+	"runtime"
+	"sync"
+	"sync/atomic"
+	"time"
+	"voidraft/internal/common/hotkey/internal/win"
+)
+
+type platformHotkey struct {
+	mu         sync.Mutex
+	hotkeyId   uint64
+	registered bool
+	funcs      chan func()
+	canceled   chan struct{}
+}
+
+var hotkeyId uint64 // atomic
+
+// register registers a system hotkey. It returns an error if
+// the registration is failed. This could be that the hotkey is
+// conflict with other hotkeys.
+func (hk *Hotkey) register() error {
+	hk.mu.Lock()
+	if hk.registered {
+		hk.mu.Unlock()
+		return errors.New("hotkey already registered")
+	}
+
+	mod := uint8(0)
+	for _, m := range hk.mods {
+		mod = mod | uint8(m)
+	}
+
+	hk.hotkeyId = atomic.AddUint64(&hotkeyId, 1)
+	hk.funcs = make(chan func())
+	hk.canceled = make(chan struct{})
+	go hk.handle()
+
+	var (
+		ok   bool
+		err  error
+		done = make(chan struct{})
+	)
+	hk.funcs <- func() {
+		ok, err = win.RegisterHotKey(0, uintptr(hk.hotkeyId), uintptr(mod), uintptr(hk.key))
+		done <- struct{}{}
+	}
+	<-done
+	if !ok {
+		close(hk.canceled)
+		hk.mu.Unlock()
+		return err
+	}
+	hk.registered = true
+	hk.mu.Unlock()
+	return nil
+}
+
+// unregister deregisteres a system hotkey.
+func (hk *Hotkey) unregister() error {
+	hk.mu.Lock()
+	defer hk.mu.Unlock()
+	if !hk.registered {
+		return errors.New("hotkey is not registered")
+	}
+
+	done := make(chan struct{})
+	hk.funcs <- func() {
+		win.UnregisterHotKey(0, uintptr(hk.hotkeyId))
+		done <- struct{}{}
+		close(hk.canceled)
+	}
+	<-done
+
+	<-hk.canceled
+	hk.registered = false
+	return nil
+}
+
+const (
+	// wmHotkey represents hotkey message
+	wmHotkey uint32 = 0x0312
+	wmQuit   uint32 = 0x0012
+)
+
+// handle handles the hotkey event loop.
+func (hk *Hotkey) handle() {
+	// We could optimize this. So far each hotkey is served in an
+	// individual thread. If we have too many hotkeys, then a program
+	// have to create too many threads to serve them.
+	runtime.LockOSThread()
+	defer runtime.UnlockOSThread()
+
+	isKeyDown := false
+	tk := time.NewTicker(time.Second / 100)
+	for range tk.C {
+		msg := win.MSG{}
+		if !win.PeekMessage(&msg, 0, 0, 0) {
+			select {
+			case f := <-hk.funcs:
+				f()
+			case <-hk.canceled:
+				return
+			default:
+				// If the latest status is KeyDown, and AsyncKeyState is 0, consider key is up.
+				if win.GetAsyncKeyState(int(hk.key)) == 0 && isKeyDown {
+					hk.keyupIn <- Event{}
+					isKeyDown = false
+				}
+			}
+			continue
+		}
+		if !win.GetMessage(&msg, 0, 0, 0) {
+			return
+		}
+
+		switch msg.Message {
+		case wmHotkey:
+			hk.keydownIn <- Event{}
+			isKeyDown = true
+		case wmQuit:
+			return
+		}
+	}
+}
+
+// Modifier represents a modifier.
+// https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-registerhotkey
+type Modifier uint8
+
+// All kinds of Modifiers
+const (
+	ModAlt   Modifier = 0x1
+	ModCtrl  Modifier = 0x2
+	ModShift Modifier = 0x4
+	ModWin   Modifier = 0x8
+)
+
+// Key represents a key.
+// https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes
+type Key uint16
+
+// All kinds of Keys
+const (
+	KeySpace Key = 0x20
+	Key0     Key = 0x30
+	Key1     Key = 0x31
+	Key2     Key = 0x32
+	Key3     Key = 0x33
+	Key4     Key = 0x34
+	Key5     Key = 0x35
+	Key6     Key = 0x36
+	Key7     Key = 0x37
+	Key8     Key = 0x38
+	Key9     Key = 0x39
+	KeyA     Key = 0x41
+	KeyB     Key = 0x42
+	KeyC     Key = 0x43
+	KeyD     Key = 0x44
+	KeyE     Key = 0x45
+	KeyF     Key = 0x46
+	KeyG     Key = 0x47
+	KeyH     Key = 0x48
+	KeyI     Key = 0x49
+	KeyJ     Key = 0x4A
+	KeyK     Key = 0x4B
+	KeyL     Key = 0x4C
+	KeyM     Key = 0x4D
+	KeyN     Key = 0x4E
+	KeyO     Key = 0x4F
+	KeyP     Key = 0x50
+	KeyQ     Key = 0x51
+	KeyR     Key = 0x52
+	KeyS     Key = 0x53
+	KeyT     Key = 0x54
+	KeyU     Key = 0x55
+	KeyV     Key = 0x56
+	KeyW     Key = 0x57
+	KeyX     Key = 0x58
+	KeyY     Key = 0x59
+	KeyZ     Key = 0x5A
+
+	KeyReturn Key = 0x0D
+	KeyEscape Key = 0x1B
+	KeyDelete Key = 0x2E
+	KeyTab    Key = 0x09
+
+	KeyLeft  Key = 0x25
+	KeyRight Key = 0x27
+	KeyUp    Key = 0x26
+	KeyDown  Key = 0x28
+
+	KeyF1  Key = 0x70
+	KeyF2  Key = 0x71
+	KeyF3  Key = 0x72
+	KeyF4  Key = 0x73
+	KeyF5  Key = 0x74
+	KeyF6  Key = 0x75
+	KeyF7  Key = 0x76
+	KeyF8  Key = 0x77
+	KeyF9  Key = 0x78
+	KeyF10 Key = 0x79
+	KeyF11 Key = 0x7A
+	KeyF12 Key = 0x7B
+	KeyF13 Key = 0x7C
+	KeyF14 Key = 0x7D
+	KeyF15 Key = 0x7E
+	KeyF16 Key = 0x7F
+	KeyF17 Key = 0x80
+	KeyF18 Key = 0x81
+	KeyF19 Key = 0x82
+	KeyF20 Key = 0x83
+)

internal/common/hotkey/hotkey_windows_test.go

@@ -0,0 +1,41 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build windows
+
+package hotkey_test
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+	"voidraft/internal/common/hotkey"
+)
+
+// TestHotkey should always run success.
+// This is a test to run and for manually testing, registered combination:
+// Ctrl+Shift+S
+func TestHotkey(t *testing.T) {
+	tt := time.Second * 5
+
+	ctx, cancel := context.WithTimeout(context.Background(), tt)
+	defer cancel()
+
+	hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
+	if err := hk.Register(); err != nil {
+		t.Errorf("failed to register hotkey: %v", err)
+		return
+	}
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-hk.Keydown():
+			fmt.Println("triggered")
+		}
+	}
+}

internal/common/hotkey/internal/win/hotkey.go

@@ -0,0 +1,122 @@
+// Copyright 2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build windows
+// +build windows
+
+package win
+
+import (
+	"syscall"
+	"unsafe"
+)
+
+var (
+	user32           = syscall.NewLazyDLL("user32")
+	registerHotkey   = user32.NewProc("RegisterHotKey")
+	unregisterHotkey = user32.NewProc("UnregisterHotKey")
+	getMessage       = user32.NewProc("GetMessageW")
+	peekMessage      = user32.NewProc("PeekMessageA")
+	sendMessage      = user32.NewProc("SendMessageW")
+	getAsyncKeyState = user32.NewProc("GetAsyncKeyState")
+	quitMessage      = user32.NewProc("PostQuitMessage")
+)
+
+// RegisterHotKey defines a system-wide hot key.
+// https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-registerhotkey
+func RegisterHotKey(hwnd, id uintptr, mod uintptr, k uintptr) (bool, error) {
+	ret, _, err := registerHotkey.Call(
+		hwnd, id, mod, k,
+	)
+	return ret != 0, err
+}
+
+// UnregisterHotKey frees a hot key previously registered by the calling
+// thread.
+// https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-unregisterhotkey
+func UnregisterHotKey(hwnd, id uintptr) (bool, error) {
+	ret, _, err := unregisterHotkey.Call(hwnd, id)
+	return ret != 0, err
+}
+
+// MSG contains message information from a thread's message queue.
+//
+// https://docs.microsoft.com/en-us/windows/win32/api/winuser/ns-winuser-msg
+type MSG struct {
+	HWnd    uintptr
+	Message uint32
+	WParam  uintptr
+	LParam  uintptr
+	Time    uint32
+	Pt      struct { //POINT
+		x, y int32
+	}
+}
+
+// SendMessage sends the specified message to a window or windows.
+// The SendMessage function calls the window procedure for the specified
+// window and does not return until the window procedure has processed
+// the message.
+// The return value specifies the result of the message processing;
+// it depends on the message sent.
+//
+// https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-sendmessage
+func SendMessage(hwnd uintptr, msg uint32, wParam, lParam uintptr) uintptr {
+	ret, _, _ := sendMessage.Call(
+		hwnd,
+		uintptr(msg),
+		wParam,
+		lParam,
+	)
+
+	return ret
+}
+
+// GetMessage retrieves a message from the calling thread's message
+// queue. The function dispatches incoming sent messages until a posted
+// message is available for retrieval.
+//
+// https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getmessage
+func GetMessage(msg *MSG, hWnd uintptr, msgFilterMin, msgFilterMax uint32) bool {
+	ret, _, _ := getMessage.Call(
+		uintptr(unsafe.Pointer(msg)),
+		hWnd,
+		uintptr(msgFilterMin),
+		uintptr(msgFilterMax),
+	)
+
+	return ret != 0
+}
+
+// PeekMessage dispatches incoming sent messages, checks the thread message
+// queue for a posted message, and retrieves the message (if any exist).
+//
+// https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-peekmessagea
+func PeekMessage(msg *MSG, hWnd uintptr, msgFilterMin, msgFilterMax uint32) bool {
+	ret, _, _ := peekMessage.Call(
+		uintptr(unsafe.Pointer(msg)),
+		hWnd,
+		uintptr(msgFilterMin),
+		uintptr(msgFilterMax),
+		0, // PM_NOREMOVE
+	)
+
+	return ret != 0
+}
+
+// PostQuitMessage indicates to the system that a thread has made
+// a request to terminate (quit). It is typically used in response
+// to a WM_DESTROY message.
+//
+// https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-postquitmessage
+func PostQuitMessage(exitCode int) {
+	quitMessage.Call(uintptr(exitCode))
+}
+
+func GetAsyncKeyState(keycode int) uintptr {
+	ret, _, _ := getAsyncKeyState.Call(uintptr(keycode))
+	return ret
+}

internal/common/hotkey/mainthread/doc.go

@@ -0,0 +1,11 @@
+// Copyright 2022 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+// Package mainthread provides facilities to schedule functions
+// on the main thread. It includes platform-specific implementations
+// for Windows, Linux, and macOS. The macOS implementation is specially
+// designed to handle main thread events for the NSApplication.
+package mainthread

internal/common/hotkey/mainthread/os.go

@@ -0,0 +1,87 @@
+// Copyright 2022 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build windows || linux
+
+package mainthread
+
+import (
+	"fmt"
+	"runtime"
+	"sync"
+)
+
+func init() {
+	runtime.LockOSThread()
+}
+
+// Call calls f on the main thread and blocks until f finishes.
+func Call(f func()) {
+	done := donePool.Get().(chan error)
+	defer donePool.Put(done)
+
+	data := funcData{fn: f, done: done}
+	funcQ <- data
+	if err := <-done; err != nil {
+		panic(err)
+	}
+}
+
+// Init initializes the functionality of running arbitrary subsequent functions be called on the main system thread.
+//
+// Init must be called in the main.main function.
+func Init(main func()) {
+	done := donePool.Get().(chan error)
+	defer donePool.Put(done)
+
+	go func() {
+		defer func() {
+			done <- nil
+		}()
+		main()
+	}()
+
+	for {
+		select {
+		case f := <-funcQ:
+			func() {
+				defer func() {
+					r := recover()
+					if f.done != nil {
+						if r != nil {
+							f.done <- fmt.Errorf("%v", r)
+						} else {
+							f.done <- nil
+						}
+					} else {
+						if r != nil {
+							select {
+							case erroQ <- fmt.Errorf("%v", r):
+							default:
+							}
+						}
+					}
+				}()
+				f.fn()
+			}()
+		case <-done:
+			return
+		}
+	}
+}
+
+var (
+	funcQ    = make(chan funcData, runtime.GOMAXPROCS(0))
+	erroQ    = make(chan error, 42)
+	donePool = sync.Pool{New: func() interface{} {
+		return make(chan error)
+	}}
+)
+
+type funcData struct {
+	fn   func()
+	done chan error
+}

internal/common/hotkey/mainthread/os_darwin.go

@@ -0,0 +1,69 @@
+// Copyright 2022 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build darwin
+
+package mainthread
+
+/*
+#cgo CFLAGS: -x objective-c
+#cgo LDFLAGS: -framework Cocoa
+#import <Cocoa/Cocoa.h>
+#import <Dispatch/Dispatch.h>
+
+extern void os_main(void);
+extern void wakeupMainThread(void);
+static bool isMainThread() {
+	return [NSThread isMainThread];
+}
+*/
+import "C"
+import (
+	"os"
+	"runtime"
+)
+
+func init() {
+	runtime.LockOSThread()
+}
+
+// Call calls f on the main thread and blocks until f finishes.
+func Call(f func()) {
+	if C.isMainThread() {
+		f()
+		return
+	}
+	go func() {
+		mainFuncs <- f
+		C.wakeupMainThread()
+	}()
+}
+
+// Init initializes the functionality of running arbitrary subsequent functions be called on the main system thread.
+//
+// Init must be called in the main.main function.
+func Init(f func()) {
+	go func() {
+		f()
+		os.Exit(0)
+	}()
+
+	C.os_main()
+}
+
+var mainFuncs = make(chan func(), 1)
+
+//export dispatchMainFuncs
+func dispatchMainFuncs() {
+	for {
+		select {
+		case f := <-mainFuncs:
+			f()
+		default:
+			return
+		}
+	}
+}

internal/common/hotkey/mainthread/os_darwin.m

@@ -0,0 +1,28 @@
+// Copyright 2022 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+//go:build darwin
+
+#include <stdint.h>
+#import <Cocoa/Cocoa.h>
+
+extern void dispatchMainFuncs();
+
+void wakeupMainThread(void) {
+	dispatch_async(dispatch_get_main_queue(), ^{
+		dispatchMainFuncs();
+	});
+}
+
+// The following three lines of code must run on the main thread.
+// It must handle it using golang.design/x/mainthread.
+//
+// inspired from here: https://github.com/cehoffman/dotfiles/blob/4be8e893517e970d40746a9bdc67fe5832dd1c33/os/mac/iTerm2HotKey.m
+void os_main(void) {
+	[NSApplication sharedApplication];
+	[NSApp disableRelaunchOnLogin];
+	[NSApp run];
+}