Provided by: libgiigic1-dev_1.1.2-1_i386 bug

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