INITIALIZE STROKE(3P) — Kubota Pacfic Computer Inc. (29 February 1991)

NAME

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

SYNOPSIS

C Syntax

void
pinit_stroke ( ws, dev, init_view_ind, init_stroke, pet, echo_area, record )
Pintws;workstation identifier
Pintdev;stroke device number
Pintinit_view_ind;initial view indicator
Ppoint_list∗init_stroke;initial stroke pointer
Pintpet;prompt and echo type
Plimit∗echo_area;echo area pointer
Pstroke_data∗record;data record pointer

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 state list 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.

init_view_ind
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).

init_stroke
A pointer to a Ppoint_list structure containing the initial stroke. The Ppoint_list structure is defined in phigs.h as follows:

typedef struct {
Pintnum_points;
Ppoint∗points;
} Ppoint_list;

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

points is an array of Ppoint structures specifying the x and y WC of the initial stroke points. 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 area, in Device Coordinates (DC). The z component in the workstation state list is left unchanged. Plimit is defined in phigs.h as follows:

typedef struct {
Pfloatx_min;/∗ minimum x coordinate value ∗/
Pfloatx_max;/∗ maximum x coordinate value ∗/
Pfloaty_min;/∗ minimum y coordinate value ∗/
Pfloaty_max;/∗ maximum y coordinate value ∗/
} Plimit;

recordA pointer to a Pstroke_data structure 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. Pstroke_data is defined in phigs.h as:

Some fields of the record correspond to the prompt/echo type being used.

typedef struct {
Pintbuffer_size;/∗ input buffer size ∗/
Pintinit_pos;/∗ initial editing position ∗/
Pfloatx_interval;/∗ x interval ∗/
Pfloaty_interval;/∗ y interval ∗/
Pfloattime_interval;/∗ time interval ∗/
union {
struct {
Pintunused;
} pet_r1;
struct {
Pintunused;
} pet_r2;
struct {
Pmarker_attrsmarker_attrs; /∗ marker attributes ∗/
} pet_r3;
struct {
Pline_attrsline_attrs;/∗ line attributes ∗/
} pet_r4;
} pets;
} Pstroke_data;

Execution

INITIALIZE STROKE sets the initialization parameters of a STROKE device. This function stores these parameters in the workstation state list 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 initial stroke, prompt/echo type, echo volume, and input data record.

The initial stroke 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) points 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 WC. 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 DC by applying the view orientation and view mapping transforms of the specified view representation, and then applying the workstation transformation. If the view index is invalid, an error is generated.

The prompt/echo type determines how the device will be presented to the operator and respond to his actions. Each device supports one or more prompt/echo types. 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.

The echo volume defines the region of the display surface in which to echo the device. It is specified in DC. Devices that use the echo volume may restrict their display to this region. Some of these devices may still recognize operator input outside the region even though they do not display there. This function specifies only 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 of 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 - Pointer device

This device is associated with the X pointer device. The stroke points in the STROKE device’s measure are the WC points corresponding to the positions specified in an operator-generated series of X pointer events. The operator adds points to the buffer by positioning the cursor to the desired location and depressing the left pointer button. Once all the desired points are selected, the operator presses both the shift key and the left mouse button at the same time. This triggers the stroke. Points can be removed from the buffer by pressing the CONTROL key and pointer button simultaneously. Only points after the edit position can be removed in this way.

Prompt/echo types supported: 1

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.

This device uses the buffer_size and init_pos fields of the stroke data record, Pstroke_data.

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

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

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