INITIALIZE STRING 3(3P) — SUNPHIGS LIBRARY

NAME

INITIALIZE STRING 3 − initialize a STRING input device

SYNOPSIS

C Syntax

void
pinitstring3 ( ws, dev, init, pet, echo_volume, record )
Pintws;workstation identifier
Pintdev;string device number
Pchar∗init;initial string
Pintpet;prompt and echo type
Plimit3∗echo_volume;echo volume pointer
Pstringrec∗record;data record pointer

FORTRAN Syntax

SUBROUTINE pinst3 ( WKID, STDNR, LSTR, ISTR, PET, EVOL, BUFLEN, INIPOS, LDR,
DATREC )
INTEGERWKIDworkstation identifier
INTEGERSTDNRstring device number
INTEGERLSTRlength of the initial string (>= 0)
CHARACTER∗(∗)ISTR initial string
INTEGERPETprompt/echo type
REALEVOL(6)echo volume (DC)
INTEGERBUFLENinput buffer size
INTEGERINIPOSinitial edit position
INTEGERLDRdimension of data record array
CHARACTER∗80DATREC(LDR) data record

FORTRAN Subset Syntax

SUBROUTINE pinst3 ( WKID, STDNR, LSTR, ISTR, PET, EVOL, BUFLEN, INIPOS, LDR,
DATREC )
INTEGERWKIDworkstation identifier
INTEGERSTDNRstring device number
INTEGERLSTRlength of the initial string (>= 0)
CHARACTER∗80ISTR initial string
INTEGERPETprompt/echo type
REALEVOL(6)echo volume (DC)
INTEGERBUFLENinput buffer size
INTEGERINIPOSinitial edit position
INTEGERLDRdimension of data record array
CHARACTER∗80DATREC(LDR) data record

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

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

initA pointer to the initial string. init can be NULL, i.e., (Pchar∗)0.

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

echo_area
A pointer to a Plimit3 structure defining the X, Y and Y components of the echo volume, in Device Coordinates. Plimit3 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 ∗/
Pfloatzmin;/∗ minimum z coordinate value ∗/
Pfloatzmax;/∗ maximum z 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->stringpet1_datarec.

For some prompt/echo types of some STRING 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.

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

LSTRThe length of the initial string.

ISTRThe initial string.

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

EVOLThe X, Y and Z limits of the echo volume, XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX, in Device Coordinates.

BUFLEN
The buffer length of the STRING device.

INIPOS
The edit position.

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 STRING 3 sets the initialization parameters of a STRING 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 STRING device measure consists of a character string.

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.

All the initialization parameters must be properly specified 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 STRING input device can be inquired with the function INQUIRE DEFAULT STRING DEVICE DATA. The current state of the device can be inquired with the function INQUIRE STRING DEVICE STATE.

AVAILABLE DEVICES

Device 1 - SunView Text Subwindow

This device is the text subwindow located below the graphics window of the PHIGS workstation. This window is also used by MESSAGE to display messages sent to the workstation.

The trigger for this device is a CARRIAGE RETURN. The device’s measure corresponds to all the characters added to the text subwindow by the operator since the device was last enabled or the last STRING event was generated. All the usual features of Text Subwindows are available to the operator, i.e., scrolling, cut and paste, write to file, etc.

Keyboard input that occurs while the cursor is in the graphics portion of the PHIGS workstation is directed to the text subwindow if no other device is handling it (such as the keyboard CHOICE device).

The echo volume is ignored by this device.

Prompt/echo types supported: 1

PET 1Display the text in the text subwindow.

C Data Record:

A Pstringpet0001 structure defined in phigs.h as:

typedef struct {
Pintbufsiz;/∗ buffer size ∗/
Pintposition;/∗ initial edit position ∗/
} Pstringpet0001;

FORTRAN Data Record:

All the data record parameters for this PET are passed as function arguments. There is no data record required.

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

263Ignoring function, length of the initial string is greater than the buffer size

Museum