Name

XtCreatePopupShell — create a pop-up shell. 

Synopsis

Widget XtCreatePopupShell(name, widget_class, parent, args, num_args)

    String name;
    WidgetClass widget_class;
    Widget parent;
    ArgList args;
    Cardinal num_args;

Arguments

nameSpecifies the text name for the created shell widget. 

widget_class
Specifies the widget class pointer for the created shell widget.

parentSpecifies the parent widget. 

argsSpecifies the argument list to override the resource defaults. 

num_argsSpecifies the number of arguments in the argument list. 

Description

XtCreatePopupShell creates a pop-up shell widget, suitable for containing one composite or simple widget that is to be popped up.  Pop-up widgets are used to create windows that are descendants of the root window (rather than the application’s main window) so that the pop-up window can appear anywhere on the screen, not just with the application.  Therefore, pop ups have their own shell widget parent. 

For a widget to pop up, it must be the child of a pop-up widget shell.  A pop-up shell is never allowed more than one child, referred to as the pop-up child.  Both the shell and child taken together are referred to as the pop up. 

XtCreateManagedWidget is used to create the pop up’s child (which is the widget which will be visible to the user).  After the pop-up shell and its child are created, the shell can be popped up. 

There are currently two classes of pop-up shells.  They are listed in the table below and defined in <X11/Shell.h>.  Either can be passed to XtCreatePopupShell as the widget_class argument. 

The overrideShellWidgetClass window is created with the override-redirect window attribute set, thereby forcibly bypassing window management. transientShellWidgetClass hints to the window manager that it should not decorate the window as it would a general application and asks it to allow it to bypass its geometry management.  The latter approach is preferred, but the former may be used for dropdown menus and other short-term windows. 

The XtCreatePopupShell function ensures that the specified class is a subclass of Shell and, rather than using insert_child to attach the widget to the parent’s children list, attaches the shell to the parent’s pop-ups list directly.  The pop-up shell is not a normal child of its parent--a pop-up child is kept on its parent’s list of pop-up children. 

The pop-up shell accepts a resource callback list named XtNpopupCallback that will get called back when the widget is popped up.  There is an analogous resource, XtNpopdownCallback, that is invoked when the widget is popped down.  These callbacks provide the opportunity either to make last-minute changes to a pop-up child before it is popped up or to change it after it is popped down.  Note that excessive use of pop-up callbacks can make popping up occur more slowly. 

Once a pop-up shell is created, the single child of the pop-up shell can be created in one of three ways:

•At startup, an application can create the child of the pop-up shell.  This is appropriate for pop-ups that are composed of a fixed set of widgets.  The application can change the state of the subparts of the pop-up child as the application state changes.  For example, if an application creates a static menu, it can call XtSetSensitive (or, in general, XtSetValues) on any of the buttons that make up the menu.  Creating the pop-up child at this time means that pop-up time is minimized, especially if the application calls XtRealizeWidget on the pop-up shell at startup.  When the menu is needed, all the widgets that make up the menu already exist and need only be mapped.  The menu should pop up as quickly as the X server can respond. 

•An application can postpone the creation of the child until it is needed, which minimizes application startup time, but slows pop-up time.  This approach allows the pop-up child to reconfigure itself each time it is popped up.  In this case, the pop-up child creation routine should poll the application to find out if it should change the sensitivity of any of its subparts. 

•An application can use work procedures (XtAddWorkProc) to create the child during application idle time.  This solves both the above problems, but may introduce random user response delays. 

The pop-up shell accepts a resource function pointer (of type XtRFunction) that gets invoked when a widget is popped up.  The resource is named XtNcreatePopupChildProc.  It can be used to create the pop-up child, if one does not exist at the time the pop-up is invoked. 

Pop-up child creation does not map the pop up, even if you create the child and call XtRealizeWidget on the pop-up shell.  Pop ups can be popped up through several mechanisms:

•A call to XtPopup. 

•One of the supplied callback procedures (for example, XtCallbackNone, XtCallbackNonexclusive, or XtCallbackExclusive). 

•The standard translation action XtMenuPopup. 

For a discussion of the underlying concepts of override-redirection, see Chapter 4, An Example Application  in Volume One, Xlib Programming Manual. 

See Also

XtCallbackExclusive(1), XtCreateManagedWidget(1), XtNameToWidget(1), XtPopdown(1), XtPopup(1).