.TH "gicContextAllocate" 3 "2006-12-30" "libgiigic-1.1.x" GGI
.SH NAME
\fBgicContextAllocate\fR, \fBgicContextFree\fR, \fBgicContextAttachControl\fR, \fBgicContextDetachControl\fR, \fBgicContextLookupControl\fR, \fBgicContextGetControl\fR, \fBgicContextNumControls\fR, \fBgicContextGetName\fR, \fBgicContextWrite\fR, \fBgicContextRead\fR, \fBgicContextMapActions\fR, \fBgicContextFindConflict\fR, \fBgicContextHandleEvent\fR : Contexts
.SH SYNOPSIS
.nb
.nf
#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);
.fi

.SH 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. \fBgicHeadRead(3)\fR
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 \fBgicContextAllocate\fR. To free a
context that is not needed anymore, call \fBgicContextFree\fR.

\fBgicContextAttachControl\fR and \fBgicContextDetachControl\fR 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.

\fBgicContextLookupControl\fR and \fBgicContextGetControl\fR 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 \fBgicContextNumControls\fR to 
query for the number of controls.

\fBgicContextGetName\fR can be used to query for the name of a context.

\fBgicContextWrite\fR writes a description of the context given to the given
file. It can be read back with \fBgicContextRead\fR which will allocate and
return context if successful. Afterwards \fBgicContextMapActions\fR should be
called to reestablish the mapping between actions and callbacks.

In learning-mode, \fBgicContextFindConflict\fR is useful to check, if there are
conflicting controls.

When the context is active, you feed it with events using
\fBgicContextHandleEvent\fR which will cause it to activate the relevant
callbacks.

When an application is in a context, you should feed the events to 
\fBgicContextHandleEvent\fR to activate the relevant
callbacks.
.SH RETURN VALUE
\fBgicContextRead\fR and \fBgicContextAllocate\fR return the read/allocated 
context on return or NULL on failure.

\fBgicContextAttachControl\fR, \fBgicContextDetachControl\fR, \fBgicContextWrite\fR
and \fBgicContextMapActions\fR return 0 on success and an \f(CWgii-error(3)\fR
code on failure.

\fBgicContextLookupControl\fR and \fBgicContextGetControl\fR return the requested 
control or NULL on failure.

\fBgicContextNumControls\fR return the number of controls attached to the 
context.
.SH SEE ALSO
\f(CWgicHeadRead(3)\fR, \f(CWgic_context(3)\fR