NAME

AG_Keyboard — agar direct keyboard interface

SYNOPSIS

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

DESCRIPTION

The AG_Keyboard interface provides a direct interface to keyboard status. This manual page also documents a few utility routines for dealing with Agar keyboard symbols. The AG_Keyboard object itself is registered and accessed through the AG_Driver(3) interface.

INHERITANCE HIERARCHY

AG_Object(3) -> AG_InputDevice(3) -> AG_Keyboard.

WIDGET INTERFACE

const char *
AG_LookupKeyName(AG_KeySym sym);

char *
AG_LookupKeyMod(AG_KeyMod mod);

AG_KeySym
AG_LookupKeySym(const char *name);

int *
AG_GetKeyState(AG_Widget *widget);

int
AG_GetKeyCount(AG_Widget *widget);

void
AG_SetKeyState(AG_Widget *widget, int *keyState);

Uint
AG_GetModState(AG_Widget *widget);

void
AG_SetModState(AG_Widget *widget, Uint modState);

int
AG_CompareKeyMods(Uint modState, const char *flags);

The AG_LookupKeyName() function returns a pointer to a statically-allocated, user-readable string describing the given AG_KeySym(3) (or NULL if the argument is out of range).

The AG_LookupKeyMod() function returns a dynamically-allocated, user-readable string describing the given AG_KeyMod(3).

AG_LookupKeySym() returns a keysym value for the specified name (or AG_KEY_NONE if no match was found).

The AG_GetKeyState() function returns a pointer to an array of integers which represent the current keyboard status. The array has up to AG_KEY_LAST entries (see AG_KeySym(3)). AG_GetKeyCount() returns the number of entries in the keyboard status array.

The AG_SetKeyState() routine overwrites the keyboard status array with the contents of keyState (which should have AG_KEY_LAST entries).

AG_GetModState() returns the current keyboard modifier status (see AG_KeyMod(3)). AG_SetModState() overwrites the current modifier status with the value of modState.

The AG_CompareKeyMods() function compares a modifier status against a string of flags, returning 1 if any of the modifiers described by the string are active, or 0 otherwise. No distinction is made between left and right-sided modifiers. The string may contain "C" for CTRL, "A" for ALT, "S" for SHIFT, and "M" for META.

INTERNAL DRIVER INTERFACE

AG_Keyboard *
AG_KeyboardNew(AG_Driver *drv, const char *descr);

void
AG_KeyboardUpdate(AG_Keyboard *kbd, AG_KeyboardAction action, AG_KeySym sym);

int
AG_ProcessKey(AG_Keyboard *kbd, AG_Window *win, AG_KeyboardAction action, AG_KeySym sym, Uint32 unicode);

The AG_KeyboardNew() function registers a new keyboard device under the specified AG_Driver(3).

When a keyboard event is received by the driver, it should call AG_KeyboardUpdate() to update Agar's internal keyboard status as soon as the event is received. Typically, AG_KeyboardUpdate() is called by the GetNextEvent() routine of the driver (see AG_GetNextEvent(3)).

The AG_ProcessKey() function is called to perform final processing of key press and key release events (sending ‘key-up’ and ‘key-down’ events to the appropriate Agar widgets). Typically, AG_ProcessKey() is called from the ProcessEvent() routine of the driver (see AG_ProcessEvent(3)). The agDrivers must be locked.

AG_KeyboardUpdate() and AG_ProcessKey() accept the same arguments. action should be AG_KEY_PRESSED or AG_KEY_RELEASED. The sym argument is the Agar virtual key (see AG_KeySym(3)), and unicode is the Unicode character value. Either (but not both) arguments may be undefined. sym may be set to AG_KEY_NONE if there is no corresponding Agar virtual key, and unicode may be set to 0 if there is no corresponding Unicode character (as should be the case for function keys).

SEE ALSO

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

HISTORY

The AG_Keyboard interface first appeared in Agar 1.4.0 and the widget interface was first documented in Agar 1.5.0.