POPUPWINDOW WIDGET(3W) — OLIT

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);

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 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. 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.
PopupWindow Coloration

the diagram Popup Window Coloration illustrates the resources that affect the coloration of the PopupWindow widget.

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 (cont.)
            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
     XtNuserData XtPointer      NULL     SGI
         XtNvPad Dimension         4       I
       XtNvSpace 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                    Type     Default   Access
    XtNallowShellResize                 Boolean        TRUE      SGI
   XtNancestorSensitive                 Boolean        TRUE       G∗
               XtNapply          XtCallbackList        NULL        I
          XtNbackground                   Pixel       White SGI†
    XtNbackgroundPixmap                  Pixmap      (none) SGI†
         XtNborderColor                   Pixel       Black SGI†
        XtNborderPixmap                  Pixmap      (none) SGI†
         XtNborderWidth               Dimension           0      SGI XtNcreatePopupChildProc XtCreatePopupChildProc        NULL      SGI
               XtNdepth                     int (parent’s)       GI
     XtNdestroyCallback          XtCallbackList        NULL       SI
         XtNfooterPanel                  Widget      (none)        G
            XtNgeometry                  String        NULL       GI PopupWindow Resource Set (cont.)
               Name            Type       Default Access
          XtNheight       Dimension (calculated)     SGI
       XtNheightInc             int            -1     SGI
           XtNinput         Boolean         FALSE       G XtNlowerControlArea          Widget        (none)       G
      XtNmaxAspectX        Position            -1     SGI
      XtNmaxAspectY        Position            -1     SGI
      XtNminAspectX        Position            -1     SGI
      XtNminAspectY        Position            -1     SGI
XtNpopdownCallback XtCallbackList          NULL      SI
   XtNpopupCallback XtCallbackList          NULL      SI
           XtNreset XtCallbackList          NULL       I
    XtNresetFactory XtCallbackList          NULL       I
       XtNsaveUnder         Boolean         FALSE     SGI
       XtNsensitive         Boolean          TRUE     GI∗
     XtNsetDefaults XtCallbackList          NULL       I
           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
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
ResourceButton Name

XtNapplyApply XtNresetReset XtNresetFactoryReset 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. 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. 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 pushpin, the application should not assume that the pop-down will occur even though it has allowed it.