request_locator(3G)

NAME

request_locator, intrequest_locator2d − wait for input device to be triggered then return measured value

SYNOPSIS

C Syntax:

void request_locator ( fildes, ordinal, timeout, valid, x, y, z );
int fildes, ordinal, *valid;
float timeout, *x, *y, *z;

void intrequest_locator2d ( fildes, ordinal, timeout, valid, x, y );
int fildes, ordinal, *valid, *x, *y;
float timeout;

FORTRAN77 Syntax:

subroutine request_locator ( fildes, ordinal, timeout, valid,
x, y, z )
integer*4 fildes, ordinal, valid
real timeout, x, y, z

subroutine intrequest_locator2d ( fildes, ordinal, timeout,
valid, x, y )
integer*4 fildes, ordinal, valid, x, y
real timeout

Pascal Syntax:

procedure request_locator ( fildes, ordinal:integer; timeout:real;
var valid:integer; var x, y, z:real );

procedure intrequest_locator2d ( fildes, ordinal:integer;
timeout:real; var valid, x, y:integer );

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by gopen when an I/O path to a graphics device is opened.

ordinal Logical device number ranging from 1 to number of devices of this class.

timeout Time, in seconds, to wait for a trigger.

Output Parameters

valid TRUE (1 in Pascal) if data is valid.

FALSE (0 in Pascal) if data is invalid (timeout period exceeded or device not initialized). If FALSE, x, y, z is undefined.

x, y, z Set to x, y, and z virtual device coordinate values of the point returned from a locator device.

Discussion

Request_locator returns the measured value of the device specified by fildes and ordinal when a trigger occurs, or when the time period specified by timeout is exceeded. If the request was not previously posted with initiate_request and no request data is ready for this device, it is posted by this call. If a request was previously posted but not yet satisfied, the timeout runs from the time this call was made.

A request can be performed on an input device while it is enabled for event generation. The mode of (events enabled/events disabled) is saved by the device and restored after the request has been satisfied. The request data does not go into the event queue, but into a separate virtual register.

Use inquire_request_status to determine whether a previously posted request is ready.

To discard a request that was previously posted and satisfied, but which has not been read, use request_choice, request_locator, or intrequest_locator2d with a zero timeout and discard the result.

Integer operations are only available when using the INT_XFORM gopen mode. When in 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