.\" .\" $XConsortium: p075,v 5.4 94/04/17 20:55:08 hersh Exp $ .\" .\" $XMCOPY .\" Copyright (c) 1990, 1991 by Sun Microsystems, Inc. and the X Consortium. .\" .\" All Rights Reserved .\" .\" Permission to use, copy, modify, and distribute this software and its .\" documentation for any purpose and without fee is hereby granted, .\" provided that the above copyright notice appear in all copies and that .\" both that copyright notice and this permission notice appear in .\" supporting documentation, and that the names of Sun Microsystems, .\" and the X Consortium not be used in advertising or publicity .\" pertaining to distribution of the software without specific, written .\" prior permission. .\" .\" SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, .\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO .\" EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR .\" CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF .\" USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR .\" OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .TH "INITIALIZE CHOICE" 3P "29 February 1991" .SH NAME INITIALIZE CHOICE \- initialize a \s-2CHOICE\s+2 input device using \s-2\&2D\s+2 data .IX "Choice Input Devices" "INITIALIZE CHOICE" .IX "PFCN_KEY \s-2C\s+2 Macros" "INITIALIZE CHOICE" .SH SYNOPSIS .SS C Syntax .ft B .ta 1.25i 3.25i .nf void pinit_choice ( ws, dev, istat, init, pet, echo_area, record ) Pint ws; \fIworkstation identifier\fP Pint dev; \fIchoice device number\fP Pin_status istat; \fIinitial choice status\fP Pint init; \fIinitial choice\fP Pint pet; \fIprompt and echo type\fP Plimit *echo_area; \fIecho area pointer\fP Pchoice_data *record; \fIdata record pointer\fP .fi .ft R .SS Required PHIGS Operating States (PHOP, WSOP, *, *) .SH DESCRIPTION .SS Purpose \s-2INITIALIZE CHOICE\s+2 sets the initialization parameters of a \s-2CHOICE\s+2 device. This function stores these parameters in the workstation state list of the workstation associated with the specified device. The specified \fBdevice must be in \s-2REQUEST\s+2 mode\fP when this function is called. .SS C Input Parameters .IP \fIws\fP The workstation identifier of the workstation associated with the device. .IP \fIdev\fP The device number of the \s-2CHOICE\s+2 device to initialize. See the \fIAVAILABLE DEVICES\fP section below for a description of the available devices. .IP \fIistat\fP The \s-2CHOICE\s+2 status of the initial measure. Pin_status is an enumerated type defined in phigs.h as follows: .sp .4 .ta .5i .nf typedef enum { .sp .2 PIN_STATUS_NONE, PIN_STATUS_OK, PIN_STATUS_NO_IN .sp .2 } Pin_status; .fi .IP \fIinit\fP The initial choice number. \s-2PHIGS\s+2 ignores this value if \fIistat\fP is not \s-2PIN_STATUS_OK\s+2. .IP \fIpet\fP The prompt/echo type desired. Those supported by each device are listed in the \fIAVAILABLE DEVICES\fP section below. .IP \fIecho_area\fP A pointer to a Plimit structure defining the \fIx\fP and \fIy\fP components of the echo volume, in Device Coordinates. The \fIz\fP component in the workstation state list is left unchanged. Plimit is defined in phigs.h as follows: .sp .4 .nf .ta .5i +1i +1i .sp .2 typedef struct { .sp .2 Pfloat x_min; /* minimum x coordinate value */ Pfloat x_max; /* maximum x coordinate value */ Pfloat y_min; /* minimum y coordinate value */ Pfloat y_max; /* maximum y coordinate value */ .sp .2 } Plimit; .IP .fi .IP \fIrecord\fP A 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 \fIAVAILABLE DEVICES\fP section. .IP 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 \fIpet_r1\fP. .IP Pchoice_data is defined in phigs.h as: .sp .4 .ta .5i +\w'Ppr_switch 'u +\w'num_strings; 'u .nf typedef struct { .sp .2 union { struct { Pint unused; } pet_r1; struct { Pint num_prompts; /* number of alternatives */ Ppr_switch *prompts; /* array of prompts */ } pet_r2; struct { Pint num_strings; /* number of choice strings */ char **strings; /* array of choice strings */ } pet_r3; struct { Pint num_strings; /* number of alternatives */ char **strings; /* array of strings */ } pet_r4; struct { Pint struct_id; /* struct identifier */ Pint num_pick_ids; /* number of alternatives */ Pint *pick_ids; /* array of pick identifiers */ } pet_r5; } pets; .sp .2 } Pchoice_data; .fi .IP For some prompt/echo types the data record is not used; however, the \fIrecord\fP parameter must still be supplied. .SS Execution .LP \s-2INITIALIZE CHOICE\s+2 sets the initialization parameters of a \s-2CHOICE\s+2 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 \s-2REQUEST\s+2 mode when this function is called. .LP The parameters that are initialized by this function are \fIinitial choice\fP, \fIprompt/echo type\fP, \fIecho volume\fP, and \fIinput data record\fP. .LP The \fIinitial choice\fP 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 \s-2REQUEST CHOICE\s+2 is called, or when its input mode is set to \s-2SAMPLE\s+2 or \s-2EVENT\s+2. .LP A \s-2CHOICE\s+2 device measure consists of a \fIstatus\fP and a \fIchoice number\fP. \fIStatus\fP indicates whether or not one of the possible choice values on the device was selected. (It's possible to trigger some \s-2CHOICE\s+2 devices without selecting one of the choices.) The \fIchoice number\fP indicates the value selected, if any. .LP The \fIprompt/echo type\fP 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 \fIAVAILABLE DEVICES\fP section below. All devices support prompt/echo type 1. Positive prompt/echo types are defined by the \s-2PHIGS\s+2 standard. Negative types are implementation-dependent. .LP The \fIecho volume\fP defines the region of the display surface in which to echo the device. It is specified in Device Coordinates (\s-2DC\s+2). 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 \fIx\fP and \fIy\fP components of the echo volume. The existing \fIz\fP component in the workstation state list is left unchanged. .LP The \fIinput data record\fP 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 \fIAVAILABLE DEVICES\fP section below list the data record contents that each device recognizes. .LP All the initialization parameters must be specified properly or this function will generate an error. The \fIERRORS\fP section below lists the possible error conditions. .LP The default initialization parameters and the list of prompt/echo types supported by a \s-2CHOICE\s+2 input device can be inquired with the function \s-2INQUIRE DEFAULT CHOICE DEVICE DATA\s+2. The current state of the device can be inquired with the function \s-2INQUIRE CHOICE DEVICE STATE\fP. .SH AVAILABLE DEVICES .SS Device 1 - "Athena List Widget" .LP 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. .LP The echo volume is not used by this device. .LP \fBPrompt/echo types supported\fP: 1, 3 .IP "PET 1" .8i Display a \s-2PHIGS\s0-defined list of choice strings in the menu. The choice strings are the integers \fI1\fP through \fI10\fP. .IP The data record is not used for this \s-2PET\s+2. .IP "PET 3" Display an application-specified list of choice strings in the menu. The data record member used is \fIpet_r3\fP, which contains the number and array of choice strings. .LP The widgets used and their names, in decreasing hierarchy, are: .IP choice1 \(-> \fIapplicationShellWidgetClass\fR .RS .br viewport \(-> \fIviewportWidgetClass\fR .RS .br list \(-> \fIlistWidgetClass\fR .RE .RE .LP Fallback resources for choice devices are: .IP *choice1*allowHoriz \(-> \fI\s-1TRUE\s+1\fR .IP *choice1*allowVert \(-> \fI\s-1TRUE\s+1\fR .IP *choice1*list.translations \(em .RS .br , \(-> \fISet() Notify() RequestSatisfied()\fR .RE .LP The fully qualified name of all widgets is .workstation.choice., where 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. .SH ERRORS .IP 003 Ignoring function, function requires state (\s-2PHOP, WSOP\s+2, *, *) .IP 054 Ignoring function, the specified workstation is not open .IP 061 Ignoring function, specified workstation is neither of category \s-2INPUT\s+2 nor of category \s-2OUTIN\s+2 .IP 250 Ignoring function, the specified device is not available on the specified workstation .IP 251 Ignoring function, the function requires the input device to be in \s-2REQUEST\s+2 mode .IP 253 Warning, the specified prompt/echo type is not available on the specified workstation. Prompt/echo type one will be used in its place .IP 254 Ignoring function, invalid echo area/volume; \s-2XMIN \(>= XMAX, YMIN \(>= YMAX\s+2, or \s-2ZMIN > ZMAX\s+2 .IP 255 Ignoring function, one of the echo area/volume boundary points is outside the range of the device .IP 260 Ignoring function, one of the fields within the input device data record is in error .IP 261 Ignoring function, initial value is invalid .SH SEE ALSO .nf .IP .ta 0.5i SET CHOICE MODE (3P) REQUEST CHOICE (3P) SAMPLE CHOICE (3P) GET CHOICE (3P) INQUIRE CHOICE DEVICE STATE (3P) INITIALIZE CHOICE 3 (3P) .fi