LibGIIGIC Functions
===================



Initialize and uninitialize LibGIIGIC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gicInit gicExit


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicInit(void);

  int gicExit(void);


Description
-----------

`gicInit` initializes the library. This function must be called before
using other LibGIIGIC functions; otherwise the results will be undefined.


`gicExit` uninitializes the library (after being initialized by
`gicInit`) and automatically cleans up if necessary.  This should be
called after an application finished using the library.  If any GIC
functions are called after the library has been uninitialized, the
results will be undefined.


`gicInit` allows multiple invocations.  A reference count is
maintained, and to completely uninitialize the library, `gicExit` must
be called as many times as `gicInit` has been called beforehand.


Return value
------------

`gicInit` returns `0` for OK, otherwise an :man:`gii-error(3)` code.


`gicExit` returns:

`0`
    after successfully cleaning up,

`>0`
    the number of 'open' `gicInit` calls, if there has been more than
    one call to `gicInit`.  As `gicInit` and `gicExit` must be used in
    properly nested pairs, e.g. the first `gicExit` after two
    `gicInit`'s will return `1`.

`<0`
    :man:`gii-error(3)`, especially if more `gicExit` calls have been done than
    `gicInit` calls.


Examples
--------

Initialize and uninitialize LibGIIGIC::

  if (gicInit() < 0) {
      fprintf(stderr, "Cannot initialize LibGIIGIC!\n");
      exit(1);
  }

  /* Do some LibGIIGIC stuff */

  gicExit();



See Also
--------

:man:`gicOpen(3)`



Open and close a recognizer
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gicOpen gicClose


Synopsis
--------

::

  #include <ggi/gic.h>

  gic_handle_t gicOpen(const char *recognizers,...);
  int gicClose(gic_handle_t hand);


Description
-----------

`gicOpen` opens a recognizer. This function is given the name of an
recognizer driver to load. If only `NULL` is specified, the default
recognizer target is opened.


The optional arguments are a `NULL`-terminated list of pointers, which
are used to give additional information to the targets.  Currently
only the first pointer is specified: `void *` :p:`argptr`, a pointer
to a library-specific struct. It is used to pass parameters that are
not easily transferable in textual form.


Parameters which can be represented in text format are usually
transfered in the :p:`input` parameter, in the format:
``library_name:arguments``


`gicClose` releases and destroys an open recognizer and its associated
internal control structures. This will put back input streams to their
default modes, etc.



Return value
------------

`gicOpen` returns the opened recognizer or `NULL` for error.
The `gic_handle_t` type is opaque to the programmer and can
only be used through GIC functions.


`gicClose` returns `GGI_OK` (== 0) for OK, otherwise an :man:`gii-error(3)` code.


See Also
--------

:man:`gicInit(3)`



Associate a gii handle with gic
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gicInputRegister


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicInputRegister(gic_handle_t hand,gii_input_t inp);


Description
-----------

`gicInputRegister` registers a GII gii_input_t with the GIC instance. This is needed by some
recognizers to be able to store their configuration in a portable way.


Return value
------------

`gicInputRegister` returns `0` for success, otherwise an :man:`gii-error(3)` code.


See Also
--------

:man:`gicOpen(3)`



Adjust Recognizers
~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gicRecognizerDriverRegister gicRecognizerDriverUnregister gicRecognizerDriverLookup


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicRecognizerDriverRegister(gic_handle_t hand,
				gic_recognizerdriver *driver);
  int gicRecognizerDriverUnregister(gic_handle_t hand,
				gic_recognizerdriver *driver);
  gic_recognizerdriver *gicRecognizerDriverLookup(gic_handle_t hand,
				const char *name);


Description
-----------

Recognizerdrivers. The work-monkeys. The recognizers given in :man:`gicOpen(3)` are automatically
open. But you might want to adjust that list.

`gicRecognizerDriverRegister` registers additional recognizers into the gic_handle_t.

`gicRecognizerDriverUnregister` unregisters the given recognizer from the gic_handle_t.

`gicRecognizerDriverLookup` searches for the recognizers with the given name.


Return value
------------

`gicRecognizerDriverRegister` and `gicRecognizerDriverUnregister` return `0` for
success, otherwise an :man:`gii-error(3)` code.

`gicRecognizerDriverLookup` returns a pointer to the recognizer if found, otherwise
NULL.


See Also
--------

:man:`gicOpen(3)`



Recognizer dump
~~~~~~~~~~~~~~~

.. manpage:: 3 gicRecognizerWrite


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicRecognizerWrite(gic_handle_t hand,
			gic_recognizer *recognizer, FILE *file);


