READ_LOCATOR_EVENT(3G)

NAME

read_locator_event − read a locator event from the top of the event queue.

SYNOPSIS

C SYNTAX

int read_locator_event(queue_des,locator_fildes,ordinal,
x,y,z,status,message_link);
int queue_des,*locator_fildes,*ordinal,*status,*message_link;
float *x,*y,*z;

FORTRAN77 SYNTAX

        integer*4 function read_locator_event(queue_des,
        locator_fildes,ordinal,x,y,z,status,message_link)
        integer*4 queue_des,locator_fildes
        integer*4 ordinal,status,message_link
        real x,y,z

PASCAL SYNTAX

function read_locator_event(queue_des:integer;
var locator_fildes,ordinal:integer;var x,y,z:real;
var status,message_link:integer):integer;

HP-UX COMPATIBILITY

Level: HP-UX/STANDARD

Origin: HP

DESCRIPTION

INPUT PARAMETER

queue_des
is either the file descriptor of an opened graphics device, or -1. If queue_des is the file descriptor of an opened graphics device, then the first event for that device is read. If queue_des is -1, then the top event from any input device is read.

OUTPUT PARAMETERS

locator_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.
x,y,z
are set to the point returned from a locator.
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 locator event on top of the event queue, read_locator_event returns the top event. If the queue is empty, or the top event is not a locator 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

Related Articles