.\" @(#)PEXEndPickAll.3 1.5 95/03/24 SMI;
.so man3/pex.macs
.TH PEXEndPickAll 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXEndPickAll \- End Pick All
.SH SYNTAX
.HP
PEXPickPath *PEXEndPickAll\^(\^Display *\fIdisplay\fP\^, PEXRenderer \fIrenderer\fP\^, int *\fIstatus_return\fP\^, int *\fImore_return\fP\^, unsigned long *\fIcount_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 \fImore_return\fP 1i
Returns the status of remaining picks.
.IP \fIcount_return\fP 1i
Returns the number of pick paths.
.SH RETURNS
An array of pick paths; a null pointer if unsuccessful or no pick
(see also \fIstatus_return\fP).
.SH DESCRIPTION
.\" indexing
.IX PEXEndPickAll
.IX "Picking" "PEXEndPickAll"
.LP
This function terminates an immediate-mode pick,
returns the hierarchical pick paths of any
hit primitives, and sets the renderer state to
.B PEXIdle.
.LP
If one or more primitives were picked, a pick status of
.B PEXPick
is returned along with the pick paths.  The hierarchical pick path is
equivalent to the renderer's current path at the time the picked primitive
was processed.
If no primitives were picked, the returned pick status is
.B PEXNoPick,
and the returned pick paths 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 paths is a null pointer.
.LP
If all hits were recorded then
.B PEXNoMoreHits
is returned
and the renderer's pick start path will be empty.
If the maximum number of hits was reached and additional
hits were detected, then
.B PEXMoreHits
is returned
and the renderer's pick start path will be set to the last recorded
hit primitive.
If, after reaching the maximum number of hits,
subsequent output commands were ignored, then
.B PEXMayBeMoreHits
is returned and the renderer's pick start path
is set to the last element processed by the
.I renderer
before
it started ignoring primitives.
.LP
If the renderer state is
.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 one, 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 PEXBeginPickAll (3)
.BR PEXPickAll (3)
.BR PEXFreePickPaths (3)
.fi