.\"##
.\" $XConsortium: p248,v 5.2 94/04/17 20:57:19 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 "POST STRUCTURE" 3P "29 February 1991"
.SH NAME
POST STRUCTURE \- assign a structure network to a workstation for display
.IX "Priority, Display Priority" "POST STRUCTURE"
.IX "Display Priority" "POST STRUCTURE"
.IX "Structure Networks" "POST STRUCTURE"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
ppost_struct ( ws_id, struct_id, priority )
Pint	ws_id;	\fIworkstation identifier\fP
Pint	struct_id;	\fIstructure identifier\fP
Pfloat	priority;	\fIpriority\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2POST STRUCTURE\s+2 assigns a structure, and the structure network of which
it is the root, to a workstation for display.
The workstation's \fIdisplay update state\fP determines when the structure
network is traversed, updating the display.
.\"	The workstation must be opened before posting a structure to it.
.SS C Input Parameters
.IP \fIws_id\fP
The identifier of the workstation to which the structure should be posted.
.IP \fIstruct_id\fP
The identifier of the structure to be posted.
.IP \fIpriority\fP
The display priority of this structure in relation to other structures posted to the same workstation, in the range of 0.0
to 1.0, inclusive.
.\"	Structures with lower \fIpriority\fP values take precedence over structures with higher \fIpriority\fP values.
.SS Execution
.LP
\s-2POST STRUCTURE\s+2 adds \fIstructure identifier\fP
to the \fItable of posted structures\fP
on the workstation with \fIworkstation identifier\fP.
If the structure does not exist, it will be created as an empty structure
and posted to \fIws_id\fP.
.LP
If more than one structure network is posted to the workstation, display
\fIpriority\fP determines the display order of the structure networks.
Structures with higher priority values take precedence over (i.e.,
are drawn on top of) structures with lower priority values.  If the
structure identifier is already posted on the workstation, the
structure is removed from the table of posted structures, and reposted
with the priority value specified.  If two structures are posted
with the same priority, the structure posted (or reposted) last assumes a
higher priority.
.LP
If the workstation's display update state permits,
\s-2POST STRUCTURE\s+2 initiates traversal of all
the structure networks posted to the workstation, ordered by their priority.
(See \s-2SET DISPLAY UPDATE STATE\s+2
.\"	and the \fI\s-2PEX-SI\s0 Programming Guide\fP
for more information on the workstation display update state.)
The structure elements are traversed in sequence, beginning with the first
element of the posted structure. Traversal of subordinate structures in the
network is prompted by \s-2EXECUTE STRUCTURE\s+2 elements.
.LP
The structure network and the workstation state together
determine the image displayed on the workstation's display surface.
While a structure remains posted to a workstation, any
changes in the structure network or the workstation's tables can result in
immediate changes to the display, depending on the structure's priority
and the workstation's display update state.
.SH ERRORS
.IP 003
Ignoring function, function requires state (\s-2PHOP, WSOP, *, *\s+2)
.IP 054
Ignoring function, the specified workstation is not open
.IP 059
Ignoring function, the specified workstation does not have output capability
(i.e., the workstation category is neither \s-2OUTPUT\s+2, \s-2OUTIN\s+2, nor \s-2MO\s+2)
.IP 208
Ignoring function, the display priority is out of range
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "UNPOST STRUCTURE (3P)"
.SM "UNPOST ALL STRUCTURES (3P)"
.SM "INQUIRE POSTED STRUCTURES (3P)"
.SM "INQUIRE SET OF WORKSTATIONS TO WHICH POSTED (3P)"
.SM "INQUIRE NUMBER OF DISPLAY PRIORITIES SUPPORTED (3P)"
.fi