.TH "gicHeadAllocate" 3 "2006-12-30" "libgiigic-1.1.x" GGI
.SH NAME
\fBgicHeadAllocate\fR, \fBgicHeadFree\fR, \fBgicHeadAttachContext\fR, \fBgicHeadDetachContext\fR, \fBgicHeadLookupContext\fR, \fBgicHeadGetContext\fR, \fBgicHeadNumContexts\fR, \fBgicHeadWrite\fR, \fBgicHeadRead\fR, \fBgicHeadMapActions\fR : Heads
.SH SYNOPSIS
.nb
.nf
#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);
.fi

.SH 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 \fBgicHeadRead\fR. However when building apps that 
can (re)build the configuration files, the other functions become useful.

A gic_head is allocated using \fBgicHeadAllocate\fR, 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.

\fBgicHeadFree\fR frees an allocated gic_head.

\fBgicHeadAttachContext\fR and \fBgicHeadDetachContext\fR 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.

\fBgicHeadLookupContext\fR and \fBgicHeadGetContext\fR 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 \fBgicHeadNumContexts\fR to query for the number
of contexts.

\fBgicHeadWrite\fR 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.

\fBgicHeadRead\fR will read such a \fIfile\fR, allocate a gic_head and fill it with
the read data. After that, you should call \fBgicHeadMapActions\fR to
reestablish the connection between the actions and the action callbacks.
.SH RETURN VALUE
\fBgicHeadRead\fR and \fBgicHeadAllocate\fR return the read/allocated head on return
or NULL on failure.

\fBgicHeadAttachContext\fR, \fBgicHeadDetachContext\fR, \fBgicHeadWrite\fR and
\fBgicHeadMapActions\fR return 0 on success and an \f(CWgii-error(3)\fR code on failure.

\fBgicHeadLookupContext\fR and \fBgicHeadGetContext\fR return the requested context
or NULL on failure.

\fBgicHeadNumContexts\fR return the number of contexts attached to the head.
.SH SEE ALSO
TODO