.\"
.\" $XConsortium: p065,v 5.3 94/04/17 20:55:01 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 "GET CHOICE" 3P "16 August 1991"
.SH NAME
GET CHOICE \- retrieve the
\s-2CHOICE\s+2
event in the \s-2PHIGS\s+2 current event report
.IX "Choice Input Devices" "GET CHOICE"
.IX "Event Input Mode" "GET CHOICE"
.IX "Input Modes" "GET CHOICE"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pget_choice ( in_status, choice )
Pin_status	*in_status;	\fI\s-2OUT\s+2 choice status\fP
Pint	*choice;	\fI\s-2OUT\s+2 choice\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2GET CHOICE\s+2 retrieves the current event report from the
\s-2PHIGS\s+2 state list when the event report contains a Choice event.
A \s-2CHOICE\s+2 event consists of a status and a choice value.
The status indicates if the operator selected one of the available choices
from the input device.
The choice value indicates the choice selected, if any.
.SS C Output Parameters
.IP \fIin_status\fP
\s-2PHIGS\s+2 sets the variable pointed to by \fIin_status\fP to indicate
whether or not one of the possible choices of the Choice device
was selected.
A value of \s-2PIN_STATUS_OK\s+2 indicates that one of the possible choice values
was selected.
A value of \s-2PIN_STATUS_NONE\s+2 indicates that none of the possible choices
was selected.
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
The value \s-2PIN_STATUS_NO_IN\s+2 will not be returned by this function.
That value is for use with \s-2REQUEST CHOICE\s+2.
.IP \fIchoice\fP
If the status returned is \s-2PIN_STATUS_OK\s+2, \s-2PHIGS\s+2 sets the variable
pointed to by \fIchoice\fP to the choice value selected by the operator.
The variable is not set if the status returned is \s-2PIN_STATUS_NONE\s+2.
.SS Execution
.LP
When an input device that is set to Event mode is triggered
by the operator,
an event report is added to the input event queue.
The event report contains the identity and current measure of the device.
\s-2AWAIT EVENT\s+2 moves the measure of the oldest event in the input queue
to the current event report in the \s-2PHIGS\s+2 state list.
If the event is a Choice event, \s-2GET CHOICE\s+2 is used to
retrieve the contents of the event from the current event report.
.LP
If the choice event was generated by the operator's selecting one of the
possible choice values, \s-2GET CHOICE\s+2 returns the status
\s-2PIN_STATUS_OK\s+2 and the choice value selected.
If none of the possible values was selected, the status returned will be
\s-2PIN_STATUS_NONE\s+2 and no choice value is returned.
.LP
See \s-2INITIALIZE CHOICE 3\s+2 for a description of the available
Choice devices and how their measure values are determined.
.SH ERRORS
.IP 003
Ignoring function, function requires state (\s-2PHOP, WSOP, *, *\s+2)
.IP 259
Ignoring function, the input device class of the current input report
does not match the class being requested
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "INITIALIZE CHOICE (3P)"
.SM "INITIALIZE CHOICE 3 (3P)"
.SM "AWAIT EVENT (3P)"
.fi