Contexts
Name
gicContextAllocate, gicContextFree, gicContextAttachControl, gicContextDetachControl, gicContextLookupControl, gicContextGetControl, gicContextNumControls, gicContextGetName, gicContextWrite, gicContextRead, gicContextMapActions, gicContextFindConflict, gicContextHandleEvent : Contexts
Synopsis
#include <ggi/gic.h> struct gic_context *gicContextAllocate(struct gg_stem *stem, const char *name); void gicContextFree(struct gg_stem *stem, struct gic_context *context); int gicContextAttachControl(struct gg_stem *stem, struct gic_context *context, struct gic_control *control); int gicContextDetachControl(struct gg_stem *stem, struct gic_context *context, struct gic_control *control); struct gic_control *gicContextLookupControl(struct gg_stem *stem, struct gic_context *context, const char *name); struct gic_control *gicContextGetControl(struct gg_stem *stem, struct gic_context *context, int number); int gicContextNumControls(struct gg_stem *stem, struct gic_context *context); int gicContextGetName(struct gg_stem *stem, struct gic_context *context, char *string, size_t maxlen); int gicContextWrite(struct gg_stem *stem, struct gic_context *context, FILE *file); struct gic_context *gicContextRead(struct gg_stem *stem, FILE *file); int gicContextMapActions(struct gg_stem *stem, struct gic_context *context, struct gic_action actions[]); int gicContextFindConflict(struct gg_stem *stem, struct gic_context *context, struct gic_recognizer *rec, struct gic_recognizer **start_and_return, struct gic_feature **optional); int gicContextHandleEvent(struct gg_stem *stem, struct gic_context *context, gii_event *event);
Description
A struct 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 struct 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 gg-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.