Description
-----------

Writes out a dump of the recognizer into the given file.

TODO Write something useful here - be more verbose


Return value
------------

`gicRecognizerWrite` returns `0` for success, otherwise an :man:`gii-error(3)` code.


See Also
--------

:man:`gicActionWrite(3)`



Train recognizers
~~~~~~~~~~~~~~~~~

.. manpage:: 3 gicRecognizerTrain gicRecognizerTrainStart gicRecognizerTrainStop gicRecognizerTrainAdd gicRecognizerTrainMove gicRecognizerFindConflict gicRecognizerGetName gicRecognizerGetOpposite


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicRecognizerTrain(gic_handle_t hand,
			gic_recognizer **recognizerlist,
			gii_event *event);

  #define gicRecognizerTrainStart(hand,x) \
			gicRecognizerTrain(hand,x,NULL)
  #define gicRecognizerTrainStop(hand,x)  \
			gicRecognizerTrain(hand,x,NULL)

  int gicRecognizerTrainAdd(gic_handle_t hand,
			gic_recognizer **recognizerlist,
			gic_recognizer *newone);
  int gicRecognizerTrainMove(gic_handle_t hand,
			gic_recognizer **recognizerlist,
			gic_recognizer *newone);
  int gicRecognizerFindConflict(gic_handle_t hand,
			gic_recognizer *recognizer,
			gic_recognizer *compare_to);
  int gicRecognizerGetName(gic_handle_t hand,
			gic_recognizer *recognizer,
			char *string, size_t maxlen);
  int gicRecognizerGetOpposite(gic_handle_t hand,
			gic_recognizer *recognizer,
			gic_recognizer **opposite);


Description
-----------

TODO Write something useful here


Return value
------------

All functions
return `0` for success, otherwise an :man:`gii-error(3)` code.


See Also
--------

:man:`gicOpen(3)`



Action handling
~~~~~~~~~~~~~~~

.. manpage:: 3 gicActionWrite gicActionMapActions


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicActionWrite(gic_handle_t hand,
		gic_actionlist *aclist, FILE *where);
  int gicActionMapActions(gic_handle_t hand,
		gic_actionlist *aclist, gic_actionlist *actions);


Description
-----------

`gicActionWrite` writes out a dump to the :p:`where` file.

TODO Describe `gicActionMapActions` here


Return value
------------

`gicActionWrite` and `gicActionMapActions` return `0` for success,
otherwise an :man:`gii-error(3)` code.


See Also
--------

:man:`gicRecognizerWrite(3)`



Allocate Features
~~~~~~~~~~~~~~~~~

.. manpage:: 3 gicFeatureAllocate gicFeatureFree


Synopsis
--------

::

  #include <ggi/gic.h>

  gic_feature *gicFeatureAllocate(gic_handle_t hand,
			char *name,char *shortname);
  void gicFeatureFree(gic_handle_t hand,
			gic_feature *feature);


Description
-----------

TODO Write something useful here


Return value
------------

TODO Write something useful here


See Also
--------

TODO

Bind Features with Recognizers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gicFeatureAttachRecognizerDriver gicFeatureAttachRecognizer gicFeatureDetachRecognizer gicFeatureGetRecognizer gicFeatureNumRecognizers gicFeatureGetName


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicFeatureAttachRecognizerDriver(gic_handle_t hand,
        gic_feature *feature, gic_recognizerdriver *driver,void *privdata);
  int gicFeatureAttachRecognizer(gic_handle_t hand,
        gic_feature *feature, gic_recognizer *recognizer);
  int gicFeatureDetachRecognizer(gic_handle_t hand,
        gic_feature *feature, gic_recognizer *recognizer);
  gic_recognizer *gicFeatureGetRecognizer(gic_handle_t hand,
        gic_feature *feature, int number);
  int gicFeatureNumRecognizers(gic_handle_t hand,
        gic_feature *feature);
  int gicFeatureGetName(gic_handle_t hand,
        gic_feature *feature, char *string, size_t maxlen);


Description
-----------

TODO Write something useful here


Return value
------------

TODO Write something useful here


See Also
--------

TODO

Bind Features and Actions
~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gicFeatureAttachAction gicFeatureDetachAction gicFeatureWrite gicFeatureRead 


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicFeatureAttachAction(gic_handle_t hand,
        gic_feature *feature,
        void (*action)(gic_handle_t hand, gic_actionlist *action,
                gic_feature *feature,gic_state newstate,
                gic_flag flag,int recnum),
        void *privdata, char *name);

  int gicFeatureDetachAction(gic_handle_t hand,
        gic_feature *feature,
        void (*action)(gic_handle_t hand, gic_actionlist *action,
                gic_feature *feature,gic_state newstate,
                gic_flag flag,int recnum),
        void *privdata, char *name);


