Agar Logo

Agar 1.7 Manual

(Printable Version)
AG_Keyboard(3)

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


HISTORY

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

Csoft.net ElectronTubeStore