.TH "gicControlAllocate" 3 "2006-12-30" "libgiigic-1.1.x" GGI
.SH NAME
\fBgicControlAllocate\fR, \fBgicControlFree\fR, \fBgicControlAttachFeature\fR, \fBgicControlDetachFeature\fR, \fBgicControlLookupFeature\fR, \fBgicControlGetFeature\fR, \fBgicControlNumFeatures\fR, \fBgicControlGetName\fR, \fBgicControlWrite\fR, \fBgicControlRead\fR, \fBgicControlMapActions\fR, \fBgicControlFindConflict\fR, \fBgicControlHandleEvent\fR : Controls
.SH SYNOPSIS
.nb
.nf
#include <ggi/gic.h>

gic_control *gicControlAllocate(gic_handle_t hand,
      char *name,char *shortname);
void gicControlFree(gic_handle_t hand, gic_control *control);
int gicControlAttachFeature(gic_handle_t hand,
      gic_control *control,gic_feature *feature);
int gicControlDetachFeature(gic_handle_t hand,
      gic_control *control,gic_feature *feature);
gic_feature *gicControlLookupFeature(gic_handle_t hand,
      gic_control *context,const char *name);
gic_feature *gicControlGetFeature(gic_handle_t hand,
      gic_control *context,int number);
int gicControlNumFeatures(gic_handle_t hand,
      gic_control *context);
int gicControlGetName(gic_handle_t hand,
      gic_control *control, char *string, size_t maxlen);
int gicControlWrite(gic_handle_t hand,
      gic_control *control,FILE *file);
gic_control *gicControlRead(gic_handle_t hand, FILE *file);
int gicControlMapActions(gic_handle_t hand,
      gic_control *control,gic_actionlist *actions);
int gicControlFindConflict(gic_handle_t hand,
      gic_control *control,gic_recognizer *feature,
      gic_recognizer **start_and_return,gic_feature **optional);

int gicControlHandleEvent(gic_handle_t hand,
      gic_control *control, gii_event *event);
.fi

.SH DESCRIPTION
A gic_control is LIBGIIGIC's notion of a collection of things that control a
motion or similar.

Usually applications do not need to handle this themselves.

To allocate a new \f(CWgic_control(3)\fR, call \fBgicControlAllocate\fR. To free a
context that is not needed anymore, call \fBgicControlFree\fR.

\fBgicControlAttachFeature\fR and \fBgicControlDetachFeature\fR are used to
attach and detach features from a control. Multiple features like
up/down/left/right make up a control (like sliding).

\fBgicControlLookupFeature\fR and \fBgicControlGetFeature\fR can be used to get
access to features attached to a control. The former accesses the features
by name, the latter by number. You can use \fBgicControlNumFeatures\fR to
query for the number of controls.

\fBgicControlGetName\fR can be used to query for the name of a control.

\fBgicControlWrite\fR writes a description of the control given to the given
\fIfile\fR. It can be read back with \fBgicContextRead(3)\fR which will allocate and
return a control if successful. Afterwards \fBgicControlMapActions\fR should be
called to reestablish the mapping between actions and callbacks.

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

You can feed events to \fBgicControlHandleEvent\fR to activate the relevant
callbacks. However, usually one uses \fBgicContextHandleEvent(3)\fR.
.SH RETURN VALUE
\fBgicControlRead\fR and \fBgicControlAllocate\fR return the read/allocated 
context on return or NULL on failure.

\fBgicControlAttachFeature\fR, \fBgicControlDetachFeature\fR, \fBgicControlWrite\fR
and \fBgicControlMapActions\fR return \fB0\fR on success and an \f(CWgii-error(3)\fR
code on failure.

\fBgicControlLookupFeature\fR and \fBgicControlGetFeature\fR return the requested 
feature or NULL on failure.

\fBgicControlNumFeatures\fR return the number of features attached to the 
control.
.SH SEE ALSO
\f(CWgicContextRead(3)\fR