AWAIT EVENT(3P) — Kubota Pacfic Computer Inc. (29 February 1991)

NAME

AWAIT EVENT − move event from input queue to current event report

SYNOPSIS

C Syntax

void
pawait_event ( timeout, ws_id, class, in_num )
Pfloattimeout;timeout ( seconds )
Pint∗ws_id;OUT workstation identifier
Pin_class∗class;OUT device class
Pint∗in_num;OUT logical input device number

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

If the input event queue is not empty, AWAIT EVENT moves the next event in the queue to the current event report in the PHIGS state list. It returns the workstation identifier, input class, and input device number of the input device that generated the event.

If the input queue is empty, AWAIT EVENT suspends PHIGS until an event is entered into the queue or the time specified by timeout has elapsed.

C Input Parameters

timeout
The time, in seconds, to wait for an event if none are present in the input queue.

C Output Parameters

ws_idIf the event queue is not empty, PHIGS sets the variable pointed to by ws_id to the identifier of the workstation that was the source of the input event. If the queue is empty, PHIGS does not set this variable.

classIf the event queue is not empty, PHIGS sets the variable pointed to by class to the class of the device that generated the input event. If the queue is empty, PHIGS sets this variable to PIN_NONE. Pin_class is an enumerated type that may take the following values:

typedef enum {
PIN_NONE,
PIN_LOC,
PIN_STROKE,
PIN_VAL,
PIN_CHOICE,
PIN_PICK,
PIN_STRING
} Pin_class;

in_num
A pointer to an integer variable. If the event queue is not empty, PHIGS sets this variable to the identifier of the input device that generated the input event.

Execution

The AWAIT EVENT function writes the logical input value of the oldest input event in the input queue to the current event report in the PHIGS state list. The workstation id, device class, and device number of the input device that generated the event are returned in the output parameters. The current event report is accessed by the appropriate GET device class function; for example, GET LOCATOR or GET STRING.

If there are no events in the input queue when AWAIT EVENT is called, AWAIT EVENT does not return until an event is added to the queue or until the time specified by the timeout parameter has elapsed. If a timeout occurs, PIN_NONE is returned as the device class and the other two values, workstation id and device number, are undefined.

Window system events such as repaints and resizes, and events for all active input devices are processed as usual while AWAIT EVENT is waiting for a timeout to expire.

While the timeout can be any positive floating-point value, the effective timeout resolution depends on the operating system in use.

ERRORS

003Ignoring function, function requires state (PHOP, WSOP, ∗, ∗)

256Warning, the input queue has overflowed

Museum