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.

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 {
        return
    }
    fmt.Printf("hotkey: %v is registered\n", hk)
    <-hk.Keydown()
    fmt.Printf("hotkey: %v is down\n", hk)
    <-hk.Keyup()
    fmt.Printf("hotkey: %v is up\n", hk)
    hk.Unregister()
    fmt.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. For applications based on other GUI frameworks, such as fyne, ebiten, or Gio. This is not necessary. 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.

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 golang.design/x/hotkey/mainthread is possible. For applications based on other GUI frameworks, such as fyne, ebiten, or Gio. This is not necessary. 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.

  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 { return } fmt.Printf("hotkey: %v is registered\n", hk) <-hk.Keydown() fmt.Printf("hotkey: %v is down\n", hk) <-hk.Keyup() fmt.Printf("hotkey: %v is up\n", hk) hk.Unregister() fmt.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 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