Controls

Name

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

Synopsis

#include <ggi/gic.h>

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

int gicControlHandleEvent(struct gg_stem *stem,
      struct gic_control *control, gii_event *event);

Description

A struct 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 gg-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