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

NAME

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

SYNOPSIS

C Syntax

void
pinit_string ( ws, dev, init, pet, echo_area, record )
Pintws;workstation identifier
Pintdev;string device number
char∗init;initial string
Pintpet;prompt and echo type
Plimit∗echo_area;echo area pointer
Pstring_data∗record;data record pointer

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

INITIALIZE STRING sets the initialization parameters of a STRING 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 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, that is, (char∗)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 Plimit structure defining the x and y components of the echo volume, 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 Pstring_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.

The members of the data record union correspond to the prompt/echo type being used. As an example, the appropriate member of the Pstring_data structure for prompt/echo type 1 is pet_r1.

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

Pstring_data3 is defined in phigs.h as follows:

typedef struct {
Pintbuffer_size;/∗ input buffer size ∗/
Pintinit_pos;/∗ initial editing position ∗/
union {
struct {
Pintunused;
} pet_r1;
} pets;
} Pstring_data;

Execution

INITIALIZE STRING sets the initialization parameters of a STRING 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 string, prompt/echo type, echo volume, and input data record.

The initial string is the logical input value the device will take on whenever it is enabled. The device’s measure retains 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 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 Device Coordinates (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 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 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.

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 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 - Athena Ascii Text Widget

The string device realization is a collection of widgets from the Athena widget set. It consists of a Shell widget, a Viewport widget, and an AsciiText widget. The AsciiText widget is the item manipulated by the operator to change the string value.

String device events are generated by a carriage return. A carriage return also invokes the RequestSatisfied action. The device’s measure corresponds to all the characters added to the widget by the operator since the device was last enabled or the last STRING event was generated. The string device has the following translation defined:

<Key>Return → newline() StringEvent() RequestSatisfied()

The single prompt/echo type supported is 1.

The widgets used and their names, in decreasing hierarchy, are:

string1 → applicationShellWidgetClass

viewport → viewportWidgetClass

text → asciiTextWidgetClass

Fallback resources for string devices are:

∗string1∗Text∗width → 400

∗string1∗Text∗height → 50

∗string1∗Text∗editType → edit

∗string1∗Text∗scrollVertical → never

∗string1∗Text∗scrollHorizontal → never

∗string1∗Text∗autoFill → on

The fully qualified name of all widgets is <appl_name>.workstation<ws_id>.string<dev_id>.<widget_name>, where <appl_name> is the application name specified in the call to OPEN XPHIGS. (This will be "phigs" if OPEN XPHIGS was not called.) For example, phigs.workstation1.string.viewport is the name of the pane widget of string device 1 on workstation 1.

This device does not use the PHIGS echo area. Applications or users can specify the position of the devices (subject to window manager control) by specifying the appropriate resource values in a resource file.

The echo volume is ignored by this device. The buffer_size and init_pos fields of the data record are used by this device.

Prompt/echo types supported: 1

PET 1Display the text in the widget.

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

261Ignoring function, initial value is invalid

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

Museum