NAME
gicHeadAllocate, gicHeadFree, gicHeadAttachContext,
gicHeadDetachContext, gicHeadLookupContext, gicHeadGetContext,
gicHeadNumContexts, gicHeadWrite, gicHeadRead, gicHeadMapActions -
Heads
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.
SEE ALSO
TODO