PopupWindowShell(3w) — OLIT Widget Set
NAME
PopupWindowShell − popup window shell widget
SYNOPSIS
#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/PopupWindo.h>
. . .
Apply( w, client_data, call_data); Widget w;
XtPointer client_data;
XtPointer call_data;
{ /∗ minimal callback ∗/
printf( "apply callback\n" );
}
XtCallbackRec applycalls[] = {
{ Apply, NULL },
{ NULL, NULL },
};
. . .
Widget applycalls;
XtSetArg( args[0], XtNapply, (XtArgVal) &applycalls);
String name;
Widget control;
ArgList args;
my_popup = XtCreatePopupShell( name, popupWindowShellWidgetClass,
my_parent, args, num_args);
. . .
Widget lower_area, upper_area, footer;
XtSetArg( args[0], XtNupperControlArea, (XtArgVal) &upper_area); XtSetArg( args[1], XtNlowerControlArea, (XtArgVal) &lower_area); ;
XtSetArg( args[2], XtNfooterPanel, (XtArgVal) &footer);
XtGetValues( my_popup, args, 3);
Widget an_upper_item, a_lower_item a_footer_item;
WidgetClass upper_class, lower_class, footer_class;
String upper_name, lower_name, footer_name;
an_upper_item = XtCreate( upper_name, upper__class, upper_area, args, num_args);
a_lower_item = XtCreate( lower_name, lower_class, lower_area, args, num_args);
a_footer_item = XtCreate( footer_name, footer_class, footerarea, args, num_args);
XtPopup( my_popup, XtGrabNone);
DESCRIPTION
The PopupWindow widget is used to implement the OPEN LOOK property window, managing its creation and providing a simple interface for populating the window with controls.
However, the PopupWindow has no innate semantics to relate the controls to 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.
Default Window Decorations
Resource Type Default
_
XtNmenuButton Boolean FALSE
XtNpushpin OlDefine OL_OUT
XtNresizeCorners Boolean FALSE
XtNwindowHeader Boolean TRUE
Components
The PopupWindow widget has the following parts:
• upper ControlArea
• lower ControlArea
• window border
• popup Window Menu
• settings menu (conditional)
• Apply nutton (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 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
subwidgets
The PopupWindowShell contains three subwidgets, a FooterPanel, and two ControlAreas, provided automatically, and accessible through the following resources:
XtNfooterPanel,
XtNlowerControlArea,
XtNupperControlArea.
Figure 2 PopupWindowShell Subwidgets PopupWindowShell
|
_______________________________________________
| | |
FooterPanel upper ControlArea lower ControlArea (XtNfooterPanel) (XtNuppercontrolArea) (XtNlowercontrolArea)
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.
Subclass Shell Widget
The PopupWindow widget is a sub-class of Shell so, the XtCreatePopupShell() routine is used to create a pop-up window instead of the normal XtCreateWidget().
Popping the Window Up and 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.
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 ControlAreas 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 PopupWindowShell 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.
Coloration
of the PopupWindowShell widget.
Figure 3 Popup Window Coloration
Keyboard Traversal
The PopupWindowShell widget has a number of components which the user can traverse between. The buttons in the lower ControlArea and in the Settings menu have the following mnemonics.
Resource Button Name Mnemonic
_
XtNapply Apply A
XtNreset Reset R
XtNresetFactory Reset to Factory
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
_
Activation Type Expected Results
_
OL_CANCEL Popdown window
OL_DEFAULTACTION
Call OlActivateWidget for the
OL_SELECTKEY
OL_TOGGLEPUSHPIN Toggle pushpin state
RESOURCES
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.
Table 1 PopupWindow Control Area Resources
Application Resources
Name Type Default Access
XtNalignCaptions Boolean I
XtNcenter Boolean FALSE I
XtNhPad Dimension 4 I
XtNhSpace Dimension 4 I
XtNlayoutType OlDefine I
XtNmeasure int 1 I
XtNsameSize OlDefine OL_COLUMNS I
XtNuserData XtPointer NULL SGI
XtNvPad Dimension 4 I
XtNvSpace Dimension 4 I
Access:S = XtSetValues G = XtGetValues
I = init timeO = other access
†The default is TRUE for the upper ControlAreaand FALSE for the lower ControlArea.
†The default is OL_FIXEDCOLS for the upper ControlArea and OL_FIXEDROWS for the lower ControlArea.
Footer Resources
Table 2 PopupWindowShell Resource Set
PopupWindowShell Resource Set
Name Type Default Access
XtNallowShellResize Boolean TRUE SGI
XtNancestorSensitive Boolean TRUE GO
XtNapply XtCallbackList NULL I
XtNapplyButton Widget NULL G
XtNbackground Pixel XtDefaultBackground SGI
XtNbackgroundPixmap Pixmap (none) SGI
XtNborderColor Pixel XtDefaultForeground SGI
XtNborderPixmap Pixmap (none) SGI
XtNborderWidth Dimension 0 SGI
XtNconsumeEvent XtCallbackList NULL SGI
XtNcreatePopupChildProc XtCreatePopupChildProc NULL SGI
XtNdepth int (parent’s) GI
XtNdestroyCallback XtCallbackList NULL SI
XtNfocusWidget Widget NULL SGI
XtNfooterPanel Widget (none) G
XtNgeometry String NULL GI
XtNheight Dimension (calculated) SGI
XtNheightInc int -1 SGI
XtNinput Boolean FALSE G
XtNlowerControlArea Widget (none) G
XtNmaxAspectX int -1 SGI
XtNmaxAspectY int -1 SGI
XtNmaxHeight int OL_IGNORE SGI
XtNmaxWidth int OL_IGNORE SGI
XtNminAspectX int -1 SGI
XtNminAspectY int -1 SGI
XtNminHeight int OL_IGNORE SGI
XtNminWidth int OL_IGNORE SGI
XtNpopdownCallback XtCallbackList NULL SI
XtNpopupCallback XtCallbackList NULL SI
XtNpushpin OlDefine OL_OUT GI
XtNreset XtCallbackList NULL I
XtNresetButton Widget NULL G
XtNresetFactory XtCallbackList NULL I
XtNresetFactoryButton Widget NULL G
XtNresizeCorners Boolean True SGI
XtNsaveUnder Boolean FALSE SGI
XtNsensitive Boolean TRUE GIO
XtNsetDefaults XtCallbackList NULL I
XtNsetDefaultsButton Widget NULL G
XtNtitle String NULL SGI
XtNupperControlArea Widget (none) G
XtNuserData XtPointer NULL SGI
XtNverify XtCallbackList NULL I
XtNwidth Position (calculated) SGI
XtNwidthInc Position -1 SGI
XtNx Position 0 SGI
XtNy Position 0 SGI
Access:S = XtSetValues G = XtGetValues
I = init timeO = other access
† see resources(3w)
XtNapply
class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:II’u’
XtNreset
class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:II’u’
XtNresetFactory
class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:II’u’
XtNsetDefaults
class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:II’u’
Action: callback lists for buttons in the lower ControlArea 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.
Table 3 Popup Button Labels
Popup Button Labels
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 application that this may be done by issuing the XtNverify callbacks, then checking the state of the pushpin.
XtNapplyButton
class:XtNApplyButtontype:Widgetdefault:NULLNULL’u’access:GG’u’
XtNresetButton
class:XtCResetButtontype:Widgetdefault:NULLNULL’u’access:GG’u’
XtNresetFactoryButton
class:XtCResetFactoryButtontype:Widgetdefault:NULLNULL’u’access:GG’u’
XtNsetDefaultsButton
class:XtCSetDefaultsButtontype:Widgetdefault:NULLNULL’u’access:GG’u’
Action: allows 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
class:XtNfocusWidgettype:Widgetdefault:NULLNULL’u’access:SGISGI’u’
Action: 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
class:XtCFooterPaneltype:Widgetdefault:(none)(none)’u’access:GG’u’
Action: gives 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
class:XtCLowerControlAreatype:Widgetdefault:(none)(none)’u’access:GG’u’
XtNupperControlArea
class:XtCUpperControlAreatype:Widgetdefault:(none)(none)’u’access:GG’u’
Action: give 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.
XtNverify
class:XtCCallbacktype:XtCallbackListdefault:NULLNULL’u’access:II’u’
Action: defines the callbacks to be invoked when popping down
The call_data parameter in the SYNOPSIS 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 pushpin, the application should not assume that the pop-down will occur even though it has allowed it.
XtNpushpin
class:XtNpushpintype:OlDefinedefault:OL_OUTOL_OUT’u’access:GIGI’u’ This resource indicates whether the Popup Window should have a pushpin and, if so, its initial value. The legal values are OL_IN, OL_OUT, and OL_NONE.
SEE ALSO
CoreResources(3W), FlatResources(3W), ShellResources(3W)
Version 3.0 — Last change: 19 July 91