Description
-----------

`gicFeatureAttachAction()` and `gicFeatureDetachAction()` are used to bind an
action (i.e. a callback function) to a feature. This is usually handled
by higher layers, which map whole sets of actions using a gic_actionlist.


Return value
------------

`gicFeatureAttachAction()` and `gicFeatureDetachAction()` return 0 on success
and an :man:`gii-error(3)` code on failure.

See Also
--------

TODO

Load and Save Feature
~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gicFeatureWrite gicFeatureRead 


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicFeatureWrite(gic_handle_t hand,
        gic_feature *feature, FILE *file);
  gic_feature *gicFeatureRead(gic_handle_t hand,
        FILE *file);


Description
-----------

`gicFeatureWrite` writes a description of the feature given to the given
file. It can be read back with `gicFeatureRead` which will allocate and
return a feature if successful. Afterwards `gicFeatureMapActions` should be
called to reestablish the mapping between actions and callbacks.


Return value
------------

TODO Write something useful here


See Also
--------

:man:`gicFeatureMapActions(3)`


Feature mappings
~~~~~~~~~~~~~~~~

.. manpage:: 3 gicFeatureMapActions gicFeatureFindConflict


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicFeatureMapActions(gic_handle_t hand,
        gic_feature *feature, gic_actionlist *actions);

  int gicFeatureFindConflict(gic_handle_t hand,
        gic_feature *feature, gic_recognizer *rec,
        gic_recognizer **start_and_return);


Description
-----------

`gicFeatureMapActions` is called to reestablish the connection between 
the actions and the action callbacks.

In learning-mode, `gicFeatureFindConflict` is useful to check, if there are
conflicting features.


Return value
------------

TODO Write something useful here


See Also
--------

TODO

Event handling
~~~~~~~~~~~~~~

.. manpage:: 3 gicFeatureActivate gicFeatureHandleEvent


Synopsis
--------

::

  #include <ggi/gic.h>

  int gicFeatureActivate(gic_handle_t hand,
        gic_feature *feature,gic_state newstate,gic_flag flag,int recnum);

  int gicFeatureHandleEvent(gic_handle_t hand,
        gic_feature *feature, gii_event *event);


Description
-----------

To manually activate a feature, call `gicFeatureActivate`. This will 
activate the relevant callbacks.

You can feed events to `gicFeatureHandleEvent` to activate the relevant
callbacks. However, usually one uses `gicContextHandleEvent`.


Return value
------------

TODO Write something useful here


See Also
--------

:man:`gicContextHandleEvent(3)`



Controls
~~~~~~~~

.. manpage:: 3 gicControlAllocate gicControlFree gicControlAttachFeature gicControlDetachFeature gicControlLookupFeature gicControlGetFeature gicControlNumFeatures gicControlGetName gicControlWrite gicControlRead gicControlMapActions gicControlFindConflict gicControlHandleEvent


Synopsis
--------

::

  #include <ggi/gic.h>

  gic_control *gicControlAllocate(gic_handle_t hand,
        char *name,char *shortname);
  void gicControlFree(gic_handle_t hand, gic_control *control);
  int gicControlAttachFeature(gic_handle_t hand,
        gic_control *control,gic_feature *feature);
  int gicControlDetachFeature(gic_handle_t hand,
        gic_control *control,gic_feature *feature);
  gic_feature *gicControlLookupFeature(gic_handle_t hand,
        gic_control *context,const char *name);
  gic_feature *gicControlGetFeature(gic_handle_t hand,
        gic_control *context,int number);
  int gicControlNumFeatures(gic_handle_t hand,
        gic_control *context);
  int gicControlGetName(gic_handle_t hand,
        gic_control *control, char *string, size_t maxlen);
  int gicControlWrite(gic_handle_t hand,
        gic_control *control,FILE *file);
  gic_control *gicControlRead(gic_handle_t hand, FILE *file);
  int gicControlMapActions(gic_handle_t hand,
        gic_control *control,gic_actionlist *actions);
  int gicControlFindConflict(gic_handle_t hand,
        gic_control *control,gic_recognizer *feature,
        gic_recognizer **start_and_return,gic_feature **optional);

  int gicControlHandleEvent(gic_handle_t hand,
        gic_control *control, gii_event *event);


