.\"##
.\" $XConsortium: p001,v 5.2 94/04/17 20:54:11 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 "ADD NAMES TO SET" 3P "29 February 1991"
.SH NAME
ADD NAMES TO SET \- create a structure element containing additions to the
current name set
.IX "Highlighting" "ADD NAMES TO SET"
.IX "Invisibility" "ADD NAMES TO SET"
.IX "Detectability" "ADD NAMES TO SET"
.IX "Namesets" "ADD NAMES TO SET"
.IX "Special Attributes" "ADD NAMES TO SET"
.IX "Attributes, Special Attributes" "ADD NAMES TO SET"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
padd_names_set ( set )
Pint_list	*set;	\fIset of names to be added\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
The \s-2ADD NAMES TO SET\s+2 function puts a structure element
containing additions to the traversal-time \fIcurrent name set\fP
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 that 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.
.LP
If the current edit mode is \s-2INSERT\s+2, the \s-2ADD NAMES TO 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-2ADD NAMES TO 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.
.SS C Input Parameter
.IP \fIset\fP
A pointer to a Pint_list structure
containing the set of names to be added.
The Pint_list data structure is defined in phigs.h as:
.sp .4
.ta .5i +\w'Piclass '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;
.SS Execution
When traversal of a posted structure network 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. \s-2REMOVE NAMES FROM SET\s+2 elements remove names 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 (3P), \s-2SET HIGHLIGHTING FILTER\s+2 (3P), and \s-2SET PICK FILTER\s+2 (3P).  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 may 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\s+2, *, \s-2STOP\s+2, *)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "REMOVE NAMES FROM 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