.\"##
.\" $XConsortium: p252,v 5.3 94/04/17 20:57:22 hersh Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         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 name of Sun Microsystems,
.\"## 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.
.ds b \s-2BREAK\s+2
.TH "REQUEST CHOICE" 3P "29 February 1991"
.SH NAME
REQUEST CHOICE \- request an operator interaction with a choice device
.IX "Choice Input Devices" "REQUEST CHOICE"
.IX "Request Input Mode" "REQUEST CHOICE"
.IX "Input Modes" "REQUEST CHOICE"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
preq_choice ( ws, dev, in_status, choice )
Pint	ws;	\fIworkstation identifier\fP
Pint	dev;	\fIchoice device number\fP
Pin_status	*in_status; 	\fIOUT input status\fP
Pint	*choice;	\fIOUT choice\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
Use \s-2REQUEST CHOICE\s+2 to request an operator interaction with a
specified choice device. The device must be in request mode. See
\s-2SET CHOICE MODE\s+2 and \s-2INITIALIZE CHOICE\s+2 for more
information. See the \fIAvailable Devices\fP section of
\s-2INITIALIZE CHOICE\s+2 for a
description of the available choice devices.
.LP
The request suspends \s-2PHIGS\s+2 until the specified
device is triggered,
or the operator performs a \*b.
A \*b is performed by typing the \s-2CONTROL\s+2 and \s-2D\s+2 keys
simultaneously (^D).
.SS C Input Parameters
.IP \fIws\fP
Workstation identifier. An integer specifying the
workstation with which the requested choice device is associated.
.IP \fIdev\fP
The device number of the requested choice device.
.SS C Output Parameters
.IP \fIin_status\fP
A pointer to the location to store the status of the request.
Pin_status is 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 \fIchoice\fP
A pointer to the location to store the selected choice value, if any.
.SS Execution
\s-2REQUEST CHOICE\s+2 requests a logical input value from the specified
choice device.  The specified device must be in request mode.  See
\s-2SET CHOICE MODE\s+2 for more information.
.LP
\s-2REQUEST CHOICE\s+2 creates a measure
process for the specified device and suspends \s-2PHIGS\s+2 until the
device is triggered or the operator issues a \*b. 
A \*b is generated by the operator by depressing the
\s-2CONTROL\s+2 and \s-2D\s+2 keys
simultaneously (^D).
.LP
If the choice device is triggered and a choice has not been made, the status
is returned as \s-2PIN_STATUS_NONE\s+2, and no choice value is returned.
.LP
If the choice device is triggered and a choice has been made, the status
is returned as \s-2PIN_STATUS_OK\s+2, and the choice value contains the choice number
selected by the operator.
.LP
If a \*b occurs, the status is returned as \s-2PIN_STATUS_NO_IN\s+2, and no choice
value is returned.
.LP
In either case, when the device is triggered or a \*b is issued, 
the current measure process is terminated and \s-2PHIGS\s+2 processing resumes.
.SH ERRORS
.IP 003
Ignoring function, function requires state 
(\s-2PHOP\s+2, \s-2WSOP\s+2, \s-2*\s+2, \s-2*\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
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "INITIALIZE CHOICE 3 (3P)"
.SM "SET CHOICE MODE (3P)"
.fi