NAME

INITIALIZE CHOICE 3 − initialize a CHOICE input device

SYNOPSIS

C Syntax

void
pinitchoice3 ( ws, dev, status, init, pet, echo_volume, record )
Pintws;workstation identifier
Pintdev;choice device number
Pchoicestatusstatus;initial choice status
Pintinit;initial choice
Pintpet;prompt and echo type
Plimit3∗echo_volume;echo volume pointer
Pchoicerec∗record;data record pointer

FORTRAN Syntax

SUBROUTINE pinch3 ( WKID, CHDNR, ISTAT, ICHNR, PET, EVOL, LDR, DATREC )
INTEGERWKIDworkstation identifier
INTEGERCHDNRchoice device number
INTEGERISTATinitial status (POK, PNCHOI)
INTEGERICHNRinitial choice number
INTEGERPETprompt/echo type
REALEVOL(6)echo volume (DC)
INTEGERLDRdimension of data record array
CHARACTER∗80DATREC(LDR) data record

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

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

statusThe CHOICE status of the initial measure.  Pchoicestatus is an enumerated data type defined in phigs.h as follows:

typedef enum {
PCH_OK,
PCH_NOCHOICE
} Pchoicestatus;

initThe initial choice number.  This value is ignored if status is PCH_NOCHOICE. 

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

echo_volume
A pointer to a Plimit3 structure defining the x, y and z 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 ∗/
} Plimit3;

recordA pointer to a Pchoicerec 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 Pchoicerec union for prompt/echo type 1 is record->choicepet1_datarec. 

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

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

ISTATThe choice status of the initial measure.  Valid values as defined in phigs77.h are:

•  POK(OK)
•  PNCHOI(NO CHOICE)

ICHNR
The initial choice number. This value is ignored if ISTAT is PNCHOI. 

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. 

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 CHOICE 3 sets the initialization parameters of a CHOICE 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 CHOICE device measure consists of a status and a choice number.  Status indicates whether or not one of the possible choice values on the device was selected.  (It’s possible to trigger some CHOICE devices without selecting one of the choices.)  The choice number indicates the value selected, if any. 

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

AVAILABLE DEVICES

Devices 1, 2, 3 - SunView Menus

These devices are SunView pop-up menus, triggered by the mouse buttons.  Depressing the mouse button and holding it down will cause the menu to be displayed and allow the operator to move the cursor over any of the available choices.  He selects a choice value by releasing the mouse button while the cursor is over the desired choice value.  Releasing the mouse button while the cursor is not over the menu will cause the choice status to be set to NO CHOICE. 

If an initial choice is specified, the cursor will move to that choice value when the menu appears.  The operator need only release the mouse button to select that value. 

The echo volume is not used by these devices. 

Prompt/echo types supported: 1, 3

PET 1Display a SunPHIGS-defined list of choice strings in the menu.  The choice strings are the integers 1 through 10. 

The data record is not used for this PET. 

PET 3Display an application-specified list of choice strings in the menu.  The data record contains the number and array of choice strings. 

C Data Record:

A Pchoicepet0003 structure defined in phigs.h as:

typedef struct {
Pintnumber;/∗ number of choice strings ∗/
Pchar∗∗strings;/∗ array of choice strings ∗/
} Pchoicepet0003;

FORTRAN Data Record:

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

ILThe number of integers = 0. 

RLThe number of real values = 0. 

SLThe number of choice strings. 

LSTRAn array of integers, each entry specifying the length of the corresponding character string in STR. 

STRThe array of choice strings. 

Devices 4 through 9 - SunPHIGS Pop-up Devices

These devices are SunPHIGS pop-up devices, triggered by the left mouse button; the structure named in the choice data record is displayed in the echo volume when the device is active.  When the operator picks a primitive in the displayed structure, the pick identifier associated with it is sequentially mapped to a choice value using the list of pick identfiers in the data record.  A pick identifier that is not listed in the data record maps to NO CHOICE. 

The specified structure is interpreted during device initialization for later use as a prompt, after which no logical connection exists between it and the structure of the same name in the Central Structure Store. 

Prompt/echo types supported: 1, 5

PET 1This PET is not yet supported. 

The data record is not used for this PET. 

PET 5Display an application-specified structure in the echo area.  The data record contains the structure identifier, and the number and array of pickids to be mapped to choice numbers. 

C Data Record:

A Pchoicepet0005 structure defined in phigs.h as:

typedef struct {
Pintstruct_id;/∗ struct identifier ∗/
Pintnumber;/∗ number of alternatives ∗/
Pint∗pickids;/∗ array of pick identifiers ∗/
} Pchoicepet0005;

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 + the number of pick identifiers. 

