NAME

INITIALIZE VALUATOR − initialize a valuator input device

SYNOPSIS

C Syntax

void
pinitval ( 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
Pvalrec∗record;data record pointer

FORTRAN Syntax

SUBROUTINE pinvl ( WKID, VLDNR, IVAL, PET, XMIN, XMAX, YMIN, YMAX, LOVAL, HIVAL,
    LDR, DATREC )
INTEGERWKIDworkstation identifier
INTEGERVLDNRvaluator device number
REALIVALinitial value
INTEGERPETprompt/echo type
REALXMIN, XMAX, YMIN, YMAX echo area in device coordinates
REALLOVAL, HIVALminimal and maximal value
INTEGERLDRdimension of data record array
CHARACTER∗80DATREC(LDR) data record

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 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 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.  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 Pvalrec 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 Pvalerec union for prompt/echo type 1 is record->valpet1_datarec. 

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

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

IVALThe initial valuator value. 

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. 

LOVAL
The minimum value to use for this device.

HIVAL
The maximum value to use for this device.

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 VALUATOR sets the initialization parameters of a VALUATOR 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 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 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 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

Devices 1 through 10 - SunView Sliders

These devices are all SunView slider items contained in the same valuator window.  The valuator window is a separate window from the PHIGS workstation window.  The valuators are placed in a vertical column with device number 1 at the top of the window and device number 10 at the bottom.  The window is only displayed when one of the valuator devices is active, i.e., in EVENT or SAMPLE mode or waiting for a REQUEST to be satisfied.  Individual devices are only displayed within the window when they are active.  The window can be positioned, prior to opening the workstation, by using the workstation type attributes PHIGS_VAL_PANEL_X and/or PHIGS_VAL_PANEL_Y.  See WORKSTATION TYPE SET for more information on these attributes.  The valuator panel is resized to contain all the active devices each time a valuator device becomes active. 

Each valuator has three components: the slider, the label, and the format string.  The slider is the graphical representation of the device, the label is an area at the far left of the slider that should indicate which device it is or what data it corresponds to.  The format string displays the current value of the device and is update with each change made by the operator.  The format string is specified as a C style format string as would be passed to the printf(3) function, e.g., %8.3f.  The label is a character string.  Both these strings are limited to a maximum of 40 characters. 

A length is also part of the data record for the device.  This length is the width, in pixels, of the slider. 

The operator selects a valuator value by positioning the cursor on top of the valuator, depressing the left mouse button, and moving the mouse while holding the left mouse button down.  If the valuator device is in REQUEST mode, the device will trigger when the operator lets up the mouse button.  When the device is in EVENT mode, the device will trigger with each movement of the mouse within the valuator (thus will generate an event for each mouse movement).  In sample mode the device’s measure is changed with each mouse movement made while the left mouse button is depressed.  The device will also trigger when the left mouse button is depressed while the cursor is positioned over either the device’s label or format string.  In these cases the value of the measure will be that displayed in the format string. 

The echo volume is not used for these devices. 

Prompt/echo types supported: 1, -1

PET 1Display the valuator item as specified above.  The label is empty.  The format string is fixed at %8.3g, and the length is fixed at 200 pixels.  Use PET -1 if these values are not as desired. 

C Data Record:

A Pvalpet0001 structure defined in phigs.h as:

typedef struct {
Pfloatlow;/∗ low limit ∗/
Pfloathigh;/∗ high limit ∗/
} Pvalpet0001;

FORTRAN Data Record:

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

PET -1Display the valuator item as specified above.  The label, format string and slider length are specified in the data record. 

C Data Record:

A Puvalpet0001 structure defined in phigs.h as:

typedef struct {
Pfloatlow;/∗ low range limit ∗/
Pfloathigh;/∗ high range limit ∗/
Pintlength;/∗ length of slider in pixels ∗/
Pcharlabel[PHIGS_MAX_VAL_LABEL_LENGTH];/∗ label for slider ∗/
Pcharformat[PHIGS_MAX_VAL_LABEL_LENGTH];/∗ printf() format string ∗/
} Puvalpet0001;

PHIGS_MAX_VAL_LABEL_LENGTH is defined in phigs.h to be 40. 

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 the length of the slider in position IA(1). 

RLThe number of real values = 0. 

SLThe number of character strings = 2. 

LSTRAn array containing the lengths of the label and format strings. 

LSTR(1)
The length of the label string.

LSTR(2)
The length of the format string.

STRAn array containing the length and format strings. 

STR(1)
The label string.

STR(2)
The format string.  Use %w.df for fixed point notation, %w.de for scientific notation, or %w.de for the shorter of the two, where w is the width of the output field and d is the number of decimal places to display. 

Devices 11 through 18 - SunDials

These devices correspond to SunDials 1 through 8, if a Sun dialbox is attached. 

The operator selects a valuator value by turning the appropriate dial.  The trigger for these devices is dial movement.  These devices will only trigger when the cursor is within the display surface of the associated workstation. 

The application may specify the behaviour of each device at the limits defined by its low and high values; each device will either wrap around, or stick at the appropriate limit. 

The threshold of each dial in EVENT mode may also be specified, defining the number of dial clicks that should go by before an event is enqued; this allows the collapsing of events to avoid quick filling of the input queue. 

These devices have no display components; i.e., no prompt and no echo. 

Prompt/echo types supported: 1, -4

PET 1Each dial will wrap around at the limits defined for it, and the EVENT mode threshold is 3.  Use PET -4 if these values are not as desired. 

C Data Record:

A Pvalpet0001 structure defined in phigs.h as:

typedef struct {
Pfloatlow;/∗ low limit ∗/
Pfloathigh;/∗ high limit ∗/
} Pvalpet0001;

FORTRAN Data Record:

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

PET -4The dial behaviour at its defined limits and the EVENT mode threshold are specified in the data record. 

C Data Record:

A Puvalpet0004 structure defined in phigs.h as:

typedef struct {
Pfloatlow;/∗ low range limit ∗/
Pfloathigh;/∗ high range limit ∗/
Pdial_limitsdial_lmt;/∗ wraparound or stick at limits ∗/
Pintthreshold;/∗ number of dial events to collapse into 1 ∗/
} Puvalpet0004;

Pdial_limits is an enumerated type defined in phigs.h as follows:

typedef enum {
PDIAL_WRAPAROUND,
PDIAL_STICK
} Pdial_limits;

FORTRAN Data Record:

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

ILThe number of integers = 2. 

IAAn array of integers with the following values:

IA(1)The dial behaviour at its defined limits.  Valid values as defined in phigs77.h are:

PDIALWRAP
PDIALSTICK

IA(2)The EVENT mode threshold. 

RLThe number of real values = 0. 

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

SEE ALSO

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

Sun Release 4.0  —  Last change: 12 July 1989