Chapter 8. Event Management

Table of Contents
LibGII layer
Input sources
Event model
Event processing

An interactive application responds to events generated by various input devices. Along with a graphic interface, GGI provides an event library to make the life easier for the programmer.

LibGII layer

LibGII (General Input Interface Library) is a flexible library for handling input from a variety of sources, including keyboards, mice, joysticks, etc.

LibGII is based on the concept of input streams, which virtualize access to the underlying input drivers. Events from various input devices are abstracted into easy-to-use structures. LibGII also allows the application to join streams together, receiving input from an arbitrary combination of devices.

LibGII consists of a main library (libgii.so) and a multitude of dynamic drivers. The library then loads the necessary "drivers" for the requested input.

LibGII is the result of splitting event functionality from LibGGI in order to further abstract it. Thus its design is deliberately similar to LibGGI. LibGGI uses LibGII for input (and LibGG, a library of LibGGI/LibGII common functions) internally.

Using LibGII as a standalone event library

While LibGGI relies on LibGII, the latter can be used independently as an event library for a non graphic application, or with another graphic subsystem. LibGGI automatically set LibGII up at initialization, but if LibGGI is not used, LibGII has to be initialized by the programmer.

To use LibGII, #include ggi/gii.h in a C program, call giiInit before any other LibGII functions, and giiExit when done. Other differences will be discussed later on.

Most LibGII functions return 0 to indicate success, and a negative error code to indicate errors. Return codes greater than 0 are usually additional hints or other non-negative integer data.

A list of error codes and descriptions can be found in the ggi/errors.h file, which is part of the LibGGI/LibGG package.

Input sources

An input source is an abstract link between input devices and the application. It's a channel through which generated events are delivered to the program, waiting to be processed.

When using LibGGI, an input source is automatically bound to the visual, with default devices opened. All the LibGII functions have a LibGGI equivalent which takes a ggi_visual_t instead of a gii_input_t. Of course, other inputs can still be opened manually.

Input drivers

An input driver is a module that generates events, usually from a system infrastructure. An exemple of input driver is the linux-keyboard which generate key events from the raw linux keyboard infrastructure. These are building blocks for input sources.

Filters

Along with input drivers, GII provides event filters. They look similar to input drivers (they are modules themself) but they are used to alter events being queued on an input source. They can block or generate events.

Filters allow very interesting things to be done without messing with the application, like saving events for future playback, repeating event on a TCP socket, or remapping keyboards.

Merging inputs

When a input or filter module is successfully opened (with the giiOpen function), it creates an input source. In the case of a filter, this input source will hardly provides any event, since the only time a filter can generate an event is when an other event is queued on the input source.

An input source can in fact be composed of several event generators. This is achieved by merging input sources together with the giiJoinInputs function. This input source will recieve all events generated by the inputs and filters it contains, and pass them through the filters. This allow an application to read all its events from a single source, regardless of the number and variety of devices it is actually bound to.

giiSplitInputs can then be used to remove an individual input or filter instance from an input source.

Event model

GII defines several type of events, described in details in gii_event(9gii).

Event processing

Event driven applications usually work the following way: they perform various initializations before entering an event loop, which is left when a specific situation is meet.