Hotkeys API

The "new" hotkeys system as used in the Gtk3 UI is described here. The plan is to make this the only API for hotkeys in VICE, porting SDL over to this system and having any future UIs/ports use this as well.

Terminology

What is referred to here as "hotkeys" are keyboard shortcuts to activate UI elements such as dialogs and control emulator behavior (such as Warp mode, Pause, Reset, Quit). Another term for these is "(keyboard) accelerators" as used by Gtk+. I'll try to use "hotkeys" for VICE's API and "accelerators" for the Gtk+ implementation, but don't shoot me if I mix them up somewhere down the line.

Basic concepts

The hotkeys system is closely linked with the UI Actions system. In the Gtk3 UI the hotkeys are mapped to UI action IDs when parsing hotkey (.vhk) files. For any menu item that triggers a UI action the hotkey is used to set an accelerator label on the item (e.g. "Alt+Z"), but hotkeys can also be assigned to UI actions that do not have a corresponding menu item.

In the Gtk3 UI the accelerator labels on the menu items are cosmetic, we use GClosures for hotkey signal handlers so they also work in fullscreen mode and without a corresponding menu item.

A hotkey is in essence a simple key with optional modifier keys that maps to a UI action. Here's a snippet of a hotkey (data/C64/gtk3-hotkeys.vhk) file:

# "File" - monitor, reset, quit
monitor-open        <Alt>h
reset-soft          <Alt>F9
reset-hard          <Alt>F12
quit                <Alt>q

(todo: add some fake syntax highlighting with CSS to the example)

The first column contains UI action names, as declared in uiactions.c, and the second column contains key names with (optional) modifiers. So the "reset-soft" action can be triggered with Alt+F9. Modifier keys are referred to with angular brackets and key names are simple strings, taken from X11's keysymdef.h header, with the XK_ prefix stripped.
The VICE src/arch/shared/hotkeys/vhkkeysyms.h header contains copies of some of the X11 defines, prefixed with VHK_ instead of XK_. The defines for the modifiers are also present in the vhkkeysyms.h header:

#define VHK_MOD_NONE    0x0000
#define VHK_MOD_ALT     0x0001
#define VHK_MOD_COMMAND 0x0002
#define VHK_MOD_CONTROL 0x0004
#define VHK_MOD_HYPER   0x0008
#define VHK_MOD_META    0x0010
#define VHK_MOD_OPTION  0x0020
#define VHK_MOD_SHIFT   0x0040
#define VHK_MOD_SUPER   0x0080