read_locator_event(3G)

NAME

read_locator_event − read locator event from top of 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;
int intread_locator_event2d(queue_des,locator_fildes,ordinal,
x,y,status,message_link);
int queue_des,*locator_fildes,*ordinal,*status,*message_link;
int *x,*y;

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
integer*4 function intread_locator_event(queue_des,
locator_fildes,ordinal,x,y,status,message_link)
integer*4 queue_des,locator_fildes
integer*4 ordinal,status,message_link
integer*4 x,y

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;
function intread_locator_event2d(queue_des:integer;
int locator_fildes,ordinal:integer;var x,y:integer;
int status,message_link:integer):integer;

DESCRIPTION

Input Parameters

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

Output Parameters

locator_fildes File descriptor of the device returning the event.

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

x,y,z Point returned from a locator.

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

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 cronological 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.

Integer operations are only available when using the INT_XFORM gopen mode. When in the INT_XFORM mode, floating point operations are not available for that fildes. Floating point operations are the default, or can be specified with FLOAT_XFORM mode. For a list of integer operations, floating point operations, and common operations, see the starbase.3g manual page.

Museum

Related Articles