POPUPWINDOW WIDGET(3
MI
W)
SC. REFERENCE MANUAL PA
PG
OE
PS
UPWINDOW WIDGET(3W)
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
POPUPWINDOW WIDGET(3
MI
W)
SC. REFERENCE MANUAL PA
PG
OE
PS
UPWINDOW WIDGET(3W)
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 win-
dow and provides a simple interface for populating the win-
dow 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 fol-
lowing 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
POPUPWINDOW WIDGET(3
MI
W)
SC. REFERENCE MANUAL PA
PG
OE
PS
UPWINDOW WIDGET(3W)
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 applica-
tion is building a command window, it has to create what-
ever 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 func-
tion. 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 Win-
dow 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 con-
tainer (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 con-
trol 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 applica-
tion.
Amiga Unix Last change: 3
POPUPWINDOW WIDGET(3
MI
W)
SC. REFERENCE MANUAL PA
PG
OE
PS
UPWINDOW WIDGET(3W)
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
POPUPWINDOW WIDGET(3
MI
W)
SC. REFERENCE MANUAL PA
PG
OE
PS
UPWINDOW WIDGET(3W)
_______________________________________________________________________
_____________________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 | Xt
|CMaxAspectX | Positi
|on | -1 || SGI | | |
|____________________|___|_________________|_______|________|______________||_______| | |
|_XtNmaxAspectY______|__Xt
|CMaxAspectY______|__Positi
|on______|__-1__________||_SGI___| | |
| XtNmaxHeight | Xt
|CMaxHeight | Dimens
|ion | OL_IGNORE || SGI | | |
|____________________|___|_________________|_______|________|______________||_______| | |
|_XtNmaxWidth________|__Xt
|CMaxWidth________|__Dimens
|ion_____|__OL_IGNORE___||_SGI___| | |
| XtNminAspectX | Xt
|CMinAspectX | Positi
|on | -1 || SGI | | |
|____________________|___|_________________|_______|________|______________||_______| | |
|_XtNminAspectY______|__Xt
|CMinAspectY______|__Positi
|on______|__-1__________||_SGI___| | |
| XtNminHeight | Xt
|CMinHeight | Dimens
|ion | OL_IGNORE || SGI | | |
|____________________|___|_________________|_______|________|______________||_______| | |
|_XtNminWidth________|__Xt
|CMinWidth________|__Dimens
|ion_____|__OL_IGNORE___||_SGI___| | |
| XtNpopdownCallback | Xt
|CCallback | XtCall
|backList| NULL || SI | | |
|____________________|___|_________________|_______|________|______________||_______| | |
|_XtNpopupCallback___|__Xt
|CCallback________|__XtCall
|backList|__NULL________||_SI____| | |
| XtNpushpin | Xt
|CPushpin | OlDefi
|ne | OL_OUT || GI | | |
|____________________|___|_________________|_______|________|______________||_______| | |
|_XtNreset___________|__Xt
|CCallback________|__XtCall
|backList|__NULL________||_I_____| | |
| XtNresetFactory | Xt
|CCallback | XtCall
|backList| NULL || I | | |
|____________________|___|_________________|_______|________|______________||_______| | |
|_XtNsaveUnder_______|__Xt
|CSaveUnder_______|__Boolea
|n_______|__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 Con-
trol Area; conversely, where a resource has no callback
defined by the application, no button is shown. The call-
backs 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