Manual pages › OPEN LOOK widgets (3W)
olPopWinShl(3W)
PopupWindowShell
From the original Amiga UNIX 2.1 manual. Some things it mentions may not be in this release.
WIDGET CLASS NAME · SYNOPSIS · DESCRIPTION · SUBSTRUCTURE · RESOURCES
WIDGET CLASS NAME
PopupWindowShell
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <PopupWindo.h>
static 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);
w = XtCreateWidget(name, widget-class, upper_controlarea, ...);
w = XtCreateWidget(name, widget-class, lower_controlarea, ...);
w = XtCreateWidget(name, widget-class, footerarea, ...);
.
.
.
XtPopup(popupwindow, XtGrabNone);
Amiga Unix Last change: 1
DESCRIPTION
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
- 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 But-
tons 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 win-
dow.
Amiga Unix Last change: 2
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.
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 (upper_controlarea and lower_controlarea) 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.
Amiga Unix Last change: 3
PopupWindow Coloration Figure 2 illustrates the resources
that affect the coloration of the PopupWindow widget.
Figure 2. Popup Window Coloration
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.
Amiga Unix Last change: 4
_______________________________________________________________________
_____________________Application_Resources_(cont.)_____________________
Name Class Type Default Access
_______________________________________________________________________
Amiga Unix Last change: 5
() MISC. REFERENCE MANUAL PAGES ()
_______________________________________________________________________
|_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 |
|_________________|__________________|___________|____________|________|
- The default is TRUE for the Upper Control Area and FALSE
for the Lower Control Area.
= The default is OL_FIXEDCOLS for the Upper Control Area
and OL_FIXEDROWS 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
____________________________________________________________________________________________________
_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____
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
Amiga Unix Last change: 1
() MISC. REFERENCE MANUAL PAGES ()
____________________________________________________________________________________________________
_XtNheightInc______________XtCHeightInc______________int______________________-1_____________SGI____
XtNinput XtCInput Boolean FALSE G
____________________________________________________________________________________________________
_XtNlowerControlArea_______XtCLowerControlArea_______Widget___________________(none)_________G______
|________________________|_________________________|________________________|________ | |
|________________________|_PopupWindow_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___|
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
Amiga Unix Last change: 2
() MISC. REFERENCE MANUAL PAGES ()
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.
Amiga Unix Last change: 3
() MISC. REFERENCE MANUAL PAGES ()
The labels for these buttons are listed below, in the order
they appear in the Lower Control Area:
____________________________________
|_Resource__________Button_Name_____|
| XtNapply Apply |
| 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 applica-
tion that this may be done by issuing the XtNverify call-
backs, then checking the state of the pushpin.
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 Contro-
lArea 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 PopupWin-
dow 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.
XtNverify This resource defines the callbacks to be invoked when the PopupWindow attempts to pop itself down. The call_data 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 call_data 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
Amiga Unix Last change: 4 () MISC. REFERENCE MANUAL PAGES ()
pushpin, the application should not assume that the pop-down will occur even though it has allowed it.
Amiga Unix Last change: 5