1giiOpen(3) GGI giiOpen(3)
2
6 giiOpen, giiJoinInputs, giiSplitInputs, giiClose : Open, join, split
7 and close inputs
8
10 #include <ggi/gii.h>
11 gii_input_t giiOpen(const char * input, ...);
13 gii_input_t giiJoinInputs(gii_input_t inp, gii_input_t inp2);
15 int giiSplitInputs(gii_input_t inp, gii_input_t *newhand,
17 uint32_t origin, uint32_t flags);
18 int giiClose(gii_input_t inp);
20
23 giiOpen opens an input. This function is given the name of an input
24 driver to load. Passing NULL here results in an auto-select mechanism,
25 which currently means examining the contents of GII_INPUT.
26 The optional arguments are a NULL-terminated list of pointers, which
28 are used to give additional information to the targets. Currently only
29 the first pointer is specified: void * argptr, a pointer to a library-
30 specific struct. It is used to pass parameters that are not easily
31 transferable in textual form.
32 Parameters which can be represented in text format are usually trans‐
34 fered in the input parameter, in the format: library_name:arguments
35 giiJoinInputs joins two inputs into one. From a programmers' point of
37 view, this closes both inp and inp2 and opens an new input that com‐
38 bines both inputs into one. That is, after giiJoinInputs has completed,
39 there is no need to giiClose inp and inp2 any more. When cleaning up,
40 you need to close the returned input instead. See the example for
41 details. However the inputs are not actually closed or reopened inter‐
42 nally. That is, you will not get any startup-events or similar the
43 driver generates, though pending events of both old inputs are trans‐
44 ferred to the newly created input.
45 giiSplitInputs splits one of the inputs from a group of joined inputs
47 and returns the handle. The parameter origin can be used to choose
48 which input to detach (use GGI_EV_ORIGIN_NONE to match any input.) The
49 detached handle is returned in newhand. Note, though, that if the
50 detached input is the same one given in inp, then the handle returned
51 in newhand will be that of the rest of the joined inputs instead. You
52 can tell whether this happened by checking the return code. Events
53 queued in the joined input for the newly split input are not trans‐
54 ferred automatically. You must drain them out yourself. The parameter
55 flags is reserved for future use and should be set to 0.
56 giiClose releases and destroys an open input and its associated inter‐
58 nal control structures. This will put back input streams to their
59 default modes, etc.
60 Important: If you want to handle input while also using LibGGI,
61 using LibGII functions such as giiOpen is almost certainly not
62 what you want. Use LibGGI functions such as ggiEventRead(3)
63 with the LibGGI visual instead.
64
66 giiOpen and giiJoinInputs return the opened or joined input, or NULL
67 for error. The gii_input_t type is opaque to the programmer and can
68 only be used through GII functions.
69 giiClose returns GGI_OK (== 0) on success, otherwise an gii-error(3)
71 code.
72 giiSplitInputs returns 0 for normal success, or 1 if the input which
74 was split off was the same as the one passed in inp (in which case,
75 newhand may contain a handle to a joined set of visuals.) Otherwise,
76 it returns an gii-error(3) code.
77
79 GII input management:
80 gii_input_t inp, inp2, inp3;
82 /* Initialize the GII library. This must be called before any other
84 * GII function. */
85 if (giiInit() != 0) exit(1);
86 /* Open the nulldevice for testing ... */
88 if ((inp=giiOpen("input-null",NULL)) == NULL) {
89 giiExit();
90 exit(1);
91 }
92 /* Open stdin for testing ... */
94 if ((inp2=giiOpen("input-stdin",NULL)) == NULL) {
95 giiExit();
96 exit(1);
97 }
98 /* Open evdev for testing ... */
100 if ((inp3=giiOpen("input-linux-evdev",NULL)) == NULL) {
101 giiExit();
102 exit(1);
103 }
104 /* Now join them. Note the usage of _i_n_p_=_giiJoin(inp,inp2);
106 * This is the recommended way to do this. */
107 inp=giiJoinInputs(inp,inp2);
108 /* Note that this mends inp2 into inp. That is you may not call
110 giiClose(inp2) - this happens together with giiClose(inp) ! */
111 /* Join another */
113 inp=giiJoinInputs(inp,inp3);
114 /* ... do the real work here ... */
116 /* Split one of them back out of the join. */
118 res = ggiSplitInputs(inp, &inp2, GII_EV_ORIGIN_NONE, 0);
119 if (res == 1) {
120 gii_input_t tmp;
121 tmp = imp2;
122 imp2 = imp1;
123 imp1 = tmp;
124 }
125 else if (res < 0) fprintf(stderr, "Failed to split inputs\n");
126 /* Close the single input */
128 giiClose(inp2);
129 /* Close the joined input */
131 giiClose(inp);
132 /* Now close down LibGII. */
134 giiExit();
135
138 giiInit(3)
139libgii-1.0.x 2006-12-30 giiOpen(3)