.\"##
.\" $XConsortium: p234,v 5.2 94/04/17 20:57:09 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.
.ds f \s-2MESSAGE\s+2
.TH "MESSAGE" 3P "29 February 1991"
.SH NAME
MESSAGE \- display a message on a workstation
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pmessage ( ws, msg )
Pint	ws;	\fIworkstation identifier\fP
char	*msg;	\fImessage string\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\*f displays a message (character string) on the specified workstation.
See \fIExecution\fP below for a description of the placement of the
message on the workstation.
.SS C Input Parameters
.IP \fIws\fP
The workstation to send the message to.
.IP \fImsg\fP
The null terminated array of char (character string) to display on the
workstation.
.SS Execution
\*f displays the specified character string on the specified workstation.
The location of the message's display is dependent upon the workstation
type as follows:
.IP "\fIx_tool\fR and \fIx_drawable\fR workstation types"
If the workstation has a text subwindow associated with it, the message is
written to that window.  If a \s-2STRING\s+2 input device is also active
and using the text subwindow, the message will be interleaved (correctly)
with the operator input.
.IP
If the workstation does not have a text subwindow associated with it, the
message will be written to the lower left corner of the workstation's
graphics window and will be removed upon the next clearing of that window.
See \s-2UPDATE WORKSTATION\s+2 and \s-2SET DISPLAY UPDATE STATE\s+2 for a
description of when the window is cleared.  See \s-2WORKSTATION TYPE
SET\s+2 for a description of how to associate a text subwindow with a
workstation.
.LP
The \s-2MESSAGE\s+2 function only display a message when the \s-2PM\s+2 is running.
If the \s-2PM\s+2 is not running then the function is silently ignored.
.LP
When the \s-2PM\s+2 is running the message function causes a window to pop up
on the display.
The window contains the message and a button labelled ``Done''.
Selecting the Done button causes the window to disappear.
.LP
The message window is implemented with Athena widgets.
The resource database attributes recognized by the message window
and the default values are:
.nf
.ta .5i +2i
	*message.box.orientation	vertical,
	*message.box.allowResize	True,
	*message*label.resize	True,
	*message*button.label	Done
.SH ERRORS
.IP 003
Ignoring function, function requires state (\s-2PHOP, WSOP, *, *\s+2)
.IP 054
Ignoring function, the specified workstation is not open
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "WORKSTATION TYPE SET (3P)"
.\" .SM "TEXT (3P)"
.\" .SM "ANNOTATION TEXT RELATIVE (3P)"
.fi