SYNOPSIS

#include <ggi/gic.h>
gic_head *gicHeadAllocate (gic_handle_t hand,
char *name);
void gicHeadFree (gic_handle_t hand,
gic_head *head);
int gicHeadAttachContext(gic_handle_t hand,
gic_head *head,gic_context *context);
int gicHeadDetachContext(gic_handle_t hand,
gic_head *head,gic_context *context);
gic_context *gicHeadLookupContext(gic_handle_t hand,
gic_head *head,const char *name);
gic_context *gicHeadGetContext (gic_handle_t hand,
gic_head *head,int number);
int gicHeadNumContexts (gic_handle_t hand,
gic_head *head);
int gicHeadWrite (gic_handle_t hand,
gic_head *head,FILE *file);
gic_head *gicHeadRead (gic_handle_t hand,
FILE *file);
int gicHeadMapActions (gic_handle_t hand,
gic_head *head,gic_actionlist *actions);

DESCRIPTION

A gic_head is LIBGIIGIC's notion of a collection of contexts. Each context describes the mappings between inputs and actions for a given situation in a program.

Thus a head usually describes all the contexts of a program that are managed by libgiigic.

Usually a program will not have to bother with most functions as it will read its config via gicHeadRead. However when building apps that can (re)build the configuration files, the other functions become useful.

A gic_head is allocated using gicHeadAllocate, which takes the gic handle it will be associated with and a name for the Head. It returns the allocated head or NULL on failure.

gicHeadFree frees an allocated gic_head.

gicHeadAttachContext and gicHeadDetachContext are used to attach and detach contexts from a head. A context refers to a situation in a program that has an input mapping attached to it. Most programs will have multiple such contexts, like one for accessing the menus, one for the game mode, etc.

gicHeadLookupContext and gicHeadGetContext can be used to get access to contexts attached to a head. The former accesses the contexts by name, the latter by number. You can use gicHeadNumContexts to query for the number of contexts.

gicHeadWrite can be used to write out a textual description of the head. This is usually used to write out a config file after it changed.

gicHeadRead will read such a file, allocate a gic_head and fill it with the read data. After that, you should call gicHeadMapActions to reestablish the connection between the actions and the action callbacks.

RETURN VALUE

gicHeadRead and gicHeadAllocate return the read/allocated head on return or NULL on failure.

gicHeadAttachContext, gicHeadDetachContext, gicHeadWrite and gicHeadMapActions return 0 on success and an gii-error(3) code on failure.

gicHeadLookupContext and gicHeadGetContext return the requested context or NULL on failure.

gicHeadNumContexts return the number of contexts attached to the head.