hotkey

README

hotkey

cross platform hotkey package in Go

import "golang.design/x/hotkey"

Features

• Cross platform supports: macOS, Linux (X11), and Windows
• Global hotkey registration without focus on a window

API Usage

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.

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)
		return
	}

	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)
}

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 golang.design/x/hotkey/mainthread is possible. It is uncessary or applications based on other GUI frameworks, such as fyne, ebiten, or Gio. See the "./examples" folder 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).

Examples

Description	Folder
A minimum example	minimum
Register multiple hotkeys	multiple
A example to use in GLFW	glfw
A example to use in Fyne	fyne
A example to use in Ebiten	ebiten
A example to use in Gio	gio

Who is using this package?

The main purpose of building this package is to support the midgard project.

To know more projects, check our wiki page.

License

MIT | © 2021 The golang.design Initiative Authors, written by Changkun Ou.

Documentation

Overview

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)
}

Index

• type Event
• type Hotkey
  • func New(mods []Modifier, key Key) *Hotkey
  • func (hk *Hotkey) Keydown() <-chan Event
  • func (hk *Hotkey) Keyup() <-chan Event
  • func (hk *Hotkey) Register() error
  • func (hk *Hotkey) String() string
  • func (hk *Hotkey) Unregister() error
• type Key
• type Modifier

Types

type Event

type Event struct{}

Event represents a hotkey event

type Hotkey

type Hotkey struct {
	// contains filtered or unexported fields
}

Hotkey is a combination of modifiers and key to trigger an event

func New

func New(mods []Modifier, key Key) *Hotkey

New creates a new hotkey for the given modifiers and keycode.

func (*Hotkey) Keydown

func (hk *Hotkey) Keydown() <-chan Event

Keydown returns a channel that receives a signal when the hotkey is triggered.

func (*Hotkey) Keyup

func (hk *Hotkey) Keyup() <-chan Event

Keyup returns a channel that receives a signal when the hotkey is released.

func (*Hotkey) Register

func (hk *Hotkey) Register() error

Register registers a combination of hotkeys. If the hotkey has registered. This function will invalidates the old registration and overwrites its callback.

func (*Hotkey) String

func (hk *Hotkey) String() string

String returns a string representation of the hotkey.

func (*Hotkey) Unregister

func (hk *Hotkey) Unregister() error

Unregister unregisters the hotkey.

type Key

type Key uint16

Key represents a key. See /usr/include/X11/keysymdef.h

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
)

All kinds of keys

type Modifier

type Modifier uint32

Modifier represents a modifier.

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)
)

All kinds of Modifiers See /usr/include/X11/X.h