await_event(3G)

NAME

await_event − wait for event to occur and be buffered then return class of the 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);

DESCRIPTION

Input Parameters

await_fid Specifies how await_event waits. If await_fid is the file descriptor of an opened graphics input device, wait for events from that device. If await_fid is −1 (minus one), wait for events from any device.

timeout Maximum time, in seconds, to wait for an event. Valid is set to FALSE (0) if time runs out.

Output Parameters

valid Set to TRUE (1) if the event data is valid;
FALSE (0) if the event data is invalid.

class May be one of the following classes: LOCATOR or CHOICE. The integer values assigned for these class designators are found in the Starbase include file used with your program.

Discussion

If await_fid is minus 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, 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, valid is set to FALSE (0), and class is undefined. If an event is found before time runs out, 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