NAME

read_choice_event − read choice event from top of event queue

SYNOPSIS

C Syntax:

int read_choice_event ( queue_des, choice_fildes, ordinal, value,
status, message_link );
int queue_des;
int *choice_fildes, *ordinal, *value, *status, *message_link;

FORTRAN77 Syntax:

integer*4 function read_choice_event ( queue_des,
choice_fildes, ordinal, value, status, message_link )
integer*4 queue_des, choice_fildes, ordinal
integer*4 value, status, message_link

Pascal Syntax:

function read_choice_event ( queue_des:integer;
var choice_fildes, ordinal, value,
status, message_link:integer ):integer;

DESCRIPTION

Input Parameters

queue_des File descriptor of an opened graphics device or −1 (minus one).  If it is a file descriptor, the first event for that device is read.  If −1 (minus one), the next event from any input device is read. 

Output Parameters

choice_fildes File descriptor of the device returning the event. 

ordinal Device number returning the event.  To determine maximum device number, use inquire_sizes.

value Value returned from a choice device. 

status Set to one of the following defined values:

EMPTY_NO_OVERFLOW
NOT_EMPTY_NO_OVERFLOW
EMPTY_OVERFLOW
NOT_EMPTY_OVERFLOW.

message_link Set to one of the defined values:

SINGLE_EVENT
SIMULTANEOUS_EVENT_FOLLOWS

Discussion

If there are more simultaneous events in the queue, message_link is set to SIMULTANEOUS_EVENT_FOLLOWS. Otherwise, message_link is set to SINGLE_EVENT.

Status is set to the state of the queue after the current event report has been removed from the queue (either of the two EMPTY states indicates that there are no more events currently in the queue).  The event queue can hold up to 100 events.  If the queue is full, any new events are lost.  If events are lost, the next status returned indicates OVERFLOW and the overflow flag is cleared. 

A single event queue services all devices and events are entered into the queue in the chronological order in which they occur.  The order in which simultaneous events are queued is implementation-dependent, but each simultaneous event entry in the queue, except for the last entry, indicates SIMULTANEOUS_EVENT_FOLLOWS. 

RETURN VALUE

If there is a choice event on top of the event queue, read_choice_event returns the top event.  If the queue is empty or the top event is not a choice event, the call returns a non-zero function value and the output parameters are undefined. 
 

SEE ALSO

read_locator_event(3G). 

Hewlett-Packard Company  —  November 03, 1994