.\"##
.\" $XConsortium: p251,v 5.2 94/04/17 20:57:21 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 "REMOVE NAMES FROM SET" 3P "29 February 1991"
.SH NAME
REMOVE NAMES FROM SET \- create a structure element to remove names from the
current name set
.IX "Highlighting" "REMOVE NAMES FROM SET"
.IX "Invisibility" "REMOVE NAMES FROM SET"
.IX "Detectability" "REMOVE NAMES FROM SET"
.IX "Namesets" "REMOVE NAMES FROM SET"
.IX "Special Attributes" "REMOVE NAMES FROM SET"
.IX "Attributes, Special Attributes" "REMOVE NAMES FROM SET"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
premove_names_set ( set )
Pint_list	*set;	\fIset of names to be removed\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
\s-2REMOVE NAMES FROM SET\s+2 creates a structure element
containing names to be removed from the traversal-time \fIcurrent name set\fP,
and puts the element
into the currently open structure according to the current edit mode.
The current name set is compared during traversal to the workstation's
\fIname set filters\fP to determine if primitives which follow in the
structure network are invisible, highlighted, and/or
selectable by \s-2PICK\s+2 input devices.  Each name in the \fIname set\fP
is a small non-negative integer.
.SS C Input Parameter
.IP \fIset\fP
A pointer to a Pint_list structure
containing the set of names to be removed.
The Pint_list data structure is defined in phigs.h as:
.sp .4
.ta .5i +\w'Piclass     'u +\w'*integers;     'u
.nf
typedef struct {
.sp .2
	Pint	num_ints;	/* number of Pints in list */
	Pint	*ints;	/* list of integers */
.sp .2
} Pint_list;
.fi
.SS Execution
.LP
If the current edit mode is \s-2INSERT\s+2, the \s-2REMOVE NAMES FROM SET\s+2
element is inserted into the open structure after the element pointed to
by the current element pointer. If the edit mode is \s-2REPLACE\s+2, the
\s-2REMOVE NAMES FROM SET\s+2 element replaces the element pointed to by the
element pointer. In either case, the element pointer is updated to point
to the new element.
.LP
When traversal of a posted structure network starts, the \fIcurrent name set\fP
is empty. During traversal, the member names specified by
\s-2ADD NAMES TO SET\s+2 elements are added to the current name set.
The member names specified by \s-2REMOVE NAMES FROM SET\s+2 elements
are removed from the current name set.
.LP
The updated current name set applies to primitives
that follow in the structure network by set-intersection with the
workstation's \fIname set filters\fP, which are set by
\s-2SET INVISIBILITY FILTER\s+2,
\s-2SET HIGHLIGHTING FILTER\s+2, and \s-2SET PICK FILTER\s+2.
Each workstation has a single \fIinvisibility filter\fP,
a single \fIhighlighting filter\fP,
and a \fIpick filter\fP for each \s-2PICK\s+2 input device.
The actual appearance of highlighting is workstation-dependent.
.LP
Each filter contains an
\fIinclusion set\fP and an \fIexclusion set\fP of names, both
empty by default.
A primitive is \fIeligible\fP
.\"	for the special treatment
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.
If the current name set is empty, subsequent primitives are not eligible.
If the workstation's inclusion set is empty (the default),
no primitives are eligible.  That is, no primitives are invisible,
highlighted, or selectable by \s-2PICK\s+2 input devices.
.LP
Each name is a small non-negative integer.
\s-2PHIGS\s+2
conformance requires support for at least 64 names;
\s-2PEX-SI\s0
supports the range 0 to 1023.
The same names can be added and removed any number of times during traversal.
Since the presence or absence of each name in the current nameset and the
workstation's filter affects the eligibility of subsequent primitives,
1024 names provide up to 1024 different simultaneous groupings of primitives.
.SH ERRORS
.IP 005
Ignoring function, function requires state (\s-2PHOP, *, STOP, *\s+2)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "ADD NAMES TO SET (3P)"
.SM "SET INVISIBILITY FILTER (3P)"
.SM "SET HIGHLIGHTING FILTER (3P)"
.SM "SET PICK FILTER (3P)"
.SM "INCREMENTAL SPATIAL SEARCH (3P)"
.SM "INCREMENTAL SPATIAL SEARCH 3 (3P)"
.fi