gicContextAllocate(3)

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)