Description
-----------

A gic_control is LIBGIIGIC's notion of a collection of things that control a
motion or similar.

Usually applications do not need to handle this themselves.

To allocate a new :man:`gic_control(3)`, call `gicControlAllocate`. To free a
context that is not needed anymore, call `gicControlFree`.

`gicControlAttachFeature` and `gicControlDetachFeature` are used to
attach and detach features from a control. Multiple features like
up/down/left/right make up a control (like sliding).

`gicControlLookupFeature` and `gicControlGetFeature` can be used to get
access to features attached to a control. The former accesses the features
by name, the latter by number. You can use `gicControlNumFeatures` to
query for the number of controls.

`gicControlGetName` can be used to query for the name of a control.

`gicControlWrite` writes a description of the control given to the given
:p:`file`. It can be read back with `gicContextRead` which will allocate and
return a control if successful. Afterwards `gicControlMapActions` should be
called to reestablish the mapping between actions and callbacks.

In learning-mode, `gicControlFindConflict` is useful to check, if there are
conflicting controls.

You can feed events to `gicControlHandleEvent` to activate the relevant
callbacks. However, usually one uses `gicContextHandleEvent`.


Return value
------------

`gicControlRead` and `gicControlAllocate` return the read/allocated 
context on return or NULL on failure.

`gicControlAttachFeature`, `gicControlDetachFeature`, `gicControlWrite`
and `gicControlMapActions` return `0` on success and an :man:`gii-error(3)`
code on failure.

`gicControlLookupFeature` and `gicControlGetFeature` return the requested 
feature or NULL on failure.

`gicControlNumFeatures` return the number of features attached to the 
control.


See Also
--------

:man:`gicContextRead(3)`



Contexts
~~~~~~~~

.. manpage:: 3 gicContextAllocate gicContextFree gicContextAttachControl gicContextDetachControl gicContextLookupControl gicContextGetControl gicContextNumControls gicContextGetName gicContextWrite gicContextRead gicContextMapActions gicContextFindConflict gicContextHandleEvent


Synopsis
--------

::

  #include <ggi/gic.h>

  gic_context *gicContextAllocate(gic_handle_t hand,char *name);
  void gicContextFree(gic_handle_t hand,gic_context *context);
  int gicContextAttachControl(gic_handle_t hand,
        gic_context *context,gic_control *control);
  int gicContextDetachControl(gic_handle_t hand,
        gic_context *context,gic_control *control);
  gic_control *gicContextLookupControl(gic_handle_t hand,
        gic_context *context,const char *name);
  gic_control *gicContextGetControl(gic_handle_t hand,
        gic_context *context,int number);
  int gicContextNumControls(gic_handle_t hand,
        gic_context *context);
  int gicContextGetName(gic_handle_t hand,
        gic_context *context, char *string, size_t maxlen);
  int gicContextWrite(gic_handle_t hand,
        gic_context *context,FILE *file);
  gic_context *gicContextRead(gic_handle_t hand,FILE *file);
  int gicContextMapActions(gic_handle_t hand,
        gic_context *context,gic_actionlist *actions);
  int gicContextFindConflict(gic_handle_t hand,
        gic_context *context,gic_recognizer *rec,
        gic_recognizer **start_and_return,gic_feature **optional);

  int gicContextHandleEvent(gic_handle_t hand,
        gic_context *context, gii_event *event);


Description
-----------

A 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`
will provide all they need. For those that want to build up contexts
themselves, the following functions are provided:

To allocate a new 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 :man:`gii-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.


See Also
--------

:man:`gicHeadRead(3)`, :man:`gic_context(3)`


Heads
~~~~~

.. manpage:: 3 gicHeadAllocate gicHeadFree gicHeadAttachContext gicHeadDetachContext gicHeadLookupContext gicHeadGetContext gicHeadNumContexts gicHeadWrite gicHeadRead gicHeadMapActions


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 :p:`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 :man:`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


Predefined callback functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gicActionLazyAction gicActionLazyGetstate gicActionLazyReset


Synopsis
--------

::

  #include <ggi/gicaction_lazy.h>

  void gicActionLazyAction(gic_handle_t hand, gic_actionlist *action, gic_feature *feature,
			gic_state newstate, gic_flag flag, int recnum);
  gic_state gicActionLazyGetstate(gicActionActionLazyData *data);
  void gicActionLazyReset(gicActionLazyData *data);

Description
-----------

TODO

Return value
------------

TODO

See Also
--------

TODO
