gicControlAllocate(3)

NAME
gicControlAllocate, gicControlFree, gicControlAttachFeature, gicControlDetachFeature, gicControlLookupFeature, gicControlGetFeature, gicControlNumFeatures, gicControlGetName, gicControlWrite, gicControlRead, gicControlMapActions, gicControlFindConflict, gicControlHandleEvent : Controls

SYNOPSIS
#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);

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 gic_control(3), call gicControlAllocate. To free a context that is not needed anymore, call gicControlFree. gicControlAttachFeature and gicControlDetachFeature are used to attach and detach features from a control. Multiple features like up/down/left/right make up a control (like sliding). gicControlLookupFeature and gicControlGetFeature 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 gicControlNumFeatures to query for the number of controls. gicControlGetName can be used to query for the name of a control. gicControlWrite writes a description of the control given to the given file. It can be read back with gicContextRead(3) which will allocate and return a control if successful. Afterwards gicControlMapActions should be called to reestablish the mapping between actions and callbacks. In learning-mode, gicControlFindConflict is useful to check, if there are conflicting controls. You can feed events to gicControlHandleEvent to activate the relevant callbacks. However, usually one uses gicContextHandleEvent(3).

RETURN VALUE
gicControlRead and gicControlAllocate return the read/allocated context on return or NULL on failure. gicControlAttachFeature, gicControlDetachFeature, gicControlWrite and gicControlMapActions return 0 on success and an gii-error(3) code on failure. gicControlLookupFeature and gicControlGetFeature return the requested feature or NULL on failure. gicControlNumFeatures return the number of features attached to the control.

SEE ALSO
gicContextRead(3)