Keyboard input

Every GtkWindow maintains a single focus location (in the “focus-widget” property). The focus widget is the target widget for key events sent to the window. Only widgets which have “can-focus” set to TRUE can become the focus. Typically these are input controls such as entries or text fields, but e.g. buttons can take the focus too.

Input widgets can be given the focus by clicking on them, but focus can also be moved around with certain key events (this is known as keyboard navigation). GTK reserves the Tab key to move the focus to the next location, and Shift-Tab to move it back to the previous one. In addition many containers allow directional navigation with the arrow keys.

Many widgets can be activated to trigger and action. E.g., you can activate a button or switch by clicking on them, but you can also activate them with the keyboard, by using the Enter or Space keys.

Apart from keyboard navigation, activation and directly typing into entries or text views, GTK widgets can use key events for activating shortcuts. Shortcuts generally act as a quick way to move the focus around or to activate a widget that does not currently have the focus.

GTK has traditionally supported different kinds of shortcuts:

  • Accelerators are any other shortcuts that can be activated regardless of where the focus is, and typically trigger global actions, such as Ctrl-Q to quit an application.

  • Mnemonics are usually triggered using Alt as a modifier for a letter. They are used in places where a label is associated with a control, and are indicated by underlining the letter in the label. As a special case, inside menus (i.e. inside GtkPopoverMenu), mnemonics can be triggered without the modifier.

  • Key bindings are specific to individual widgets, such as Ctrl-C or Ctrl-V in an entry copy to or paste from the clipboard. They are only triggered when the widget has focus.

GTK handles accelerators and mnemonics in a global scope, during the capture phase, and key bindings locally, during the target phase.

Under the hood, all shortcuts are represented as instances of GtkShortcut, and they are managed by GtkShortcutController.