AWAIT_EVENT(3G)

NAME

await_event − wait for an event to occur and be buffered, then return the class of that event (LOCATOR or CHOICE).

SYNOPSIS

C SYNTAX

void await_event(await_fid,timeout,valid,class);
int await_fid;
float timeout;
int *valid,*class;

FORTRAN77 SYNTAX

        subroutine await_event(await_fid,timeout,valid,class)
        integer*4 await_fid
        real timeout
        integer*4 valid,class

PASCAL SYNTAX

Procedure await_event(await_fid:integer;timeout:real;var valid,
class:integer);

HP-UX COMPATIBILITY

Level: HP-UX/STANDARD

Origin: ANSI Computer Graphics Interface

DESCRIPTION

INPUT PARAMETERS

await_fid
specifies how await_event waits. If await_fid is the file descriptor of an opened graphics input device, then wait for events from that device. If await_fid is -1 (minus one), then wait for events from any device.
timeout
is the maximum time, in seconds, to wait for an event. Valid is set to FALSE (0) if time runs out.

OUTPUT PARAMETERS

valid
is set to TRUE (1) if the event data is valid and FALSE (0) if the event data is invalid.
class
may be one of the following classes: LOCATOR or CHOICE.

DISCUSSION

If await_fid is a negative one (-1), await_event waits for an event from any device. If await_fid is a valid file descriptor, await_event waits for an event from the corresponding device. If an event from a suitable device is already in the queue, then this call returns immediately with the first such event. If no such event is in the queue, then await_event waits for an event from an appropriate device to be placed in the event queue. This is a timed wait with the interval specified by timeout. If no event occurs before time runs out, then valid is set to FALSE (0), and class is undefined. If an event is found before time runs out, then class is set to the event class (CHOICE or LOCATOR) and valid is set to TRUE.

This routine does not read and remove the event from the queue. It determines the existence of an event and the class of input involved. Once await_event has indicated a valid event, either read_locator_event or read_choice_event should be used to read the event and remove it from the event queue.

The procedures enable_events and disable_events are used to enable and disable the event generation capability of choice and locator devices.

If await_fid is an invalid file descriptor, a "device not initialized" error is reported and the procedure is ignored.

There is one common event queue for all physical devices. All events are entered in the order in which they occur. This allows time ordering to be established between several input devices. Simultaneous events are placed in the queue in an implementation dependent order within their group, with all but the last one indicating simultaneous_event_follows (see message_link parameter used in read_locator_event and read_choice_event procedures).

Valid information may be read from the queue by using the read_locator_event or read_choice_event procedures.

Since TRUE and FALSE are reserved words in Pascal, integer values 1 and 0 are used instead when calling from Pascal.

Museum

Related Articles