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