.\" @(#)PEXEndPickOne.3 1.5 95/03/24 SMI;
.so man3/pex.macs
.TH PEXEndPickOne 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXEndPickOne \- End Pick One
.SH SYNTAX
.HP
PEXPickPath *PEXEndPickOne\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\fP\^, int *\fIstatus_return\fP\^, int *\fIundetectable_return\fP\^)
.SH PARAMETERS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.IP \fIrenderer\fP 1i
The resource identifier of the renderer.
.IP \fIstatus_return\fP 1i
Returns the status of the pick operation.
.IP \fIundetectable_return\fP 1i
Returns
.SB True
or
.SB False
indicating whether another pick better satisfied the pick criteria with the
exception that it did not pass the pick filter test.
.SH RETURNS
A pointer to the pick path; a null pointer if unsuccessful or no pick
(see also \fIstatus_return\fP).
.SH DESCRIPTION
.\" indexing
.IX PEXEndPickOne
.IX "Picking" "PEXEndPickOne"
.LP
This function terminates an immediate-mode pick,
returns the hierarchical pick path to the
closest or last hit primitive,
and sets the renderer state to
.B PEXIdle.
.LP
If a primitive was picked, the returned pick status is
.B PEXPick.
If no primitive was picked, the returned pick status is
.B PEXNoPick,
and the returned pick path is a null pointer.
If the renderer's drawable
was destroyed or resized during the pick operation, the returned pick status
is
.B PEXAbortedPick
and the returned pick path is a null pointer.
.LP
If there was a primitive which more closely satisfied the pick criteria, but
did not pass the pick filter test, then the undetectable pick return status
will be
.SB True.
Otherwise, it will be
.SB False.
.LP
If the renderer state is currently
.B PEXIdle
when this function is called, (i.e., no
picking is in progress or the rendering was aborted due to a resize),
the function is ignored and no error is generated.  If the renderer state
is currently
.B PEXRendering
or if the pick operation in progress is a pick all, then a
.SB BadPEXRendererState
error is sent.
.LP
PEXlib allocates memory for the return value.
.BR PEXFreePickPaths (3)
should be called to deallocate the memory.
.SH DATA STRUCTURES
.LP
.nf
typedef  XID	PEXRenderer;
.sp
typedef struct {
	unsigned long		count;		/* number of elements */
	PEXPickElementRef	*elements;
.br
} PEXPickPath;
.bp
typedef struct {
	PEXStructure		sid;
	unsigned long		offset;
	unsigned long		pick_id;
.br
} PEXPickElementRef;
.sp
typedef  XID	PEXStructure;
.fi
.SH ERRORS
.TP
.SB BadPEXRenderer
The specified renderer resource identifier is invalid.
.TP
.SB BadPEXRendererState
The specified renderer was in an invalid state.
.SH SEE ALSO
.LP
.nf
.BR PEXBeginPickOne (3)
.BR PEXPickOne (3)
.fi