IAAn array of integers with the following values:

IA(1)The structure identifier. 

IA(2) - IA(IL)
The array of pick identifiers.

RLThe number of real values = 0. 

SLThe number of strings = 0. 

Device 11 - Keyboard

This device consists of the ASCII and cursor control keys on the Sun keyboard.  The choice number is the ASCII value of the key struck by the operator.  The cursor key values correspond to the three-byte ANSI escape sequence of the key hit.  This sequence is encoded in the CHOICE value in the rightmost three bytes.  Constants are defined in phigs.h and phigs77.h (FORTRAN) to distinguish these values.  These constants are:

C ConstantFORTRANKey
PCURSOR_KEY_UPPCRSUPUp
PCURSOR_KEY_DOWNPCRSDN Down
PCURSOR_KEY_LEFTPCRSLF Left
PCURSOR_KEY_RIGHTPCRSRT Right

Prompt/echo types supported: 1

PET 1The device has no display components, i.e., no prompt and no echo. 

The data record is not used for this PET. 

Device 10 - Mouse Buttons

Device 12 - Left Function Keys

Device 13 - Top Function Keys

Device 14 - Right Function Keys

These devices are the mouse buttons and function keys.  The choice number is the id of the key struck, possibly modified according to the state of the Shift and Control keys.  The id of a key is its position in its respective set of keys, e.g., the id of the key labelled L6 on the Sun keyboard is 6.  The mouse buttons are numbered 1, 2, 3 from left to right.  Function keys struck while the Shift or Control keys are depressed are distinct from the un-shifted and un-control-ed keystroke.  In addition, mouse button values indicate whether they were generated by an up or down stroke. 

Prompt/echo types supported: 1

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

The data record is not used for this PET. 

The current keyboard setting may inhibit the generation of some function key events.  For instance, the cursor keys will not generate events for the right keypad if the Sun default keyboard mapping is used.  Likewise, L1 generates a WIN_STOP event by default, thus will not generate an event for the left keypad. 

Shifted and control-ed mouse and function keys are identified by encoding in the value both the key number and the fact that it is shifted or control-ed.  In addition, mouse button up-stroke values are encoded to indicate they were generated by an up stroke.  The following C macros and FORTRAN functions, defined in phigs.h and phigs77.h respectively, can be used to determine the coded value:

C Macros

PFCN_KEY_VALUE( choice_value )
returns the key number of the key, ignoring the Shift or Control key state.

PFCN_KEY_SHIFTED( key_id )
returns the choice value that is generated for the shifted key.

PFCN_KEY_CTRLED( key_id )
returns the choice value that is generated for the control-ed key.

PFCN_KEY_UP( key_id )
returns the choice value that is generated for the mouse button up stroke.

PFCN_KEY_IS_SHIFTED( choice_value )
returns 1 if the value is a shifted value, otherwise it returns 0.

PFCN_KEY_IS_CTRLED( choice_value )
returns 1 if the value is a control-ed value, otherwise it returns 0.

PFCN_KEY_IS_UP( choice_value )
returns 1 if the value was generated by an up stroke, otherwise it returns 0.

FORTRAN Functions
These functions correspond to the C macros described above.

pfcnkeyvalue( choice_value : integer )
pfcnkeyshifted( key_id : integer )
pfcnkeyctrled( key_id : integer )
pfcnkeyup( key_id : integer )
pfcnkeyisshifted( choice_value : integer )
pfcnkeyisctrled( choice_value : integer )
pfcnkeyisup( choice_value : integer )

All function key choice values will be in one of the following ranges:

un-shifted/un-control-ed:1 through number of choices
shifted:PFCN_KEY_SHIFTED(1) through PFCN_KEY_SHIFTED(num choices)
control-ed:PFCN_KEY_CTRLED(1) through PFCN_KEY_CTRLED(num choices)

These ranges are not contiguous; however, the key values within each range are. 

The number of choices field in the workstation description table reflects only the number of possible keys; the shifted and control-ed values are not included in this number. 

Device 15 - Software Button Box

This device is a software simulation of a 32 key button box.  It appears as a pop-up window when the device is active, i.e., in EVENT or SAMPLE mode or waiting for a REQUEST to be satisfied.  The lower-left corner of the pop-up window is mapped to the lower-left corner of the echo volume. 

Prompt/echo types supported: 1, -2

PET 1All 32 buttons will be active while the device is active; the keys are labelled with default strings from 1 to 32. 

The data record is not used for this PET. 

