NAME

GET CHOICE − retrieve the CHOICE event in the PHIGS current event report

SYNOPSIS

C Syntax

void
pget_choice ( in_status, choice )
Pin_status∗in_status;OUT choice status
Pint∗choice;OUT choice

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

GET CHOICE retrieves the current event report from the PHIGS state list when the event report contains a Choice event.  A CHOICE 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. 

C Output Parameters

in_status
PHIGS sets the variable pointed to by in_status to indicate whether or not one of the possible choices of the Choice device was selected.  A value of PIN_STATUS_OK indicates that one of the possible choice values was selected.  A value of PIN_STATUS_NONE indicates that none of the possible choices was selected.  Pin_status is defined in phigs.h as follows:

typedef enum {
PIN_STATUS_NONE,
PIN_STATUS_OK,
PIN_STATUS_NO_IN
} Pin_status;

The value PIN_STATUS_NO_IN will not be returned by this function.  That value is for use with REQUEST CHOICE. 

choiceIf the status returned is PIN_STATUS_OK, PHIGS sets the variable pointed to by choice to the choice value selected by the operator.  The variable is not set if the status returned is PIN_STATUS_NONE. 

Execution

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.  AWAIT EVENT moves the measure of the oldest event in the input queue to the current event report in the PHIGS state list.  If the event is a Choice event, GET CHOICE is used to retrieve the contents of the event from the current event report. 

If the choice event was generated by the operator’s selecting one of the possible choice values, GET CHOICE returns the status PIN_STATUS_OK and the choice value selected.  If none of the possible values was selected, the status returned will be PIN_STATUS_NONE and no choice value is returned. 

See INITIALIZE CHOICE 3 for a description of the available Choice devices and how their measure values are determined. 

ERRORS

003Ignoring function, function requires state (PHOP, WSOP, ∗, ∗)

259Ignoring function, the input device class of the current input report does not match the class being requested

SEE ALSO

INITIALIZE CHOICE (3P)
INITIALIZE CHOICE 3 (3P)
AWAIT EVENT (3P)

September 02, 1992