.\"##
.\"## @(#)set_display_update_state.3 5.1 91/02/13 Copyr 1990, 1991 SMI/MIT
.\"##
.\"## 
$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 DISPLAY UPDATE STATE" 3P "26 March 1991"
.SH NAME
SET DISPLAY UPDATE STATE \- set Workstation Deferral and Modification Modes
.IX "Simulations" "SET DISPLAY UPDATE STATE"
.IX "Quick Update Methods" "SET DISPLAY UPDATE STATE"
.IX "Regeneration" "SET DISPLAY UPDATE STATE"
.IX "Dynamic Modifications" "SET DISPLAY UPDATE STATE"
.IX "Modifications" "SET DISPLAY UPDATE STATE"
.IX "Editing" "SET DISPLAY UPDATE STATE"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_disp_upd_st ( ws, def_mode, mod_mode )
Pint	ws;	\fIworkstation identifier\fP
Pdefer_mode	def_mode;	\fIdeferral mode\fP
Pmod_mode	mod_mode;	\fImodification mode\fP
.fi
.ft R
.\" START FORTRAN STRIP
.if '\*(pF'yes' \{\
.SS FORTRAN Syntax
.ft B
.ta 1.25i 3i
.nf
SUBROUTINE psdus ( WKID, DEFMOD, MODMOD )
INTEGER	WKID	\fIworkstation	identifier\fP
INTEGER	DEFMOD	\fIdeferral	mode\fP
INTEGER	MODMOD	\fImodification	mode\fP
.fi
.ft R
.\}
.\" END FORTRAN STRIP
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET DISPLAY UPDATE STATE\s+2 sets the deferral and modification
modes in the specified workstation's state list.  
These modes provide control over when and how changes to the structure
store and workstation tables actually appear in the display.  
These values have a great effect on both visual results and performance.  
.LP
The deferral mode controls when
the display is updated (in other words, made
entirely correct).  This allows
you to delay time-consuming or visually-distracting regeneration
until a set of related changes are completed 
or until a correct display is absolutely necessary, as before an
operator input interaction can proceed.  
.LP
The modification mode controls the visual effects that take place
while the workstation is postponing display updates.  
This allows you to selectively change the display,
but to avoid regenerating the entire picture.  
.SS C Input Parameters
.IP \fIws\fP
Identifier of the workstation whose update state to set.
.IP \fIdef_mode\fP
An enumerated value specifying the \fIdeferral mode\fP
to be set for this workstation.
Valid values are defined in phigs.h:
.sp .4
.nf
.ta 1.25i
PDEFER_ASAP	\fIMake the display visually correct As Soon As Possible\fP
PDEFER_BNIG	\fIMake the display visually correct Before the Next Interaction Globally\fP
PDEFER_BNIL	\fIMake the display visually correct Before the Next Interaction Locally\fP
PDEFER_ASTI	\fIMake the display visually correct At Some Time\fP
PDEFER_WAIT	\fIMake the display visually correct When the Application Requests It\fP
.fi
.IP \fImod_mode\fP
An enumerated value specifying the \fImodification mode\fP
to be set for this workstation.
Valid values are defined in phigs.h:
.sp .4
.nf
.ta 1.25i
PMODE_NIVE	\fINo Immediate Visual Effects\fP
PMODE_UWOR	\fIUpdate Without Regeneration\fP
PMODE_UQUM	\fIUse Quick Update Methods\fP
.fi
.\" START FORTRAN STRIP
.if '\*(pF'yes' \{\
.SS FORTRAN Input Parameters
.IP \fIWKID\fP
Identifier of the workstation whose update state to set.
.IP \fIDEFMOD\fP
An enumerated value specifying the \fIdeferral mode\fP
to be set for this workstation.
Valid values are defined in phigs77.h:
.sp .4
.nf
.\" .ta .5i +\w'PDEFER_WAITD'u
.ta .8i
PDEFER_ASAP	\fIMake the display visually correct As Soon As Possible\fP
PDEFER_BNIG	\fIMake the display visually correct Before the Next Interaction Globally\fP
PDEFER_BNIL	\fIMake the display visually correct Before the Next Interaction Locally\fP
PDEFER_ASTI	\fIMake the display visually correct At Some Time\fP
PDEFER_WAITD	\fIMake the display visually correct When the Application Requests It\fP
.fi
.IP \fIMODMOD\fP
An enumerated value specifying the \fImodification mode\fP
to be set for this workstation.
Valid values are defined in phigs77.h:
.sp .4
.nf
.\" .ta .5i +\w'PDEFER_WAITD'u
.ta .8i
PMODE_NIVE	\fINo Immediate Visual Effects\fP
PMODE_UWOR	\fIUpdate Without Regeneration\fP
PMODE_UQUM	\fIUse Quick Update Methods\fP
.fi
.\}
.\" END FORTRAN STRIP
.SS Execution
The \s-2SET DISPLAY UPDATE STATE\s+2 sets the \fIdeferral mode\fP and
\&\fImodification mode\fP entries in the specified workstation's state list.
These modes control the degree to which the display must reflect the
state of the central structure store and the workstation tables.
.LP
.I "Deferral Modes"
.LP
The deferral mode \s-2PDEFER_ASAP\s+2 (\fIAs Soon As Possible\fP) demands that the
display be consistent with the structure store and the workstation state
list at all times.  This typically causes a regeneration (in other words, 
clearing of 
the display and traversal of all posted structure networks) for every
change to a structure appearing on the workstation, and for every change
to the workstation's state list. The modification
mode is unused when the deferral mode is \s-2ASAP\s+2.
.LP
The deferral mode \s-2PDEFER_BNIG\s+2 (\fIBefore the Next Interaction Globally\fP)
behaves just like \s-2PDEFER_ASAP\s+2 when
any input device is active on \fIany\fP workstation.  
The deferral mode \s-2PDEFER_BNIL (\fIBefore the Next Interaction Locally\fP)
behaves just like \s-2PDEFER_ASAP\s+2 when
any input device is active on \fIthis\fP workstation.  
Otherwise, they behave exactly like \fIAt Some Time\fP, as described below.
An input device is considered \fIactive\fP
the entire time it is in \s-2EVENT\s+2 or \s-2SAMPLE\s+2 mode, or
while a \s-2REQUEST\s+2
is pending for the device (although nothing but window redisplay can
occur while a \s-2REQUEST\s+2 is pending, because it necessarily blocks).
.LP
The deferral mode \s-2PDEFER_ASTI\s+2 (\fIAt Some Time\fP) updates the display 
only at certain times, which are at the discretion of the
\s-2PEX\s+2 implementation and are workstation dependent.  
.LP
The deferral mode \s-2PDEFER_WAIT\s+2 (\fIWhen the Application Requests It\fP) 
does not implicitly update the display.
Explicit updates are requested by using \s-2REDRAW ALL STRUCTURES\s+2 
or \s-2UPDATE WORKSTATION\s+2 with \s-2PERFORM\s+2.  
.LP
.I "Modification Modes"
.LP
During modification mode \s-2PDEFER_NIVE\s+2 (\fINo Immediate Visual Effects\fP), 
the only changes to the display are those that would be done
in accordance with the deferral mode.    
.LP
\fBNote:\fP  \fIWhen the Application Requests It\fP and 
\fINo Immediate Visual Effects\fP 
used together prohibit any change to the display in response to
changes in the central structure store or the workstation state lists.
.LP
The modification mode \s-2PDEFER_UWOR\s+2 (\fIUpdate Without Regeneration\fP) 
performs all updates that can be realized immediately
without regenerating the entire display.
This includes the actions whose \fIdynamic modification accepted\fP
entries in the workstation description table are set to \fIImmediately\fP.  
.LP
The modification mode \s-2PDEFER_UQUM\s+2 (\fIUse Quick Update Methods\fP) 
allows use of workstation dependent simulations 
of changes that cannot be performed immediately
unless the display is regenerated.  
These simulations are described in the section 
\fIAvailable Quick Update Methods\fP.  
Actions for which a \fIquick update method\fP is available
have \fIdynamic modification accepted\fP
entries in the workstation description table set to \fICan Be Simulated\fP.  
As in \fIUpdate Without Regeneration\fP mode, actions whose
\fIdynamic modification accepted\fP
entries in the workstation description table are set to \fIImmediately\fP
are performed immediately.  
Unless an action can be simulated or the update performed immediately,
the update is deferred, as if the modification mode were
\fINo Immediate Visual Effects\fP.  
.LP
.I "State of Visual Representation"
.LP
The workstation's \fIstate of visual representation\fP indicates whether
the display is \fICorrect\fP, \fISimulated\fP (but no updates
have been deferred), or \fIDeferred\fP.  This state list value may
be obtained using
\s-2INQUIRE DISPLAY UPDATE STATE(3P)\s+2.  
.LP
Changing the \fIdeferral mode\fP causes a regeneration, if the
display is not correct and the new \fIdeferral mode\fP requires it.  
Changing the \fImodification mode\fP
has no retroactive effect on previous changes
that have been simulated or deferred.  
.LP
.I "Available Quick Update Methods"
.LP
Quick update methods are dependent on the server implementation.
The \s-2PEX-SI API\s+2 does not provide any quick updates.
.LP
.I "Interactions between Deferral and Modification Modes and X Window System"
.LP
\s-2PEX-SI\s0
regenerates the image from the
\s-2CSS\s+2
when the window is damaged by window system events.  
This can occur even if the deferral mode is
\fIWhen the Application Requests It\fP 
(\s-2WAIT\s+2) and the 
modification mode is \fINo Immediate Visual Effects\fP,
which used together prohibit implicit changes to the display.  
However, only the damaged portion of the
\s-2PEX-SI\s0
canvas is repainted.  
Hence, the regeneration may use newer information than that which 
generated the older, out-of-date, but not damaged portion, which
is also visible and may not match the newly drawn portion.  
To remove any visible mismatch, the entire window can be updated by selecting
\fIRefresh\fR from the canvas's \fIFrame\fR menu (assuming that the
user is using XView).  
.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 "UPDATE WORKSTATION (3P)"
.SM "REDRAW ALL STRUCTURES (3P)"
.SM "INQUIRE DISPLAY UPDATE STATE (3P)"
.SM "INQUIRE DEFAULT DISPLAY UPDATE STATE (3P)"
.fi