PET -2The buttons specified by the application will be active while the device is active; a button is active if it has a non-blank label string.  A blank label string may contain from one to four blanks, or in C may be specified simply as a null string.  The data record contains the number and array of 4-character labels; label strings greater than four characters will be truncated.  The data record also contains the colours for the foreground (label strings and key outlines) and background (keys) to be used when displaying this device.  If less than 32 values are specified, the first n buttons will be set as specified, and the remainder will be inactive. 

A general colour representation is used allowing both direct and indirect colour specification; however only the indirect and RGB direct colour types are supported. 

C Data Record:

A Puchoicepet0002 structure defined in phigs.h as:

typedef struct {
Pintnumber;/∗ number of choice strings ∗/
Pchar∗∗strings;/∗ array of choice strings ∗/
Pgcolrfore_colour;/∗ foreground colour ∗/
Pgcolrback_colour;/∗ background colour ∗/
} Puchoicepet0002;

Pgcolr is defined in phigs.h as:

typedef struct {
      Pint             type;          /∗ indirect, RGB, CIE, HSV, HLS ∗/
      union {
         Pint         index;          /∗ colour table index ∗/
         struct {
              Pfloat          x;              /∗ red, hue, etc. ∗/
              Pfloat          y;              /∗ green, saturation, lightness, etc. ∗/
              Pfloat          z;              /∗ blue, value, saturation, etc. ∗/
         } general;
      } val;
} Pgcolr;

Constants defined in phigs.h for colour type are as follows:

0PINDIRECTIndirect
1PRGBRed, Green, Blue
2PCIECIE
3PHSVHue, Saturation, Value
4PHLSHue, Lightness, Saturation

The index member of the val union is used for type PINDIRECT.  The general member is used for the other types. 

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, 3, or 4. 

IAAn array of integers with the following values:

IA(1)The foreground colour type.  Valid values as defined in phigs77.h are:

0PINDIRIndirect
1PRGBRed, Green, Blue
2PCIECIE
3PHSVHue, Saturation, Value
4PHLSHue, Lightness, Saturation

IA(2)The background colour type. 

IA(3)The foreground colour index, if IA(1) specifies colour type PINDIR. 

IA(4)The background colour index, if IA(2) specifies colour type PINDIR. 

RLThe number of real values = 0, 3 or 6. 

RAAn array of reals with the following values:

RA(1) - RA(3)
The foreground colour triple (x, y, z), if IA(1) does not specify colour type PINDIR. 

RA(4) - RA(6)
The background colour triple (x, y, z), if IA(2) does not specify colour type PINDIR. 

SLThe number of choice strings. 

LSTRAn array of integers, each entry specifying the length of the corresponding character string in STR. 

STRThe array of choice strings. 

Device 16 - Sun Buttons

This device is the Sun 32 key lighted button box, if one is attached. 

The echo volume is not used by this device. 

Prompt/echo types supported: 1, 2

PET 1All 32 buttons will be active and lit while the device is active. 

The data record is not used for this PET. 

PET 2The buttons specified by the application will be active and lit while the device is active.  The data record contains the number and array of on/off values.  If less than 32 values are specified, the first n buttons will be set as specified, and the remainder will be inactive and not lit. 

C Data Record:

A Pchoicepet0002 structure defined in phigs.h as:

typedef struct {
Pintnumber;/∗ number of alternatives ∗/
Pprf∗enable;/∗ array of prompts ∗/
} Pchoicepet0002;

Pprf is an enumerated type defined in phigs.h; valid values for this type are PPR_ON (active and lit) and PPR_OFF (not active and not lit). 

FORTRAN Data Record:

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

ILThe number of on/off values. 

IAAn array of on/off values specifying whether each button is active and lit (PON) or not active and not lit (POFF). 

RLThe number of real values = 0. 

SLThe number of strings = 0. 

ASSOCIATIONS BETWEEN INPUT DEVICES - SunPHIGS Extension

All CHOICE devices can have associated with them a set of other input devices that will also generate input events when the CHOICE device is triggered.  The association is made with the ESCAPE function, described in the ESCAPE reference manual page.  The ESCAPE function accepts a triggering-device/triggered-device pair. This pair indicates an additional device to trigger (the slave device) when the specified triggering device (the master device) is triggered.  Separate associations can be made with each possible value of the master device (i.e. choice numbers), in which case selection of that value by the operator will trigger the devices associated with that value.  This allows operator selection of a specific choice value on a specified CHOICE device to also trigger one or more other input devices. 

When a device and its associated devices are triggered, a set of simultaneous events are generated, one event for each device. 

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 CHOICE MODE (3P)
REQUEST CHOICE (3P)
SAMPLE CHOICE (3P)
GET CHOICE (3P)
INQUIRE CHOICE DEVICE STATE 3 (3P)
INITIALIZE CHOICE (3P)

Sun Release 4.0  —  Last change: 29 July 1989