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 hotkey so that the application can be notified if a user triggers the desired hotkey. By definition, a hotkey is a combination of modifiers and a single key, and thus register a hotkey that contains multiple keys is not supported at the moment. Furthermore, because of OS restriction, hotkey events must be handled on the main thread.

Therefore, in order to use this package properly, here is a complete example that corporates the mainthread package:

package main

import (
	"context"

	"golang.design/x/hotkey"
	"golang.design/x/mainthread"
)

// initialize mainthread facility so that hotkey can be
// properly registered to the system and handled by the
// application.
func main() { mainthread.Init(fn) }
func fn() { // Use fn as the actual main function.
	var (
		mods = []hotkey.Modifier{hotkey.ModCtrl}
		k    = hotkey.KeyS
	)

	// Register a desired hotkey.
	hk, err := hotkey.Register(mods, k)
	if err != nil {
		panic("hotkey registration failed")
	}

	// Start listen hotkey event whenever you feel it is ready.
	triggered := hk.Listen(context.Background())
	for range triggered {
		println("hotkey ctrl+s is triggered")
	}
}

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 hotkey so that the application can be notified if a user triggers the desired hotkey. By definition, a hotkey is a combination of modifiers and a single key, and thus register a hotkey that contains multiple keys is not supported at the moment. Furthermore, because of OS restriction, hotkey events must be handled on the main thread.

Therefore, in order to use this package properly, here is a complete example that corporates the golang.design/x/mainthread package:

package main

import (
	"context"

	"golang.design/x/hotkey"
	"golang.design/x/mainthread"
)

// initialize mainthread facility so that hotkey can be
// properly registered to the system and handled by the
// application.
func main() { mainthread.Init(fn) }
func fn() { // Use fn as the actual main function.
	var (
		mods = []hotkey.Modifier{hotkey.ModCtrl}
		k    = hotkey.KeyS
	)

	// Register a desired hotkey.
	hk, err := hotkey.Register(mods, k)
	if err != nil {
		panic("hotkey registration failed")
	}

	// Start listen hotkey event whenever you feel it is ready.
	triggered := hk.Listen(context.Background())
	for range triggered {
		println("hotkey ctrl+s is triggered")
	}
}

Index

• type Event
• type Hotkey
  • func Register(mods []Modifier, key Key) (*Hotkey, error)
  • func (hk *Hotkey) Listen(ctx context.Context) <-chan Event
• 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 Register

func Register(mods []Modifier, key Key) (*Hotkey, 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) Listen

func (hk *Hotkey) Listen(ctx context.Context) <-chan Event

Listen handles a hotkey event and triggers a call to fn. The hotkey listen hook terminates when the context is canceled.

type Key

type Key uint8

Key represents a key. https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes

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

All kinds of Keys

type Modifier

type Modifier uint8

Modifier represents a modifier. https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-registerhotkey

const (
	ModAlt   Modifier = 0x1
	ModCtrl  Modifier = 0x2
	ModShift Modifier = 0x4
	ModWin   Modifier = 0x8
)

All kinds of Modifiers