NAME

INITIALIZE STROKE − initialize a stroke input device using 2D data

SYNOPSIS

C Syntax

void
pinitstroke ( ws, dev, init, pet, echo_area, record )
Pintws;workstation identifier
Pintdev;stroke device number
Pstroke∗init;initial stroke pointer
Pintpet;prompt and echo type
Plimit∗echo_area;echo area pointer
Pstrokerec∗record;data record pointer

FORTRAN Syntax

SUBROUTINE pinsk ( WKID, SKDNR, IVIEWI, N, IPX, IPY, PET, XMIN, XMAX, YMIN, YMAX,
    BUFLEN, LDR, DATREC )
INTEGERWKIDworkstation identifier
INTEGERSKDNRstroke device number
INTEGERIVIEWIinitial view index
INTEGERNnumber of points in initial stroke
REALIPX(∗), IPY(∗)points in initial stroke (WC)
INTEGERPETprompt/echo type
REALXMIN, XMAX, YMIN, YMAX echo area in device coordinates
INTEGERBUFLENinput buffer size
INTEGERLDRdimension of data record array
CHARACTER∗80DATREC(LDR) data record

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use INITIALIZE STROKE to set the initialization parameters of a STROKE 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 STROKE device to initialize.  See the Available Devices section below for a description of the available devices. 

initA pointer to a Pstroke structure containing the initial stroke and view index.  The Pstroke3 structure is defined in phigs.h as follows:

typedef struct {
Pintview_index;
Pintn_points;
Ppoint∗points;
} Pstroke;

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

points is an array of Ppoint structures specifying the X and Y World Coordinates of the initial stroke points.  Ppoint is defined in phigs.h as follows:

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

n_points is the number of point in the initial stroke.  This must be less than or equal to the buffer size specified in the input data record, record. 

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 area, in Device Coordinates.  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 Pstrokerec 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 Pstrokeerec union for prompt/echo type 1 is record->strokepet1_datarec. 

For some prompt/echo types of some STROKE 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 STROKE 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 stroke points from World Coordinates (WC) to Normalized Projection Coordinates (NPC). 

IPX, IPY
Arrays of X and Y world coordinate values specifying the initial stroke points. 

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 limits of the echo volume, in Device Coordinates. 

BUFLEN
The buffer length of this device’s buffer.

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 STROKE sets the initialization parameters of a STROKE 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 STROKE device measure consists of points and a view index.  The points are World Coordinate (WC) point corresponding to the positions on the workstation selected by the operator.  The view index is the index of the view representation used to transform the stroke positions from Normalized Projection Coordinates (NPC) to World Coordinates.  This view representation is determined by selecting the highest priority representation that contains all the stroke positions within its NPC limits.  See SET VIEW TRANSFORMATION INPUT PRIORITY for more information.  The workstation transform is used to transform the operator-selected positions from Device Coordinates (DC) to NPC. 

The initial stroke points are 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. 

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. 

Stroke devices contain a buffer in which to store the points selected by the operator.  Points are added to the buffer starting at the edit position.  Both the buffer size and the edit position are specified in the input data record. 

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 STROKE input device can be inquired with the function INQUIRE DEFAULT STROKE DEVICE DATA.  The current state of the device can be inquired with the function INQUIRE STROKE 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

These devices are all associated with the mouse and cursor.  The stroke points in the STROKE device’s measure are the World Coordinate points corresponding to the cursor positions the operator has selected.  The operator adds points to the buffer by positioning the cursor to the desired location and depressing the appropriate mouse button.  Once all the desired points are selected this way the operator presses both the shift key and the appropriate mouse button at the same time.  This will trigger the stroke.  Points can be removed from the buffer by pressing the CONTROL key and mouse button simultaneously.  Only points after the edit position can be removed in this way. 

The STROKE 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, -3, -4

PET 1Display the stroke points by drawing a marker at each stroke position.  The marker used is of marker type 3 (asterisk), size 1.0 and uses colour index 1. 

C Data Record:

A Pstrokepet0001 structure defined in phigs.h as:

typedef struct {
Pintbufsiz;/∗ input buffer size ∗/
Pinteditpos;/∗ editing position ∗/
Ppoint3interval;/∗ x, y, z interval ∗/
Pfloattime;/∗ time interval ∗/
} Pstrokepet0001;

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 edit position. 

RLThe number of real values = 4. 

RAAn array of reals containing:

RA(1)The X value of the space interval. 

RA(2)The Y value of the space interval. 

RA(3)The Z value of the space interval. 

RA(4)The time interval. 

All these values should be 0; neither the space nor the time intervals are currently used by any stroke device. 

SLThe number of strings = 0. 

PET -3Display the stroke points by drawing a marker at each stroke position.  The marker attributes to use are specified in the data record. 

C Data Record:

A Pustrokepet0003 structure defined in phigs.h as:

typedef struct {
Pintbufsiz;/∗ input buffer size ∗/
Pinteditpos;/∗ editing position ∗/
Ppoint3interval;/∗ x, y, z interval ∗/
Pfloattime;/∗ time interval ∗/
Pmkbundlmk_bundl;/∗ marker attributes ∗/
} Pustrokepet0003;

FORTRAN Data Record:

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

ILThe number of integers = 3. 

IAContains three integer values:

IA(1)The edit position. 

IA(2)The marker type. 

IA(3)The marker colour index. 

RLThe number of real values = 5. 

RAAn array of reals containing:

RA(1)The X value of the space interval. 

RA(2)The Y value of the space interval. 

RA(3)The Z value of the space interval. 

RA(4)The time interval. 

RA(5)The marker size. 

All the interval values should be 0; neither the space nor the time intervals are currently used by any stroke device. 

SLThe number of strings = 0. 

PET -4Display the stroke points by drawing a line between each stroke point.  The line attributes to use are specified in the data record. 

C Data Record:

A Pustrokepet0004 structure defined in phigs.h as:

typedef struct {
Pintbufsiz;/∗ input buffer size ∗/
Pinteditpos;/∗ editing position ∗/
Ppoint3interval;/∗ x, y, z interval ∗/
Pfloattime;/∗ time interval ∗/
Plnbundlln_bundl;/∗ line attributes ∗/
} Pustrokepet0004;

FORTRAN Data Record:

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

ILThe number of integers = 3. 

IAContains three integer values:

IA(1)The edit position. 

IA(2)The line type. 

IA(3)The line colour index. 

RLThe number of real values = 5. 

RAAn array of reals containing:

RA(1)The X value of the space interval. 

RA(2)The Y value of the space interval. 

RA(3)The Z value of the space interval. 

RA(4)The time interval. 

RA(5)The line size. 

All the interval values should be 0; neither the space nor the time intervals are currently used by any stroke device. 

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

262Ignoring function, number of points in the initial stroke is greater than the buffer size

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

SEE ALSO

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

Sun Release 4.0  —  Last change: 10 July 1989