.\"##
.\" $XConsortium: p323,v 5.2 94/04/17 20:58: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 "SET HIGHLIGHTING FILTER" 3P "29 February 1991"
.SH NAME
SET HIGHLIGHTING FILTER \- set the workstation's name set filter that 
determines which primitives are highlighted
.IX "Highlighting" "SET HIGHLIGHTING FILTER"
.IX "Namesets" "SET HIGHLIGHTING FILTER"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_highl_filter ( ws, filter)
Pint	ws;		\fIworkstation identifier\fP
Pfilter	*filter;	\fIhighlighting filter\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET HIGHLIGHTING FILTER\s+2 sets the workstation's \fIhighlighting filter\fP,
which is compared to the traversal-time \fIcurrent name set\fP of each primitive
to determine if the primitive is highlighted.  
.LP
The filter contains an \fIinclusion set\fP and an \fIexclusion set\fP of names.  
During traversal, a primitive is eligible for highlighting
.\" "eligible for highlighting" because the workstation may never highlight.
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.  
Each name in the inclusion name set and exclusion name set 
is a small positive integer.  
.SS C Input Parameters
.IP \fIws\fP
The identifier of the workstation whose highlighting 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 .4
.ta .5i +\w'Pint_list     'u +\w'excl_set;    'u
.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 .4
.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 HIGHLIGHTING FILTER\s+2 sets the workstation's highlighting filter, 
which contains an inclusion set and an exclusion set of names, 
both empty by default.  
A primitive is eligible for highlighting
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.  
If the workstation's highlighting filter inclusion set is empty, then 
no primitives are eligible for highlighting.  
.LP
If the current name set is empty, then subsequent primitives are not eligible.  
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 on the sets.  
\s-2REMOVE NAMES FROM SET\s+2 elements remove names from the current name set.  
The actual appearance of highlighting is workstation dependent.  
.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 059
Ignoring function, the specified workstation does not have output capability
(in other words, the workstation category is neither 
\s-2OUTPUT\s+2, \s-2OUTIN\s+2, nor \s-2MO\s+2) 
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "ADD NAMES TO SET (3P)"
.SM "REMOVE NAMES FROM SET (3P)"
.SM "GENERALIZED STRUCTURE ELEMENT (3P)"
.SM "INQUIRE HIGHLIGHTING FILTER (3P)"
.fi