NAME

INITIALIZE LOCATOR − initialize a LOCATOR input device using 2D data

SYNOPSIS

C Syntax

void
pinitloc ( ws, dev, init, pet, echo_area, record )
Pintws;workstation identifier
Pintdev;locator device number
Ploc∗init;initial locator pointer
Pintpet;prompt and echo type
Plimit∗echo_area;echo area pointer
Plocrec∗record;data record pointer

FORTRAN Syntax

SUBROUTINE pinlc ( WKID, LCDNR, IVIEWI, IPX, IPY, PET, XMIN, XMAX, YMIN, YMAX,
    LDR, DATREC )
INTEGERWKIDworkstation identifier
INTEGERLCDNRlocator device number
INTEGERIVIEWIinitial view index
REALIPX, IPYinitial locator position (WC)
INTEGERPETprompt/echo type
REALXMIN, XMAX, YMIN, YMAX echo area in device coordinates
INTEGERLDRdimension of data record array
CHARACTER∗80DATREC(LDR) data record

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use INITIALIZE LOCATOR to set the initialization parameters of a LOCATOR device.  This function stores these parameters in the workstation description table of the workstation associated with the specified device.  The specified device must be in REQUEST mode when this function is called. 

C Input Parameters

wsThe workstation identifier of the workstation associated with the device. 

devThe device number of the LOCATOR device to initialize.  See the Available Devices section below for a description of the available devices. 

initA pointer to a Ploc structure containing the initial locator position and view index.  The Ploc structure is defined in phigs.h as follows:

typedef struct {
Pintview_index;
Ppointposition;
} Ploc;

The view index is the index of the view representation in the workstation’s view table to use to map the specified initial position from World Coordinates (WC) to Normalized Projection Coordinates (NPC). 

The position is a Ppoint structure specifying the x and y World Coordinates of the initial locator position.  The z component in the workstation state list is left unchanged.  Ppoint is defined in phigs.h as follows:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
} Ppoint;

petThe prompt/echo type desired.  Those supported by each device are listed in the Available Devices section below. 

echo_area
A pointer to a Plimit structure defining the x and y components of the echo volume, in Device Coordinates.  The z component in the workstation state list is left unchanged.  Plimit is defined in phigs.h as follows:

typedef struct {
Pfloatxmin;/∗ minimum x coordinate value ∗/
Pfloatxmax;/∗ maximum x coordinate value ∗/
Pfloatymin;/∗ minimum y coordinate value ∗/
Pfloatymax;/∗ maximum y coordinate value ∗/
} Plimit;

recordA pointer to a Plocrec union containing the data record information.  The contents of the data record for each device and prompt/echo type are described below in the Available Devices section. 

The members of the data record union correspond to the prompt/echo type being used.  As an example, the appropriate member of the Plocerec union for prompt/echo type 1 is record−>locpet1_datarec. 

For some prompt/echo types of some LOCATOR devices the data record is not used.  The record parameter, however, must still be passed. 

FORTRAN Input Parameters

WKIDThe workstation identifier of the workstation associated with the device. 

LCDNR
The device number of the LOCATOR device to initialize.  See the Available Devices section below for a description of the available devices. 

IVIEWI
The view index of the view representation in the workstation’s view table to use to map the specified initial position from World Coordinates (WC) to Normalized Projection Coordinates (NPC). 

IPX, IPY
The x and y world coordinates of the initial locator position.  The z component in the workstation state list is left unchanged. 

PETThe prompt/echo type desired.  Those supported by each device are listed in the Available Devices section below. 

XMIN, XMAX, YMIN, YMAX
The x and y components of the echo volume, in Device Coordinates.  The z component in the workstation state list is left unchanged. 

LDRThe dimension of the data record array. 

DATREC
A packed data record, built by PACK DATA RECORD, containing the input data record information.  The contents of the data record for each device and prompt/echo type are described below in the Available Devices section. 

Execution

