PopupWindowShell(3W) UNIX System V PopupWindowShell(3W)
NAME
PopupWindowShell - creates an OPEN LOOK property window or command window
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <PopupWindo.h>
static void
Apply (w,clientdata,calldata)
Widget w;
XtPointer clientdata, calldata;
{
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);
w = XtCreateWidget(name, widget-class, uppercontrolarea, ...);
w = XtCreateWidget(name, widget-class, lowercontrolarea, ...);
w = XtCreateWidget(name, widget-class, footerarea, ...);
.
.
.
XtPopup(popupwindow, XtGrabNone);
10/89 Page 1
PopupWindowShell(3W) UNIX System V PopupWindowShell(3W)
DESCRIPTION
___________________________________________________
| Default Window Decorations |
|__________________|________________|______________|
| Resource | Type | Default|
|__________________|________________|______________|
|__________________|________________|______________|
| XtNmenuButton | Boolean | FALSE |
|__________________|________________|______________|
| XtNpushpin | OlDefine | OL_OUT |
|__________________|________________|______________|
| XtNresizeCorners | Boolean | FALSE |
|__________________|________________|______________|
| XtNwindowHeader | Boolean | TRUE |
|__________________|________________|______________|
Controls not Automatically Related to Selected Objects
The PopupWindow 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.
PopupWindow Components
The PopupWindow widget has the following parts:
- Upper Control Area
- Lower Control Area
- Window Border
- Popup Window Menu
- Settings Menu (Conditional)
- Apply Button (Conditional)
- Reset Button (Conditional)
- Reset to Factory Button (Conditional)
- Set Defaults Button (Conditional)
- Header
Page 2 10/89
PopupWindowShell(3W) UNIX System V PopupWindowShell(3W)
- Window Mark
- Pushpin (Optional)
- Resize Corners (Optional)
- Footer (Optional)
The Window Border, Popup Window Menu, Header, Window Mark, and Pushpin
provide the end user with window management controls over the PopupWindow
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.
Figure 1. PopupWindow
Automatic Addition of Buttons, Settings Menu
To aid in the creation of a property window, the PopupWindow 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 PopupWindow, the PopupWindow
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.
If the application is building a command window, it has to create
whatever buttons and menus are needed.
Sub-class of the Shell Widget
The PopupWindow widget is a sub-class of the Shell widget. Therefore, as
the SYNOPSIS shows, the XtCreatePopupShell() routine is used to create a
pop-up window instead of the normal XtCreateWidget().
Popping the Pop-up Window Up/Down
The application controls when the PopupWindow widget is to be displayed,
or popped up. As indicated in the SYNOPSIS, the XtPopup() routine can be
used for this.
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 XRaiseWindow function.
However, the application cannot control when the PopupWindow 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 OblongButton widget
in the Lower Control Area, or the end user dismisses the pop-up window
using the Popup Window Menu or pushpin.
10/89 Page 3
PopupWindowShell(3W) UNIX System V PopupWindowShell(3W)
Upper and Lower Control Areas
The Upper and Lower Control Areas are handled by separate widget
interfaces. The SYNOPSIS shows how the widget IDs of the control areas
(uppercontrolarea and lowercontrolarea) and footer container
(footerarea) are obtained from the PopupWindow widget.
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.
If the PopupWindow 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.
PopupWindow Coloration
Figure 2 illustrates the resources that affect the coloration of the
PopupWindow widget.
Figure 2. Popup Window Coloration
Keyboard Traversal
The PopupWindow widget has a number of components which the user can
traverse between. The buttons in the Lower Control Area and in the
Settings Menu have the following mnemonics.
_______________________________________________
| Resource Button Name Mnemonic|
|______________________________________________|
| XtNapply Apply A |
| XtNreset Reset R |
| XtNresetFactory Reset to Factory F |
| XtNsetDefaults Set Defaults S |
|______________________________________________|
These mnemonics will be displayed in the button labels according to the
value returned by OlQueryMnemonicDisplay(). The buttons are created with
XtNtraversalOn set to True.
The TOGGLEPUSHPIN key changes the state of the pushpin in the window
header. If the pushpin is in, TOGGLEPUSHPIN will pull the pin out and
pop down the window. If the pushpin is out, TOGGLEPUSHPIN will stick the
pin in.
_________________________________________________________________________
PopupWindow Activation Types
Page 4 10/89
PopupWindowShell(3W) UNIX System V PopupWindowShell(3W)
_________________________________________________________________________
| PopupWindow Activation Types |
|____________________________|___________________________________________|
| Activation Type | Expected Results |
|____________________________|___________________________________________|
|____________________________|___________________________________________|
| Activation Type | Expected Results |
|____________________________|___________________________________________|
| OL_CANCEL | Popdown window |
| OL_DEFAULTACTION | Call OlActivateWidget for the |
| | default widget with parameter |
| | OL_SELECTKEY |
| OL_TOGGLEPUSHPIN | Toggle pushpin state |
|____________________________|___________________________________________|
SUBSTRUCTURE
Lower Control Area and Upper Control Area components
Names: lowercontrolarea, uppercontrolarea
Class: ControlArea
The following resources are directed to both 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.
_________________________________________________________________________
| Application Resources |
|__________________|__________________|____________|____________|________|
| Name | Class | Type | Default | Access|
|__________________|__________________|____________|____________|________|
|__________________|__________________|____________|____________|________|
| XtNalignCaptions | XtCAlignCaptions | Boolean | † | I |
|__________________|__________________|____________|____________|________|
| XtNcenter | XtCCenter | Boolean | FALSE | I |
|__________________|__________________|____________|____________|________|
| XtNhPad | XtCHPad | Dimension | 4 | I |
|__________________|__________________|____________|____________|________|
| XtNhSpace | XtCHSpace | Dimension | 4 | I |
|__________________|__________________|____________|____________|________|
| XtNlayoutType | XtCLayoutType | OlDefine | ‡ | 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 |
|__________________|__________________|____________|____________|________|
10/89 Page 5
PopupWindowShell(3W) UNIX System V PopupWindowShell(3W)
† The default is TRUE for the Upper Control Area and FALSE for the Lower
Control Area.
‡ The default is OLFIXEDCOLS for the Upper Control Area and
OLFIXEDROWS for the Lower Control Area.
Footer
Names: footerpanel
Class: FooterPanel
RESOURCES
____________________________________________________________________________________________________
| PopupWindow Resource Set |
|________________________|_________________________|________________________|______________|________|
| Name | Class | Type | Default | Access|
|________________________|_________________________|________________________|______________|________|
____________________________________________________________________________________________________
XtNallowShellResize XtCAllowShellResize Boolean TRUE SGI
____________________________________________________________________________________________________
XtNancestorSensitive XtCSensitive Boolean TRUE G*
____________________________________________________________________________________________________
XtNapply XtCCallback XtCallbackList NULL I
____________________________________________________________________________________________________
XtNapplyButton XtCApplyButton Widget NULL G
____________________________________________________________________________________________________
XtNbackground XtCBackground Pixel White SGI†
____________________________________________________________________________________________________
XtNbackgroundPixmap XtCPixmap Pixmap (none) SGI†
____________________________________________________________________________________________________
XtNborderColor XtCBorderColor Pixel Black SGI†
____________________________________________________________________________________________________
XtNborderPixmap XtCPixmap Pixmap (none) SGI†
____________________________________________________________________________________________________
XtNborderWidth XtCBorderWidth Dimension 0 SGI
____________________________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL 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
____________________________________________________________________________________________________
Page 6 10/89
PopupWindowShell(3W) UNIX System V PopupWindowShell(3W)
____________________________________________________________________________________________________
| PopupWindow Resource Set |
|________________________|_________________________|________________________|______________|________|
| Name | Class | Type | Default | Access|
|________________________|_________________________|________________________|______________|________|
XtNfocusWidget XtCFocusWidget Widget NULL SGI
____________________________________________________________________________________________________
XtNinput XtCInput Boolean FALSE G
____________________________________________________________________________________________________
XtNlowerControlArea XtCLowerControlArea Widget (none) G
____________________________________________________________________________________________________
XtNmaxAspectX XtCMaxAspectX int -1 SGI
____________________________________________________________________________________________________
XtNmaxAspectY XtCMaxAspectY int -1 SGI
____________________________________________________________________________________________________
XtNmaxHeight XtCMaxHeight int OL_IGNORE SGI
____________________________________________________________________________________________________
XtNmaxWidth XtCMaxWidth int OL_IGNORE SGI
____________________________________________________________________________________________________
XtNminAspectX XtCMinAspectX int -1 SGI
____________________________________________________________________________________________________
XtNminAspectY XtCMinAspectY int -1 SGI
____________________________________________________________________________________________________
XtNminHeight XtCMinHeight int OL_IGNORE SGI
____________________________________________________________________________________________________
XtNminWidth XtCMinWidth int OL_IGNORE SGI
____________________________________________________________________________________________________
XtNpopdownCallback XtCCallback XtCallbackList NULL SI
____________________________________________________________________________________________________
XtNpopupCallback XtCCallback XtCallbackList NULL SI
____________________________________________________________________________________________________
XtNpushpin XtCPushpin OlDefine OL_OUT GI
____________________________________________________________________________________________________
XtNreset XtCCallback XtCallbackList NULL I
____________________________________________________________________________________________________
XtNresetButton XtCResetButton Widget NULL G
____________________________________________________________________________________________________
XtNresetFactory XtCCallback XtCallbackList NULL I
____________________________________________________________________________________________________
XtNresetFactoryButton XtCResetFactoryButton Widget NULL G
____________________________________________________________________________________________________
XtNresizeCorners XtCResizeCorners Boolean True SGI
____________________________________________________________________________________________________
XtNsaveUnder XtCSaveUnder Boolean FALSE SGI
____________________________________________________________________________________________________
XtNsensitive XtCSensitive Boolean TRUE GI*
____________________________________________________________________________________________________
XtNsetDefaults XtCCallback XtCallbackList NULL I
____________________________________________________________________________________________________
XtNsetDefaultsButton XtCSetDefaultsButton Widget NULL G
____________________________________________________________________________________________________
XtNtitle XtCTitle String NULL SGI
10/89 Page 7
PopupWindowShell(3W) UNIX System V PopupWindowShell(3W)
____________________________________________________________________________________________________
| PopupWindow Resource Set |
|________________________|_________________________|________________________|______________|________|
| Name | Class | Type | Default | Access|
|________________________|_________________________|________________________|______________|________|
|________________________|_________________________|________________________|______________|________|
| 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 |
|________________________|_________________________|________________________|______________|________|
The following resources provide the widget identifier for the buttons
that are created in the PopupWindow widget. The application can add an
accelerator to these buttons, or change the default mnemonic by accessing
the Button's resources.
XtNapply
XtNreset
XtNresetFactory
XtNsetDefaults
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
PopupWindow 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.
The labels for these buttons are listed below, in the order they appear
in the Lower Control Area:
____________________________________
Resource Button Name
____________________________________
XtNapply Apply
Page 8 10/89
PopupWindowShell(3W) UNIX System V PopupWindowShell(3W)
| XtNreset Reset |
| XtNresetFactory Reset to Factory|
| XtNsetDefaults Set Defaults |
|___________________________________|
No space is left for a missing button.
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 PopupWindow widget will attempt to pop itself
down, first checking with the application that this may be done by
issuing the XtNverify callbacks, then checking the state of the pushpin.
XtNapplyButton
XtNresetButton
XtNresetFactoryButton
XtNsetDefaultsButton
These resources allow the application writer to access the widget
identifier of the OblongButton that is created on the Lower Control Area
of the PopupWindow widget when one of the callbacks above is set. Note
that this resource is only accessable through the XtGetvalues routine.
XtNfocusWidget
This is the ID of the widget to get focus the next time this shell takes
focus. Therefore, as a user traverses objects via the keyboard or
explicitly sets focus to an object (e.g.clicking SELECT), the value of
the XtNfocusWidget resource is updated to reflect this as the object with
focus.
XtNfooterPanel
This is the widget ID of the FooterPanel class composite child widget
that handles the Footer; its value is available once the PopupWindow
widget has been created. If the application wants a footer, it can add
one to the composite identified by this resource.
XtNlowerControlArea
XtNupperControlArea
These are the widget IDs of the ControlArea 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 PopupWindow with
controls. These widget IDs are available once the PopupWindow widget has
been created.
Any widgets of the class OblongButton added to the Lower Control Area are
assumed to be window disposition controls; that is, when the end user
activates one of them the PopupWindow widget should pop itself down, if
allowed by the application and the state of the pushpin.
10/89 Page 9
PopupWindowShell(3W) UNIX System V PopupWindowShell(3W)
XtNverify
This resource defines the callbacks to be invoked when the PopupWindow
attempts to pop itself down. The calldata parameter is a pointer to a
variable of type Boolean. It is initially set to TRUE, 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.
Since more than one callback routine may be registered for this resource,
each callback routine can first check the value pointed to by the
calldata 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 TRUE after the last callback returns, the pop-down continues.
Since these callbacks are issued before the PopupWindow checks the state
of the pushpin, the application should not assume that the pop-down will
occur even though it has allowed it.
XtNpushpin
This resource indicates whether the Popup Window should have a pushpin
and, if so, its initial value. The legal values are OLIN, OLOUT, and
OLNONE.
Page 10 10/89