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

NAME

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

SYNOPSIS

C Syntax

void
pinit_choice ( ws, dev, istat, init, pet, echo_area, record )
Pintws;workstation identifier
Pintdev;choice device number
Pin_statusistat;initial choice status
Pintinit;initial choice
Pintpet;prompt and echo type
Plimit∗echo_area;echo area pointer
Pchoice_data∗record;data record pointer

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

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

istatThe CHOICE status of the initial measure. Pin_status is an enumerated type defined in phigs.h as follows:

typedef enum {
PIN_STATUS_NONE,
PIN_STATUS_OK,
PIN_STATUS_NO_IN
} Pin_status;

initThe initial choice number. PHIGS ignores this value if istat is not PIN_STATUS_OK.

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. 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 Pchoice_data 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 Pchoice_data union for prompt/echo type 1 is pet_r1.

Pchoice_data is defined in phigs.h as:

typedef struct {
      union {
struct {
   Pintunused;
} pet_r1;
struct {
   Pintnum_prompts; /∗ number of alternatives ∗/
   Ppr_switch∗prompts; /∗ array of prompts ∗/
} pet_r2;
struct {
   Pintnum_strings;/∗ number of choice strings ∗/
   char∗∗strings;/∗ array of choice strings ∗/
} pet_r3;
struct {
   Pintnum_strings;/∗ number of alternatives ∗/
   char∗∗strings;/∗ array of strings ∗/
} pet_r4;
struct {
   Pintstruct_id;/∗ struct identifier ∗/
   Pintnum_pick_ids; /∗ number of alternatives ∗/
   Pint∗pick_ids;/∗ array of pick identifiers ∗/
} pet_r5;
      } pets;
} Pchoice_data;

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

Execution

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

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

AVAILABLE DEVICES

Device 1 - Athena List Widget

This device is a collection of widgets from the Athena widget set. The set consists of a shell widget, a viewport widget, and a list widget. The list is the item manipulated by the operator to change the choice value.

The echo volume is not used by this device.

Prompt/echo types supported: 1, 3

PET 1Display a PHIGS-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 member used is pet_r3, which contains the number and array of choice strings.

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

choice1 → applicationShellWidgetClass

viewport → viewportWidgetClass

list → listWidgetClass

Fallback resources for choice devices are:

∗choice1∗allowHoriz → TRUE

∗choice1∗allowVert → TRUE

∗choice1∗list.translations —

<Btn1Down>,<Btn1Up> → Set() Notify() RequestSatisfied()

The fully qualified name of all widgets is <appl_name>.workstation<ws_id>.choice<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.choice1.viewport is the name of the viewport widget of choice 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