INITIALIZE LOCATOR sets the initialization parameters of a LOCATOR device.  This function stores these parameters in the workstation description table of the workstation associated with the specified device.  The specified device must be in REQUEST mode when this function is called. 

The parameters that are initialized by this function are the initial measure, prompt/echo type, echo volume and input data record. 

The initial measure is the logical input value the device will be set to whenever it is enabled.  The device’s measure will retain this value until operator input changes it.  A device is enabled when the appropriate REQUEST function is called, or when its input mode is set to SAMPLE or EVENT. 

A LOCATOR device measure consists of a position and a view index.  Position is the World Coordinate (WC) point corresponding to the position on the workstation selected by the operator.  The view index is the index of the view representation used to transform the locator position from Normalized Projection Coordinates (NPC) to World Coordinates.  This view representation is determined by selecting the highest priority representation that contains the locator position within its NPC limits.  See SET VIEW TRANSFORMATION INPUT PRIORITY for more information.  The workstation transform is used to transform the operator-selected position from Device Coordinates (DC) to NPC. 

The initial locator position is transformed to Device Coordinates by applying the view orientation and view mapping transforms of the specified view representation, then applying the workstation transformation.  If the view index is invalid an error will be generated. 

The prompt/echo type determines the display characteristics of the device, i.e., how it will be presented to the operator and respond to his actions.  Each device supports one or more prompt/echo type.  Those supported by each device are listed in the device’s description in the Available Devices section below.  All devices support prompt/echo type 1.  Positive prompt/echo types are defined by the PHIGS Standard.  Negative types are implementation dependent.  Most SunPHIGS input devices support both positive and negative prompt/echo types. 

The echo volume defines the region of the display surface in which to echo the device.  It is specified in Device Coordinates (DC).  Devices that use the echo volume will restrict their display to this region.  Some of these devices will still recognize operator input outside the region even though they don’t display there.  This function only specifies the x and y components of the echo volume.  The existing z component in the workstation state list is left unchanged. 

The input data record contains the prompt/echo type specific information that controls the device’s appearance and characteristics.  Not all the data record contents are used by some devices.  The device descriptions in the Available Devices section below list the data record contents that each device recognizes. 

All the initialization parameters must be specified properly or this function will generate an error.  The ERRORS section below lists the possible error conditions. 

The default initialization parameters and the list of prompt/echo types supported by a LOCATOR input device can be inquired with the function INQUIRE DEFAULT LOCATOR DEVICE DATA.  The current state of the device can be inquired with the function INQUIRE LOCATOR DEVICE STATE. 

AVAILABLE DEVICES

Device 1 - Cursor and Left Mouse Button

Device 2 - Cursor and Middle Mouse Button

Device 3 - Cursor and Right Mouse Button

Device 4 - Mouse Movement

Device 5 - Mouse Movement While Any Mouse Button Down (Drag)

These devices are all associated with the mouse and cursor.  The locator position in the LOCATOR device’s measure is the World Coordinate position corresponding to the cursor position when the device is triggered.  The trigger for devices 1, 2 and 3 is a down stroke of the associated mouse button.  The trigger for devices 4 and 5 is mouse movement. 

When in EVENT mode, devices 4 and 5 can easily generate hundreds of events in a few seconds, and they will fill the input queue quickly if it is not monitored continuously and the events removed immediately.  These devices do not provide acknowledgement (cursor blink) to the operator when they place an event on the input queue, as the other devices do. 

Not all prompt/echo types use the initial locator position.  Only those that need an additional point to the current cursor position use the initial position, PET’s -4 and -5, for instance.  No prompt/echo type moves the cursor to the initial position when the device is enabled.  The operator is in complete control of the cursor position. 

The LOCATOR echo will be removed from the workstation when the cursor leaves the echo volume.  Only the x and y components of the echo volume are used.  The z component is ignored. 

