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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Hotkey ¶
type Hotkey struct {
// contains filtered or unexported fields
}
Hotkey is a combination of modifiers and key to trigger an event
func (*Hotkey) Keydown ¶ added in v0.3.0
Keydown returns a channel that receives a signal when the hotkey is triggered.
func (*Hotkey) Keyup ¶ added in v0.3.0
Keyup returns a channel that receives a signal when the hotkey is released.
func (*Hotkey) Register ¶ added in v0.3.0
Register registers a combination of hotkeys. If the hotkey has registered. This function will invalidates the old registration and overwrites its callback.
func (*Hotkey) Unregister ¶ added in v0.3.0
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
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
module
|
|
|
internal
|
|
|
Package mainthread wrapps the golang.design/x/mainthread, and provides a different implementation for macOS so that it can handle main thread events for the NSApplication.
|
Package mainthread wrapps the golang.design/x/mainthread, and provides a different implementation for macOS so that it can handle main thread events for the NSApplication. |