Man Linux: Main Page and Category List

NAME

       giiOpen,  giiJoinInputs,  giiSplitInputs,  giiClose - Open, join, split
       and close inputs

SYNOPSIS

       #include <ggi/gii.h>

       gii_input_t giiOpen(const char * input, ...);

       gii_input_t giiJoinInputs(gii_input_t inp, gii_input_t inp2);

       int giiSplitInputs(gii_input_t inp, gii_input_t *newhand,
                          uint32_t origin, uint32_t flags);

       int giiClose(gii_input_t inp);

DESCRIPTION

       giiOpen opens an input. This function is given the  name  of  an  input
       driver  to load. Passing NULL here results in an auto-select mechanism,
       which currently means examining the contents of GII_INPUT.

       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 * 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    input    parameter,    in    the    format:
       library_name:arguments

       giiJoinInputs joins two inputs into one. From a programmers’  point  of
       view,  this  closes  both  inp  and  inp2  and  opens an new input that
       combines both  inputs  into  one.  That  is,  after  giiJoinInputs  has
       completed,  there  is  no  need to giiClose inp and inp2 any more. When
       cleaning up, you need to close the  returned  input  instead.  See  the
       example  for  details.  However  the  inputs are not actually closed or
       reopened internally. That is, you will not get  any  startup-events  or
       similar  the driver generates, though pending events of both old inputs
       are transferred to the newly created input.

       giiSplitInputs splits one of the inputs from a group of  joined  inputs
       and  returns  the  handle.  The  parameter origin can be used to choose
       which input to detach (use GGI_EV_ORIGIN_NONE to match any input.)  The
       detached  handle  is  returned  in  newhand.  Note, though, that if the
       detached input is the same one given in inp, then the  handle  returned
       in  newhand will be that of the rest of the joined inputs instead.  You
       can tell whether this happened by checking  the  return  code.   Events
       queued  in  the  joined  input  for  the  newly  split  input  are  not
       transferred automatically.  You  must  drain  them  out  yourself.  The
       parameter flags is reserved for future use and should be set to 0.

       giiClose  releases  and  destroys  an  open  input  and  its associated
       internal control structures. This will put back input streams to  their
       default modes, etc.
              Important:  If you want to handle input while also using LibGGI,
              using LibGII functions such as giiOpen is almost  certainly  not
              what  you  want.   Use  LibGGI functions such as ggiEventRead(3)
              with the LibGGI visual instead.

RETURN VALUE

       giiOpen and giiJoinInputs return the opened or joined  input,  or  NULL
       for  error.   The  gii_input_t type is opaque to the programmer and can
       only be used through GII functions.

       giiClose returns GGI_OK (== 0) on success,  otherwise  an  gii-error(3)
       code.

       giiSplitInputs  returns  0  for normal success, or 1 if the input which
       was split off was the same as the one passed in  inp  (in  which  case,
       newhand  may  contain a handle to a joined set of visuals.)  Otherwise,
       it returns an gii-error(3) code.

EXAMPLES

       GII input management:

       gii_input_t inp, inp2, inp3;

       /* Initialize the GII library. This must be called before any other
        * GII function. */
       if (giiInit() != 0) exit(1);

       /* Open the nulldevice for testing ... */
       if ((inp=giiOpen("input-null",NULL)) == NULL) {
           giiExit();
           exit(1);
       }

       /* Open stdin for testing ... */
       if ((inp2=giiOpen("input-stdin",NULL)) == NULL) {
           giiExit();
           exit(1);
       }

       /* Open evdev for testing ... */
       if ((inp3=giiOpen("input-linux-evdev",NULL)) == NULL) {
           giiExit();
           exit(1);
       }

       /* Now join them. Note the usage of _i_n_p_=_giiJoin(inp,inp2);
        * This is the recommended way to do this. */
       inp=giiJoinInputs(inp,inp2);

       /* Note that this mends inp2 into inp. That is you may not call
          giiClose(inp2) - this happens together with giiClose(inp) ! */

       /* Join another */
       inp=giiJoinInputs(inp,inp3);

       /* ... do the real work here ... */

       /* Split one of them back out of the join. */
       res = ggiSplitInputs(inp, &inp2, GII_EV_ORIGIN_NONE, 0);
       if (res == 1) {
           gii_input_t tmp;
           tmp = imp2;
           imp2 = imp1;
           imp1 = tmp;
       }
       else if (res < 0) fprintf(stderr, "Failed to split inputs\n");

       /* Close the single input */
       giiClose(inp2);

       /* Close the joined input */
       giiClose(inp);

       /* Now close down LibGII. */
       giiExit();

SEE ALSO

       giiInit(3)