'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olPopWinShl @(#)olPopWinShl	40.3 of 1/8/90
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ig
Modified 10/18/89 and 10/23/89 by lmh
..
.ds cW POPUPWINDOW
.ds rW PopupWindow
.ds nW PopupWindo
.ds wW popupWindowShell
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""POPUPWINDOW WIDGET" 3W "\&"
.if \nX=1 .ds x} ""POPUPWINDOW WIDGET" 3W
.if \nX=2 .ds x} ""POPUPWINDOW WIDGET" "" "\&"
.if \nX=3 .ds x} ""POPUPWINDOW "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
\*(bW\f3Shell\f1
.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 void
Apply (w,client_data,call_data)
Widget w;
XtPointer client_data, call_data;
{
	printf ("Apply callback!\\n");
}

Arg	 args[3];
Widget	 popupwindow, w;
Widget	 uppercontrol, lowercontrol, footer;

static XtCallbackRec applycalls[] = {
	{ Apply, NULL },
	{ NULL, NULL },
};

XtSetArg(args[0], XtNapply, (XtArgVal) applycalls);

popupwindow = XtCreatePopupShell(	"PopupShell",
						popupWindowShellWidgetClass,
						controlparent, args, 1);

XtSetArg(args[0], XtNupperControlArea, &uppercontrol);
XtSetArg(args[1], XtNlowerControlArea, &lowercontrol);
XtSetArg(args[2], XtNfooterPanel, &footer);

XtGetValues(popupshell, args, 3);
.P
\s-1\f4w = XtCreateWidget(\f2name\f4, \f2widget-class\f4, upper_controlarea, ...);
w = XtCreateWidget(\f2name\f4, \f2widget-class\f4, lower_controlarea, ...);
w = XtCreateWidget(\f2name\f4, \f2widget-class\f4, footerarea, ...);
\&.
\&.
\&.
\f4XtPopup(popupwindow, XtGrabNone);\f1\s+1
.fi
.bp
.SH "DESCRIPTION"
.sp
\f3Controls not Automatically Related to Selected Objects\f1
.P
The \*(bW widget can be used to implement the OPEN LOOK
property window.
It manages the creation of a property window and provides a
simple interface for populating the window with controls.
However,
it has no innate semantics to relate the controls with a
selected object; this must be handled by the application.
For example,
the application must dim all the controls if an object selected
by the end user is incompatible with a displayed property
window.
.sp
\f3\*(rW Components\f1
.P
The \*(bW widget has the following parts:
.IP \(em 1.5P
Upper Control Area
.IP \(em 1.5P
Lower Control Area
.IP \(em 1.5P
Window Border
.IP \(em 1.5P
Popup Window Menu
.IP \(em 1.5P
Settings Menu (Conditional)
.IP \(em 1.5P
Apply Button (Conditional)
.IP \(em 1.5P
Reset Button (Conditional)
.IP \(em 1.5P
Reset to Factory Button (Conditional)
.IP \(em 1.5P
Set Defaults Button (Conditional)
.IP \(em 1.5P
Header
.IP \(em 1.5P
Window Mark
.IP \(em 1.5P
Pushpin (Optional)
.IP \(em 1.5P
Resize Corners (Optional)
.IP \(em 1.5P
Footer (Optional)
.P
The Window Border, Popup Window Menu, Header, Window Mark,
and Pushpin provide the end user with window management
controls over the
\*(bW widget.
The Apply, Reset, Reset to Factory, and Set Defaults Buttons
are automatically created, if needed,
to help create a standard layout of a property window.
The application controls which of these,
if any,
appear in the pop-up window.
.br
.ne3.5i
.BP PSART/ps.popup1
.P
.ce
\f3Figure 1.\f1  PopupWindow
.sp
.ig
\f3Pop-up Window Menu\f1
.P
The Pop-up Window Menu is defined in .  The application
programmer controls when the Dismiss choice is changed to a
Cancel choice, as described later.
..
\f3Automatic Addition of Buttons, Settings Menu\f1
.P
To aid in the creation of a property window,
the \*(bW has several callbacks typically used in such a pop-up
window,
for applying, resetting, etc.
For each of these callbacks that the application sets in the
argument list used for creation of the \f3PopupWindow\f1,
the \*(bW widget automatically creates a button in the Lower
Control Area,
and the same button in the Settings Menu.
If none of the callbacks are defined, no buttons are
automatically created and no Settings Menu is created.
.P
If the application is building a command window,
it has to create whatever buttons and menus are needed.
.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 pop-up window instead of the
normal
\f4XtCreateWidget()\f1.
.sp
\f3Popping the Pop-up Window Up/Down\f1
.P
The application controls when the \*(bW widget is to be
displayed, or popped up.
As indicated in the SYNOPSIS, the
\f4XtPopup()\f1
routine can be used for this.
.P
The application also has the responsibility for raising a 
mapped pop-up window to the front if the user attempts to 
pop it up and it's already up.  This can be accomplished using 
the \f3XRaiseWindow\f1 function.
.P
However,
the application cannot control when the \*(bW widget is to be
popped down,
since the end user may have pinned it up with the intent that
it stays up until he or she dismisses it.
The widget itself detects when to pop down:
the end user clicks SELECT on an
\f3OblongButton\f1
widget in the Lower Control Area,
or the end user dismisses the pop-up window using the Popup
Window Menu or pushpin.
.sp
.ig
\f3Pointer Jumping\f1
.P
When the \*(bW widget pops up,
it normally moves the pointer to center it over the Default
Button.
.P
If the pointer is never moved outside the \*(bW widget,
the widget restores the original position of the pointer after
the window is popped down.
.P
The pointer does not jump if the \*(bW is opened up from an
\f2icon\f1
state.
Also,
the end user can disable pointer jumping.
.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 Apply Button,
if present.
.IP 2 1.5P
Otherwise, the Default Button is the
\f3OblongButton\f1
widget in the Control Area with the resource
\f4XtNdefault\f1
set to
\f4TRUE\f1.
.IP 3 1.5P
If more than one widget meets the above,
one is chosen arbitrarily.
.sp
.IP 4 1.5P
If no
\f3OblongButton\f1
widgets have a
\f4TRUE\f1
value for their
\f4XtNdefault\f1
resource,
and the Apply Button is not present,
an
\f3OblongButton\f1
widget is chosen arbitrarily.
.IP 5 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
..
\f3Upper and Lower Control Areas\f1
.P
The Upper and Lower Control Areas are handled by separate
widget interfaces.
The SYNOPSIS shows how the widget IDs of the control areas
(\f4upper_controlarea\f1
and
\f4lower_controlarea\f1)
and footer container
(\f4footerarea\f1)
are obtained from the \*(bW widget.
.P
The two Control Areas and the Footer abut so that there is no
space between them.
An application can control the distance between the
controls in the Control Areas by setting margins in each area.
.P
If the \*(bW widget automatically creates
the Apply, Reset, Reset to Factory, or Set Defaults Buttons,
it puts them in that order in the Lower Control Area.
No space is left for a missing button.
These buttons will also appear before any buttons added to the
Lower Control Area by the application.
.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.popup2
.P
.ce
\f3Figure 2.\f1  Popup Window Coloration
.sp
.SH "SUBSTRUCTURE"
.sp
\f3Lower Control Area and Upper Control Area components\f1
.P
.nf
Names: lowercontrolarea, uppercontrolarea
Class: ControlArea
.fi
.P
The following resources are directed to \f2both\f1
Control Area components.  To set different values for 
the same resources in the different
Control Areas,
the application must access the resources using the appropriate
Control Area widget IDs.
.bp
.ds cO
.TS H
expand, allbox;
cB s s s s.
Application Resources (cont.)
.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.
XtNalignCaptions	XtCAlignCaptions	Boolean	\(dg	I
XtNcenter	XtCCenter	Boolean	FALSE	I
XtNhPad	XtCHPad	Dimension	4	I
XtNhSpace	XtCHSpace	Dimension	4	I
XtNlayoutType	XtCLayoutType	OlDefine	\(dd	I
XtNmeasure	XtCMeasure	int	1	I
XtNsameSize	XtCSameSize	OlDefine	OL_COLUMNS	I
XtNuserData	XtCUserData	XtPointer	NULL	SGI
XtNvPad	XtCVPad	Dimension	4	I
XtNvSpace	XtCVSpace	Dimension	4	I
.TE
.sp -0.5
\s-1
.IP \(dg 3
The default is \f4TRUE\f1 for the Upper Control Area and
\f4FALSE\f1 for the Lower Control Area.
.IP \(dd 3
The default is \f4OL_FIXEDCOLS\f1
for the Upper Control Area and \f4OL_FIXEDROWS\f1
for the Lower Control Area.
\s+1
.P
\f3Footer\f1
.P
.nf
Names: footerpanel
Class: FooterPanel
.fi
.SH "RESOURCES"
.TS
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	XtCSensitive	Boolean	TRUE	G*
XtNapply	XtCCallback	XtCallbackList	NULL	I
XtNbackground	XtCBackground	Pixel	White	SGI\(dg
XtNbackgroundPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNborderColor	XtCBorderColor	Pixel	Black	SGI\(dg
XtNborderPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNborderWidth	XtCBorderWidth	Dimension	0	SGI
XtNcreatePopupChildProc	XtCCreatePopupChildProc	XtCreatePopupChildProc	NULL	SGI
XtNdepth	XtCDepth	int	(parent's)	GI
XtNdestroyCallback	XtCCallback	XtCallbackList	NULL	SI
XtNfooterPanel	XtCFooterPanel	Widget	(none)	G
XtNgeometry	XtCGeometry	String	NULL	GI
XtNheight	XtCHeight	Dimension	(calculated)	SGI
XtNheightInc	XtCHeightInc	int	-1	SGI
XtNinput	XtCInput	Boolean	FALSE	G
XtNlowerControlArea	XtCLowerControlArea	Widget	(none)	G
.TE
.SK
.TS
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 (cont.)
Name	Class	Type	Default	Access
_
XtNmaxAspectX	XtCMaxAspectX	Position	-1	SGI
XtNmaxAspectY	XtCMaxAspectY	Position	-1	SGI
XtNmaxHeight	XtCMaxHeight	Dimension	OL_IGNORE	SGI
XtNmaxWidth	XtCMaxWidth	Dimension	OL_IGNORE	SGI
XtNminAspectX	XtCMinAspectX	Position	-1	SGI
XtNminAspectY	XtCMinAspectY	Position	-1	SGI
XtNminHeight	XtCMinHeight	Dimension	OL_IGNORE	SGI
XtNminWidth	XtCMinWidth	Dimension	OL_IGNORE	SGI
XtNpopdownCallback	XtCCallback	XtCallbackList	NULL	SI
XtNpopupCallback	XtCCallback	XtCallbackList	NULL	SI
XtNpushpin	XtCPushpin	OlDefine	OL_OUT	GI
XtNreset	XtCCallback	XtCallbackList	NULL	I
XtNresetFactory	XtCCallback	XtCallbackList	NULL	I
XtNsaveUnder	XtCSaveUnder	Boolean	FALSE	SGI
XtNsensitive	XtCSensitive	Boolean	TRUE	GI*
XtNsetDefaults	XtCCallback	XtCallbackList	NULL	I
XtNtitle	XtCTitle	String	NULL	SGI
XtNupperControlArea	XtCUpperControlArea	Widget	(none)	G
XtNuserData	XtCUserData	XtPointer	NULL	SGI
XtNverify	XtCCallback	XtCallbackList	NULL	I
XtNwidth	XtCWidth	Position	(calculated)	SGI
XtNwidthInc	XtCWidthInc	Position	-1	SGI
XtNx	XtCPosition	Position	0	SGI
XtNy	XtCPosition	Position	0	SGI
.TE
.sp
\f3XtNapply\f1
.br
.br
\f3XtNreset\f1
.br
.br
\f3XtNresetFactory\f1
.br
.br
\f3XtNsetDefaults\f1
.P
Each of these resources is a callback list that corresponds to
a button in the Lower Control Area and in the Settings Menu.
Typically, an application defines one of these resources only
when it is using the \*(bW widget for a property window.
For each resource with a defined callback, a unique button is
added in the Lower Control Area;
conversely, where a resource has no callback defined by the
application, no button is shown.  The callbacks must be set at
initialization time in order for the buttons to be created.
.bp
The labels for these buttons are listed below,
in the order they appear in the Lower Control Area:
.TS
box, center;
lB lB.
Resource	Button Name
_
.T&
l l.
XtNapply	Apply
XtNreset	Reset
XtNresetFactory	Reset to Factory
XtNsetDefaults	Set Defaults
.TE
.sp
No space is left for a missing button.
.P
In general,
the callback list for one of these resources is issued when the
user activates the button associated with the resource.
After the callbacks are issued,
the \*(bW widget will attempt to pop itself down,
first checking with the application that this may be done by
issuing the
\f4XtNverify\f1
callbacks,
then checking the state of the pushpin.
.ig
To allow for future expansion of features,
the
\f4call_data\f1
parameter of each of these callbacks is set to zero by the
\*(bW before the callbacks are issued. 
..
.sp 0.75
\f3XtNfooterPanel\f1
.P
This is the widget ID of the
\f3FooterPanel\f1
class composite child widget that handles the Footer;
its value is available once the \*(bW widget has been created.
If the application wants a footer,
it can add one to the composite identified by this resource.
.sp
\f3XtNlowerControlArea\f1
.br
.br
\f3XtNupperControlArea\f1
.P
These are the widget IDs of the
\f3ControlArea\f1
class composite child widgets that handle the Lower Control
Area and Upper Control Area,
respectively.
The application can use each widget ID to populate the \*(bW
with controls.
These widget IDs are available once the \*(bW widget has been
created.
.P
Any widgets of the class
\f3OblongButton\f1
added to the Lower Control Area are assumed to be window
disposition controls;
that is,
when the end user activates one of them the \*(bW widget should pop
itself down,
if allowed by the application and the state of the pushpin.
.sp
\f3XtNverify\f1
.P
This resource defines the callbacks to be invoked when the
\*(bW attempts to pop itself down.
The
\f4call_data\f1
parameter is a pointer to a variable of type
\f4Boolean\f1.
It is initially set to
\f4TRUE\f1,
and the application should set a value that reflects whether
the pop-down is allowed.
Typically, the application will use this to prevent a pop-down
so that an error message can be displayed.
.P
Since more than one callback routine may be registered for this
resource,
each callback routine can first check the value pointed to by the
\f4call_data\f1
parameter to see if a previous callback in the list has already
rejected the pop-down attempt.
If one has,
the subsequent callback need not continue evaluating whether a
pop-down is allowed.
If the value is still
\f4TRUE\f1
after the last callback returns,
the pop-down continues.
.P
Since these callbacks are issued before the \*(bW checks the
state of the pushpin,
the application should not assume that the pop-down will occur
even though it has allowed it.
