Wait for and receive events

Name

giiEventPoll, giiEventsQueued, giiEventRead : Wait for and receive events

Synopsis

#include <ggi/gii.h>

gii_event_mask giiEventPoll(gii_input inp, gii_event_mask mask,
                            struct timeval *t);

int giiEventsQueued(gii_input inp, gii_event_mask mask);

int giiEventRead(gii_input inp, gii_event *ev, gii_event_mask mask);

Description

giiEventPoll waits for specific events to become available on an input. This call somewhat resembles the Unix select(2) call, but only for LibGII events and is more portable. The function returns after an event matching the given event mask is available or after the amount of time specified by t has elapsed, whichever occurs first. If t is NULL, there is no timeout. In this case, the function will return immediatly if there is no possibility to retrieve an event (the underlying input has no source listening on low-level events).

The timeout value on return is updated to the time that would have been remaining. So make sure to re-setup this value when calling giiEventPoll in a loop.

giiEventsQueued returns the number of events matching the specified event mask that are currently queued in the input.

giiEventRead blocks for and transfers an event from the given input to the location pointed to by ev. The event with the earliest timestamp that matches the given mask is returned to the application.

Return value

giiEventPoll returns a mask of available events (constrained by the given mask). It is 0 if no events are available. If no timeout is given, 0 means that the input has no sources that have a chance of producing an event, so it returns instead of looping forever.

giiEventsQueued returns the number of events.

giiEventRead returns the size of event on success, and 0 on error.

Examples

This is one of the various ways of coding an event-polling loop:

for(;;) {
    tv.tv_sec = 0;
    tv.tv_usec = 100; /* change to 0 for non-blocking behaviour */

    giiEventPoll(inp, emAll, &tv);
    n = giiEventsQueued(inp, emAll);

    /* Process events in one gulp, when available */
    while(n--) {
        giiEventRead(inp, &ggievent, emAll);
        switch(giievent.any.type) {
            /* ... */
        }
    }

    /* Do other stuff */
}