NAME

AG_GlobalKeys — agar application-wide keyboard shortcuts

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>

DESCRIPTION

The AG_GlobalKeys interface associates application-wide keyboard shortcuts to specified callback routines.

Note that AG_GlobalKeys entirely ignores the status of Agar windows and widgets. To implement keyboard operations specific to a given Agar window or widget, one would instead use AG_ActionOnKeyDown(3) or AG_ActionOnKeyUp(3). For a more low-level interface to keyboard processing, the base AG_Widget(3) class also provides the ‘key-down’ and ‘key-up’ event handlers.

INTERFACE

void
AG_BindGlobalKey(AG_KeySym key, AG_KeyMod mod, void (*fn)(void));

void
AG_BindGlobalKeyEv(AG_KeySym key, AG_KeyMod mod, void (*fn)(AG_Event *));

void
AG_BindStdGlobalKeys(void);

int
AG_UnbindGlobalKey(AG_KeySym key, AG_KeyMod mod);

void
AG_ClearGlobalKeys(void);

AG_BindGlobalKey() binds the specified routine to the given key combination. Keys are represented by AG_KeySym enums, and acceptable values for sym and mod arguments are listed under AG_KeySym(3) and AG_KeyMod(3).

The AG_BindGlobalKeyEv() variant accepts an AG_Event(3) style function. Note that arguments of AG_KEY_ANY and AG_KEYMOD_ANY are acceptable, in which case any key or key modifier will be matched.

The AG_BindStdGlobalKeys() routine sets up the standard key bindings:

CTRL+EQUALS / META+EQUALS

AG_ZoomIn(3)

CTRL+MINUS / META+MINUS

AG_ZoomOut(3)

CTRL+0 / META+0

AG_ZoomReset(3)

CTRL+Q / META+Q

AG_QuitGUI(3)

ESCAPE

AG_CloseFocusedWindow(3)

AG_UnbindGlobalKey() removes the given key mapping. AG_ClearGlobalKeys() removes all existing key mappings.

SEE ALSO

AG_Intro(3), AG_Keyboard(3), AG_KeyMod(3), AG_KeySym(3), AG_Widget(3), AG_Window(3)

HISTORY

The AG_GlobalKeys interface first appeared in Agar 1.0. AG_BindStdGlobalKeys() first appeared in Agar 1.5.0.