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

NAME

INITIALIZE VALUATOR − initialize a valuator input device using 2D data

SYNOPSIS

C Syntax

void
pinit_val ( ws, dev, init, pet, echo_area, record )
Pintws;workstation identifier
Pintdev;valuator device number
Pfloatinit;initial value
Pintpet;prompt and echo type
Plimit∗echo_area;echo area pointer
Pval_data∗record;data record pointer

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

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

initThe initial valuator value.

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 existing 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 Pval_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.

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

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

Pval_data is defined in phigs.h as:

typedef struct {
Pfloatlow;            /∗ low range limit ∗/
Pfloathigh;           /∗ high range limit ∗/
union {
    struct {
          Pintunused;
    } pet_r1;
    struct {
          Pchar∗label;/∗ the device label widget string ∗/
          Pchar∗format;/∗ the current value widget format string ∗/
          Pchar∗low_label;/∗ the low value widget format string ∗/
          Pchar∗high_label;/∗ the low value widget format string ∗/
    } pet_u1;
} pets;
} Pval_data;

Execution

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

The initial value is the logical input value the device will take on 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 VALUATOR device measure consists of a floating point number. This number is between the device’s low value and high value, inclusive.

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.

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

AVAILABLE DEVICES

Device 1 - Athena Scrollbar Widget

The valuator device realization is a collection of widgets from the Athena widget set. It consists of a Shell widget, a Pane widget, 4 Label widgets and a Scrollbar widget. The Scrollbar is the item manipulated by the operator to change the valuator value. The four Label widgets display a label for the device and labels for each of the current value, low value and high value of the device. The device label, current value and low value are all displayed (by default) to the left of the Scrollbar. The high value is displayed to the right. The Pane, Label, and Scrollbar widgets are children of the Shell widget.

Each of the four Label widgets has a character string associated with it that indicates what to display in that widget. The strings for the current value, low value and high value widgets may contain printf(3) format descriptors. PEX-SI will expand these descriptors with the corresponding device value so that the value appears in the widget. For example, if the low value widget string is “the low value is %f” and the low value is 5, PEX-SI will display the widget as “the low value is 5.0”.

The echo volume is not used for this device.

Prompt/echo types supported: 1, -1

PET 1Display the valuator item as specified above. The string for the label widget is “value.” The strings for the current value, low value, and high value strings are all %8.3g. (Use PET -1 if these values are not as desired.) No data record is used with PET 1.

PET -1Display the valuator item as specified for PET 1 but with application-specified widget strings. The label, low value, and high value strings are specified in the data record.

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

valuator1 → applicationShellWidgetClass

pane → panedWidgetClass

label → labelWidgetClass
readout → labelWidgetClass
low_label → labelWidgetClass
scrollbar → scrollbarWidgetClass
high_label → labelWidgetClass

Fallback resources for valuator devices are specified in the API. They are:

∗valuator1.pane.orientation → horizontal

∗valuator1∗scrollbar.orientation → horizontal

∗valuator1∗scrollbar.length → 50

∗valuator1∗scrollbar.translations —

<Btn1Down> → StartScroll(Continuous) MoveThumb() NotifyThumb()
<Btn1Motion> → MoveThumb() NotifyThumb()
<Btn1Up> → NotifyScroll(Proportional) RequestSatisfied() EndScroll()

∗valuator1∗scrollbar.skipAdjust → FALSE

∗valuator1∗skipAdjust → TRUE

∗valuator1∗showGrip → FALSE

The fully qualified name of all widgets is <appl_name>.workstation<ws_id>.valuator<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.valuator1.pane is the name of the pane widget of valuator device 1 on workstation 1.

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

Museum