NAME

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

SYNOPSIS

C Syntax

void
pget_pick ( depth, in_status, rpick )
Pintdepth;depth of pick path to return
Pin_status∗in_status;OUT pick status
Ppick_path∗rpick;OUT pick path

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

GET PICK retrieves the current event report from the PHIGS state list when the event report contains a PICK event.  A PICK event consists of a status and a pick path.  The status indicates whether or not a pick by the operator successfully selected an ouput primitive.  The pick path describes the location of the picked primitive, if any, in the Central Structure Store (CSS). 

C Input Parameter

depthThe maximum number of pick path elements to return.  This may be more or less than the actual path depth in the current event report. 

C Output Parameters

in_status
PHIGS sets the variable pointed to by in_status to the event’s pick status.  A value of PIN_STATUS_OK indicates that an output primitive was successfully selected by the operator.  A value of PIN_STATUS_NONE indicates that a pick was attempted but no primitive 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 PICK. 

rpickPHIGS sets the variable pointed to by rpick to the events’s pick path.  Ppick_path is defined in phigs.h as follows:

typedef struct {
Pintdepth;/∗ pick path_list depth ∗/
Ppick_path_elem∗path_list; /∗ pick path ∗/
} Ppick_path;

A pick path is only returned if the status is PIN_STATUS_OK.  The contents of rpick are not changed if the status is not PIN_STATUS_OK.  The pick path depth indicates the number of elements in the event’s pick path as stored in the current event report.  It is not affected by the depth input parameter; therefore, the number of elements returned in path_list may be less than depth. 

path_list is an array of references defining the location of the picked primitive in the CSS.  This array must be allocated by the calling program and the array pointer assigned to this field before calling this function. The array must be at least long enough to hold the number of path elements indicated by the depth input parameter.  Ppick_path_elem is defined in phigs.h as:

typedef struct {
Pintstruct_id;/∗ structure identifier ∗/
Pintpick_id;/∗ hierarchical pick identifier ∗/
Pintelem_pos; /∗ element sequence number ∗/
} Ppick_path_elem;

The struct_id, pick_id, and elem_pos are the structure identifier, pick id, and element number, respectively, of each element in the path.  Each element but the last indicates the location and current pick id of an EXECUTE STRUCTURE structure element in the path to the selected primitive.  The last element in the path indicates the location and current pick id of the selected output primitive. 

Execution

GET PICK retrieves the contents of a PICK event from the current event report in the PHIGS state list.  If PIN_STATUS_OK is returned as the status, the returned pick path contains the portion of the event’s pick path requested, as specified by the depth input parameter.  The pick path will be in either top-first or bottom-first order depending upon the value specified when the device was initialized. 

When an input device in EVENT mode is triggered by the operator, an event report is added to the input event queue if the queue is not full.  The event report contains the identity and current measure of the triggered 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 was a PICK event, GET PICK is used to retrieve the contents of the event from the current event report. 

If the pick event was generated by the operator’s successfully selecting an output primitive, GET PICK returns the status PIN_STATUS_OK and the pick path to the primitive selected.  If a primitive was not successfully selected, the status returned will be PIN_STATUS_NONE and no pick path is returned. 

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

The pick filter of a PICK device controls which output primitives on the device’s workstation are pickable.  By default no output primitives are pickable.  See SET PICK FILTER for more information on the pick filter. 

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 PICK (3P)
INITIALIZE PICK 3 (3P)
AWAIT EVENT (3P)
SET PICK FILTER (3P)

September 02, 1992