giiJoinInputs

giiOpen(3)                             GGI                            giiOpen(3)



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)



libgii-1.0.x                       2006-12-30                         giiOpen(3)