Prompt/echo types supported: 1, 2, 3, -2 (coloured crosshairs), -4 (rubberband line), -5 (rubberband rectangle)

PET 1Display the default cursor at the current locator position. 

The data record is not used for this PET. 

PET 2Display crosshairs that intersect at the current locator position and extend to the edges of the workstation’s display surface.  The crosshair colour is that of colour index 1 in the workstation’s colour table.  (PET -2 also uses crosshairs and allows their colour to be specified.) 

The data record is not used for this PET. 

PET 3Display a cross cursor at the current locator position. 

The data record is not used for this PET. 

PET -2Display crosshairs that intersect at the current locator position and extend to the edges of the workstation’s display surface.  The crosshair colour index is specified in the data record. 

C Data Record:

A Pulocpet0002 structure defined in phigs.h as:

typedef struct {
Pintcrosshair_colour;/∗ colour index ∗/
} Pulocpet0002;

FORTRAN Data Record:

The arguments passed to PACK DATA RECORD for this prompt/echo type’s data record should be:

ILThe number of integers = 1. 

IAContains one integer value in position IA(1) specifying the colour of the crosshairs. 

RLThe number of real values = 0. 

SLThe number of strings = 0. 

PET -4Display a "rubber banding" line connecting the initial locator position to the current locator position.  The line attributes are specified in the data record. 

C Data Record:

A Pulocpet0004 structure defined in phigs.h as:

typedef struct {
Plnbundlln_bundl;/∗ line type, width and colour index ∗/
} Pulocpet0004;

FORTRAN Data Record:

The arguments passed to PACK DATA RECORD for this prompt/echo type’s data record should be:

ILThe number of integers = 2. 

IAAn array of integers with the following values:

IA(1)The line type of the rubberband line. 

IA(2)The colour of the rubberband line. 

RLThe number of real values = 1. 

RAContains one real value in position RA(1) specifying the line width scale factor of the rubberband line. 

SLThe number of strings = 0. 

PET -5Display "rubber banding" edges of a rectangle, the diagonal of which connects the initial locator position to the current locator position.  The line attributes of the edges are specified in the data record. 

C Data Record:

A Pulocpet0005 structure defined in phigs.h as:

typedef struct {
Plnbundlln_bundl;/∗ line type, width and colour index ∗/
} Pulocpet0005;

FORTRAN Data Record:

The arguments passed to PACK DATA RECORD for this prompt/echo type’s data record should be:

ILThe number of integers = 2. 

IAAn array of integers with the following values:

IA(1)The line type of the rubberband rectangle. 

IA(2)The colour of the rubberband rectangle. 

RLThe number of real values = 1. 

RAContains one real value in position RA(1) specifying the line width scale factor of the rubberband rectangle. 

SLThe number of strings = 0. 

ERRORS

003Ignoring function, function requires state (PHOP, WSOP, ∗, ∗)

054Ignoring function, the specified workstation is not open

061Ignoring function, specified workstation is neither of category INPUT nor of category OUTIN

250Ignoring function, the specified device is not available on the specified workstation

251Ignoring function, the function requires the input device to be in REQUEST mode

254Ignoring function, invalid echo area/volume; XMIN ≥ XMAX, YMIN ≥ YMAX, or ZMIN > ZMAX

255Ignoring function, one of the echo area/volume boundary points is outside the range of the device

260Ignoring function, one of the fields within the input device data record is in error

253Warning, the specified prompt/echo type is not available on the specified workstation.  Prompt/echo type one will be used in its place

261Ignoring function, initial value is invalid

114Ignoring function, the view index value is less than zero

SEE ALSO

ESCAPE -4 (3P)
SET LOCATOR MODE (3P)
REQUEST LOCATOR (3P)
SAMPLE LOCATOR (3P)
GET LOCATOR (3P)
INQUIRE LOCATOR DEVICE STATE (3P)
INITIALIZE LOCATOR 3 (3P)

Sun Release 4.0  —  Last change: 10 July 1989