READ_CHOICE_EVENT(3G)

NAME

read_choice_event − read a choice event from the top of the 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;

HP-UX COMPATIBILITY

Level: HP-UX/STANDARD

Origin: HP

DESCRIPTION

INPUT PARAMETERS

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

OUTPUT PARAMETERS

choice_fildes
is set to the file descriptor of the device returning the event.
ordinal
is set to the device number returning the event. The maximum device number can be obtained using the inquire_sizes procedure.
value
is set to the value returned from a choice device.
status
is set to one of the defined values:

         EMPTY_NO_OVERFLOW
         NOT_EMPTY_NO_OVERFLOW
         EMPTY_OVERFLOW
         NOT_EMPTY_OVERFLOW.
message_link
is set to one of the defined values:

        SINGLE_EVENT
        SIMULTANEOUS_EVENT_FOLLOWS

DISCUSSION

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, then the call returns a non-zero function value, and the output parameters are undefined.

If there are more simultaneous events in the queue, then 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 dequeued; either of the two EMPTY states indicates that there are no more events currently in the queue. The event queue will hold only 100 events. If the queue is full, then new events will be lost. If events are lost, then the next status returned will indicate OVERFLOW. The overflow flag is then cleared.

There is one event queue for each all devices; all events are entered in the order in which they occured. Simultaneous events are enqueued in an implementation dependent order within their group, with all but the last one indicating SIMULTANEOUS_EVENT_FOLLOWS.

Museum