giiEventPoll

giiEventPoll(3gii)                 LibGII API                 giiEventPoll(3gii)



NAME
       giiEventPoll, giiEventSelect, giiEventsQueued, giiEventRead - wait for
       and receive events

SYNOPSIS
       #include <ggi/gii.h>

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

       int giiEventSelect(gii_input_tinp, gii_event_mask *mask, int n, fd_set
       *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout);

       int giiEventsQueued(gii_input_t inp, gii_event_mask mask);

       int giiEventRead(gii_input_t inp, gii_event *ev, gii_event_mask mask);
       .SH "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.

       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.

       giiEventSelect is the combination of giiEventPoll and select(2) allowing
       to wait for both LibGII events and arbitrary file descriptors in any of
       the three states. However, this function is not available if the
       operating system does not support the select(2) call, not even as a stub.

       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. On error, a negative error
       code is returned.

       giiEventSelect returns the same values as select(2) . Unlike other
       LibGGI/LibGII functions, it also uses errno.  It will update the timeout
       regardless of whether or not the system call does so.

       giiEventsQueued returns the number of events.

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

EXAMPLES
   EVENT-POLLING LOOP
       This is one of the various ways of coding an event-polling loop.

              Note: This code uses the LibGGI functions and types instead of the
              LibGII ones, since the former is the more common case.


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

               ggiEventPoll(vis, emAll, &tv);
               n = ggiEventsQueued(vis, emAll);

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

               /* Do other stuff */
       }




GGI                              22 August 2001               giiEventPoll(3gii)