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 Gdk's gdkkeysyms.h header, with the GDK_KEY_ prefix stripped.