'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olNotice @(#)olNotice	40.3 of 1/8/90
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ig
Modified 10/18/89 by lmh
Modified 10/27/89 by lmh
..
.ds cW NOTICE
.ds rW Notice
.ds nW Notice
.ds wW noticeShell
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""NOTICE WIDGET" 3W "\&"
.if \nX=1 .ds x} ""NOTICE WIDGET" 3W
.if \nX=2 .ds x} ""NOTICE WIDGET" "" "\&"
.if \nX=3 .ds x} ""NOTICE "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
\*(bW\f3Shell\fP
.SH "SYNOPSIS"
.nf
\s-1\f4#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <\*(nW.h>\f1\s+1\f1
.fi
.P
.nf
\s-1\f4static Widget notice, textarea, controlarea, w;
.P
\s-1\f4Arg args[2];
.P
\s-1\f4notice = XtCreatePopupShell(\f2name\f4, \*(wWWidgetClass, ...);
XtSetArg(args[0], XtNtextArea, &textarea);
XtSetArg(args[1], XtNcontrolArea, &controlarea);
XtGetValues(notice, args, 2);
.P
\s-1\f4w = XtCreateWidget(\f2name\f4, \fIwidget-class\f4, controlarea, ...);
\&.
\&.
\&.
\f4XtPopup(notice, XtGrabExclusive);\f1\s+1
.fi
.SH "DESCRIPTION"
.P
\f3\*(rW Components\f1
.P
The \*(bW widget has three components:
a Text Area where the message to the end user is displayed;
a Control Area containing one or more widgets that the end
user uses to control how to continue with an application;
and a Default Button.
Another important element is the Emanate Widget,
which is typically the control activated by the end user that
requires immediate attention.
The application identifies the Emanate Widget to the \*(bW
widget.
.br
.ne3.25i
.BP PSART/ps.notice1
.P
.ce
\f3Figure 1.\f1  Notice Widget
.sp
\f3Sub-class of the Shell Widget\f1
.P
The \*(bW widget is a sub-class of the
\f3Shell\f1
widget.
Therefore,
as the SYNOPSIS shows,
the
\f4XtCreatePopupShell()\f1
routine is used to create a notice instead of the normal
\f4XtCreateWidget()\f1.
.sp
\f3Popping the Notice Up/Down\f1
.P
The application controls when the \*(bW widget is to be
displayed or popped up.
As shown in the SYNOPSIS, the
\f4XtPopup()\f1
routine can be used for this.
.P
However, the application does not need to control when 
the \*(bW widget is to be popped down.
The widget itself detects when to pop down:
the end user clicks SELECT on an
\f3OblongButton\f1
widget in the Control Area.
This behavior requires that there be at least one
\f3OblongButton\f1
widget in the Control Area.
If other types of controls are used instead,
the application can "manually" pop the notice down using a
routine such as
\f4XtPopdown()\f1.
.sp
.ig
\f3Pointer Jumping\f1
.P
When the \*(bW widget pops up,
it moves the pointer to center it over the Default
Button.
As long the end user keeps the pointer within the bounds of the
notice window, the pointer's original position is restored
when the \*(bW widget is popped down.
.P
The end user can disable pointer jumping for a \*(bW widget.
.P
The \*(bW chooses the Default Button at pop-up time according to
the following criteria:
.IP 1 1.5P
The Default Button is the
\f3OblongButton\f1
widget in the Control Area with the resource
\f4XtNdefault\f1
set to
\f4TRUE\f1.
.IP 2 1.5P
If more than one widget meets the above,
one is chosen arbitrarily.
.IP 3 1.5P
If no
\f3OblongButton\f1
widgets have a
\f4TRUE\f1
value for their
\f4XtNdefault\f1
resource,
an
\f3OblongButton\f1
widget is chosen arbitrarily.
.IP 4 1.5P
If there are no
\f3OblongButton\f1
widgets,
another widget is chosen arbitrarily.
.P
If the Default Button chosen in this way does not have the
\f4XtNdefault\f1
resource set to
\f4TRUE\f1,
the \*(bW widget sets the resource to
\f4TRUE\f1.
This will be ignored by a widget that does not recognize the
resource.
.sp
..
\f3Busy Button, Busy Application\f1
.P
When the \*(bW pops up,
it "freezes" the entire application except the Notice to
prevent the end user from interacting with any other part of
the application.
As feedback of this to the user,
the \*(bW causes the headers of all the base windows and pop-up
windows to be stippled in the "busy" pattern,
and causes a stipple pattern in the Emanate Widget.
The latter stipple pattern is caused by setting the
\f4XtNbusy\f1
resource to
\f4TRUE\f1
in the Emanate Widget.
If the widget does not recognize this resource,
nothing will happen.
.P
On popping down,
the \*(bW widget clears all stipple patterns and "unfreezes"
the application.
.sp
\f3Text and Control Areas\f1
.P
The Text and Control Areas are handled by separate widget
interfaces.
The SYNOPSIS shows how the widget IDs of the Text Area
(\f4textarea\f1)
and the Control Area
(\f4controlarea\f1)
are obtained from the \*(bW widget.
.P
The Text and Control Areas abut so that there is no space between
the two.
An application can control the distance between the text and
the controls by setting margins in the Control Area.
.sp
\f3\*(rW Coloration\f1
.P
Figure 2 illustrates the resources that affect the coloration
of the \*(bW widget.
.br
.ne3.5i
.BP PSART/ps.notice2
.P
.ce
\f3Figure 2.\f1  Notice Coloration
.P
.SH "SUBSTRUCTURE"
.P
\f3Control Area component\f1
.P
.nf
Name: controlarea
Class: ControlArea
.fi
.ds cO
.TS H
expand, allbox;
cB s s s s.
Application Resources\\\\*(cO
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.TH
.ds cO " (cont'd)
.T&
lp-2 lp-2 lp-2 lp-2 lp-2.
XtNhPad	XtCHPad	Dimension	0	I
XtNhSpace	XtCHSpace	Dimension	4	I
XtNlayoutType	XtCLayoutType	OllDefine	OL_FIXEDROWS	I
XtNmeasure	XtCMeasure	int	1	I
XtNsameSize	XtCSameSize	OlDefine	OL_COLUMNS	I
XtNvPad	XtCVPad	Dimension	0	I
XtNvSpace	XtCVSpace	Dimension	4	I
.TE
See the \f3ControlArea\f1 widget for the descriptions of these
resources.
.sp
\f3Text Area component\f1
.P
.nf
Name: textarea
Class: StaticText
.fi
.ds cO
.TS H
expand, allbox;
cB s s s s.
Application Resources\\\\*(cO
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.TH
.ds cO " (cont'd)
.T&
lp-2 lp-2 lp-2 lp-2 lp-2.
XtNalignment	XtCAlignment	int	OL_LEFT	I
XtNfont	XtCFont	XFontStruct *	(OPEN LOOK font)	SI
XtNfontColor	XtCFontColor	Pixel	Black*	SGI
XtNlineSpace	XtCLineSpace	int	0	I
XtNstring	XtCString	String	NULL	I
XtNstrip	XtCStrip	Boolean	TRUE	I
XtNwrap	XtCWrap	Boolean	TRUE	I
.TE
See the \f3StaticText\f1 widget for the descriptions of these
resources.
.sp
.SH "RESOURCES"
.ds cO
.TS 
expand, allbox;
cB s s s s
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2
lp-2 lp-2 lp-2 lp-2 lp-2.
\*(bW Resource Set
Name	Class	Type	Default	Access
_
XtNallowShellResize	XtCAllowShellResize	Boolean	TRUE	SGI
XtNancestorSensitive	XtCSenstitive	Boolean	TRUE	G*
XtNbackground	XtCBackground	Pixel	White	SGI\(dg
XtNbackgroundPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNborderColor	XtCBorderColor	Pixel	White	SGI\(dg
XtNborderPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNcontrolArea	XtCControlArea	Widget	(none)	G
XtNcreatePopupChildProc	XtCCreatePopupChildProc	XtCreatePopupChildProc	NULL	SGI
XtNdepth	XtCDepth	int	(parent's)	GI
XtNdestroyCallback	XtCCallback	XtCallbackList	NULL	SI
XtNemanateWidget	XtCEmanateWidget	Widget	(parent's)	SGI
XtNgeometry	XtCGeometry	String	NULL	GI
.TE
.bp
.TS 
expand, allbox;
cB s s s s
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2
lp-2 lp-2 lp-2 lp-2 lp-2.
\*(bW Resource Set
Name	Class	Type	Default	Access
_
XtNheight	XtCHeight	Dimension	(calculated)	SGI
XtNpopdownCallback	XtCCallback	XtCallbackList	NULL	SI
XtNpopupCallback	XtCCallback	XtCallbackList	NULL	SI
XtNsaveUnder	XtCSaveUnder	Boolean	FALSE	SGI
XtNsensitive	XtCSensitive	Boolean	TRUE	GI*
XtNtextArea	XtCTextArea	Widget	(none)	G
XtNuserData	XtCUserData	XtPointer	NULL	SGI
XtNwidth	XtCWidth	Dimension	(calculated)	SGI
XtNx	XtCPosition	Position	0	SGI
XtNy	XtCPosition	Position	0	SGI
.TE
.sp
\f3XtNcontrolArea\f1
.P
This is the widget ID of the
\f3ControlArea\f1
class composite child widget where controls can be attached;
its value is available once the \*(bW widget has been created.
.P
Any widgets of the class
\f3OblongButton\f1
added to the Control Area are assumed to be window
disposition controls;
that is,
when the end user activates one of them, the \*(bW widget pops
itself down.
.sp
\f3XtNemanateWidget\f1
.PP
Range of Values:
.br
.in +5
.nf
(ID of existing widget)
.in -5
.fi
.PP
This resource identifies the Emanate Widget.
On popping up,
the \*(bW widget attempts to set this widget to be busy,
by making its
\f4XtNbusy\f1
resource
\f4TRUE\f1;
if the widget doesn't recognize the resource,
nothing happens.
On popping down,
the \*(bW widget clears the
\f4XtNbusy\f1
resource.
.P
When the \*(bW widget pops up,
it tries not to cover this widget;
this may fail depending on its location and the size of the \*(bW
widget.
.P
The default for this resource is the parent.  The parent, however,
cannot be a Gadget (OblongButtonGadget, for instance).  To emanate a
Notice from a Gadget, specify another widget as the parent and set
\f(CWXtNemanateWidget\fP to the Gadget.
.sp
\f3XtNtextArea\f1
.P
This is the widget ID of the
\f3StaticText\f1
class child widget that controls the Text Area;
its value is available once the \*(bW widget has been created.
