NAME
gicContextAllocate, gicContextFree, gicContextAttachControl,
gicContextDetachControl, gicContextLookupControl, gicContextGetControl,
gicContextNumControls, gicContextGetName, gicContextWrite,
gicContextRead, gicContextMapActions, gicContextFindConflict,
gicContextHandleEvent - Contexts
SYNOPSIS
#include <ggi/gic.h>
gic_context *gicContextAllocate(gic_handle_t hand,char *name);
void gicContextFree(gic_handle_t hand,gic_context *context);
int gicContextAttachControl(gic_handle_t hand,
gic_context *context,gic_control *control);
int gicContextDetachControl(gic_handle_t hand,
gic_context *context,gic_control *control);
gic_control *gicContextLookupControl(gic_handle_t hand,
gic_context *context,const char *name);
gic_control *gicContextGetControl(gic_handle_t hand,
gic_context *context,int number);
int gicContextNumControls(gic_handle_t hand,
gic_context *context);
int gicContextGetName(gic_handle_t hand,
gic_context *context, char *string, size_t maxlen);
int gicContextWrite(gic_handle_t hand,
gic_context *context,FILE *file);
gic_context *gicContextRead(gic_handle_t hand,FILE *file);
int gicContextMapActions(gic_handle_t hand,
gic_context *context,gic_actionlist *actions);
int gicContextFindConflict(gic_handle_t hand,
gic_context *context,gic_recognizer *rec,
gic_recognizer **start_and_return,gic_feature **optional);
int gicContextHandleEvent(gic_handle_t hand,
gic_context *context, gii_event *event);
DESCRIPTION
A gic_context is a collection of controls that make sense in a given
situation (context) of the application. A control is an abstract object
that usually describes a type of motion (e.g. sliding). It can have
multiple subobjects (called features) that can further break that down
(e.g. into up/down/left/right).
Most applications will not need to handle that themselves.
gicHeadRead(3) will provide all they need. For those that want to build
up contexts themselves, the following functions are provided:
To allocate a new gic_context, call gicContextAllocate. To free a
context that is not needed anymore, call gicContextFree.
gicContextAttachControl and gicContextDetachControl are used to attach
and detach controls from a context. A control refers to a collection of
features that describe a common motion. Most contexts will have
multiple such controls, like one for sliding and one for turning a
player.
gicContextLookupControl and gicContextGetControl can be used to get
access to controls attached to a context. The former accesses the
controls by name, the latter by number. You can use
gicContextNumControls to query for the number of controls.
gicContextGetName can be used to query for the name of a context.
gicContextWrite writes a description of the context given to the given
file. It can be read back with gicContextRead which will allocate and
return context if successful. Afterwards gicContextMapActions should be
called to reestablish the mapping between actions and callbacks.
In learning-mode, gicContextFindConflict is useful to check, if there
are conflicting controls.
When the context is active, you feed it with events using
gicContextHandleEvent which will cause it to activate the relevant
callbacks.
When an application is in a context, you should feed the events to
gicContextHandleEvent to activate the relevant callbacks.
RETURN VALUE
gicContextRead and gicContextAllocate return the read/allocated context
on return or NULL on failure.
gicContextAttachControl, gicContextDetachControl, gicContextWrite and
gicContextMapActions return 0 on success and an gii-error(3) code on
failure.
gicContextLookupControl and gicContextGetControl return the requested
control or NULL on failure.
gicContextNumControls return the number of controls attached to the
context.
SEE ALSO
gicHeadRead(3), gic_context(3)