.\"##
.\" $XConsortium: p355,v 5.2 94/04/17 20:58:35 rws Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         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 name of Sun Microsystems,
.\"## 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 "SET PICK FILTER" 3P "29 February 1991"
.SH NAME
SET PICK FILTER \- set a \s-2PICK\s+2 input device's pick filter,
which determines which primitives are
pickable
.IX "Detectability" "SET PICK FILTER"
.IX "Namesets" "SET PICK FILTER"
.IX "Pick Input Devices" "SET PICK FILTER"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_pick_filter ( ws, dev_num, filter )
Pint	ws;	\fIworkstation identifier\fP
Pint	dev_num;	\fIpick device number\fP
Pfilter	*filter;	\fIpick filter\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET PICK FILTER\s+2 sets the \fIpick filter\fP of a \s-2PICK\s+2 input device,
which is compared to the traversal-time \fIcurrent name set\fP of each primitive
to determine if the primitive is pickable by that device.  
.LP
The filter contains an \fIinclusion set\fP and an \fIexclusion set\fP of names.  
During traversal,
a primitive is pickable by the \s-2PICK\s+2 input device
if at least one name in the current name set is in the inclusion set
and no name in the `current name set' is in the exclusion set.  
This means the exclusion set has precedence over the inclusion set.  
Each name in the name set, inclusion set, and exclusion set 
is a small positive integer.  
.SS C Input Parameters
.IP \fIws\fP
The identifier of the workstation.  
.IP \fIdev_num\fP
The device number of the \s-2PICK\s+2 input device on this workstation
whose pick filter is to be set.  
.IP \fIfilter\fP
A pointer to a Pfilter structure containing the inclusion set and exclusion set
of names. Pfilter is defined in phigs.h as follows:
.sp .2
.ta .5i +1i +1.25i
.nf
typedef struct {
.sp .2
	Pint_list	incl_set;	/* inclusion set */
	Pint_list	excl_set;	/* exclusion set */
.sp .2
} Pfilter;
.fi
.sp .4
The Pint_list structure is defined in phigs.h as follows:
.sp .2
.ta .5i +\w'Pint	'u +\w'*num_ints;	'u
.nf
typedef struct {
.sp .2
	Pint	num_ints;	/* number of Pints in list */
	Pint	*ints;	/* list of integers */
.sp .2
} Pint_list;
.fi
.sp .4
.SS Execution
\s-2SET PICK FILTER\s+2 sets the \s-2PICK\s+2 input device's pick filter,
which contains an inclusion set and an exclusion set of names,
both empty by default.  
A primitive is pickable by a workstation's \s-2PICK\s+2 input device
if at least one name in the current name set is in the
\s-2PICK\s+2 device's pick filter inclusion set
and no name in the current name set is in the device's
pick filter exclusion set.  
If the device's pick filter inclusion set is empty,
no primitives are pickable by that device.  
.LP
If the current name set is empty, subsequent primitives are not pickable
by any \s-2PICK\s+2 device.  
When the conceptual traversal of a posted structure network
(to determine what primitive is being picked) starts, the current name set
is empty.  During traversal, the member names specified
by the \s-2ADD NAMES TO SET\s+2 element are added to the current name set
by the union operation on the sets;  
\s-2REMOVE NAMES FROM SET\s+2 elements remove names from the current name set.  
.SH ERRORS
.IP 003
Ignoring function, function requires state 
(\s-2PHOP\s+2, \s-2WSOP\s+2, \s-2*\s+2, \s-2*\s+2)
.IP 054
Ignoring function, the specified workstation is not open
.IP 060
Ignoring function, specified workstation is not of category \s-2OUTIN\s+2
.IP 250
Ignoring function, the specified device is not available
on the specified workstation
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "ADD NAMES TO SET (3P)"
.SM "REMOVE NAMES FROM SET (3P)"
.SM "INITIALIZE PICK (3P)"
.SM "SET PICK MODE (3P)"
.SM "REQUEST PICK (3P)"
.SM "GET PICK (3P)"
.SM "SAMPLE PICK (3P)"
.SM "INQUIRE PICK DEVICE STATE (3P)"
.SM "INQUIRE PICK DEVICE STATE 3 (3P)"
.fi