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 primary facility to register a system-level global hotkey shortcut to notify an application if a user triggers the desired hotkey. A hotkey must be a combination of modifiers and a single key.

Note a platform-specific detail on macOS due to the OS restriction (other platforms do not have this restriction): hotkey events must be handled on the "main thread". Therefore, to use this package properly, one must call the (*Hotkey).Register method on the main thread, and an OS app main event loop must be established. One can use the provided golang.design/x/hotkey/mainthread for self-contained applications. For applications based on other GUI frameworks, one has to use their provided ability to run the (*Hotkey).Register on the main thread. See the examples folder for more examples.

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 a platform specific detail 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 call the "(*Hotkey).Register" method on the main thread, and an OS app main event loop must be established. For self-contained applications, collaborating with the provided golang.design/x/hotkey/mainthread is possible. For applications based on other GUI frameworks, one has to use their provided ability to run the "(*Hotkey).Register" on the main thread. See the "./examples" folder for more examples.

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

func (*Hotkey) Keydown

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

Keydown returns a channel that receives a signal when 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.

For macOS, this method must be called on the main thread, and an OS main event loop also must be running. This can be done when collaborating with the golang.design/x/hotkey/mainthread package.

func (*Hotkey) Unregister

func (hk *Hotkey) Unregister() error

Unregister unregisters the hotkey.

type Key

type Key uint8

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

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

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