Chapter 5. Pop-Up Widgets

Table of Contents

Pop-Up Widget Types

Creating a Pop-Up Shell

Creating Pop-Up Children

Mapping a Pop-Up Widget

Unmapping a Pop-Up Widget

Pop-up widgets are used to create windows outside of the window hierarchy defined by the widget tree. Each pop-up child has a window that is a descendant of the root window, so that the pop-up window is not clipped by the pop-up widget's parent window. Therefore, pop-ups are created and attached differently to their widget parent than normal widget children.

A parent of a pop-up widget does not actively manage its pop-up children; in fact, it usually does not operate upon them in any way. The popup_list field in the CorePart structure contains the list of its pop-up children. This pop-up list exists mainly to provide the proper place in the widget hierarchy for the pop-up to get resources and to provide a place for XtDestroyWidget to look for all extant children.

A composite widget can have both normal and pop-up children. A pop-up can be popped up from almost anywhere, not just by its parent. The term child always refers to a normal, geometry-managed widget on the composite widget's list of children, and the term pop-up child always refers to a widget on the pop-up list.

Pop-Up Widget Types

There are three kinds of pop-up widgets:

• Modeless pop-ups

  A modeless pop-up (for example, a dialog box that does not prevent continued interaction with the rest of the application) can usually be manipulated by the window manager and looks like any other application window from the user's point of view. The application main window itself is a special case of a modeless pop-up.

• Modal pop-ups

  A modal pop-up (for example, a dialog box that requires user input to continue) can sometimes be manipulated by the window manager, and except for events that occur in the dialog box, it disables user-event distribution to the rest of the application.

• Spring-loaded pop-ups

  A spring-loaded pop-up (for example, a menu) can seldom be manipulated by the window manager, and except for events that occur in the pop-up or its descendants, it disables user-event distribution to all other applications.

Modal pop-ups and spring-loaded pop-ups are very similar and should be coded as if they were the same. In fact, the same widget (for example, a ButtonBox or Menu widget) can be used both as a modal pop-up and as a spring-loaded pop-up within the same application. The main difference is that spring-loaded pop-ups are brought up with the pointer and, because of the grab that the pointer button causes, require different processing by the Intrinsics. Furthermore, all user input remap events occurring outside the spring-loaded pop-up (e.g., in a descendant) are also delivered to the spring-loaded pop-up after they have been dispatched to the appropriate descendant, so that, for example, button-up can take down a spring-loaded pop-up no matter where the button-up occurs.

Any kind of pop-up, in turn, can pop up other widgets. Modal and spring-loaded pop-ups can constrain user events to the most recent such pop-up or allow user events to be dispatched to any of the modal or spring-loaded pop-ups currently mapped.

Regardless of their type, all pop-up widget classes are responsible for communicating with the X window manager and therefore are subclasses of one of the Shell widget classes.

Creating a Pop-Up Shell

For a widget to be popped up, it must be the child of a pop-up shell widget. None of the Intrinsics-supplied shells will simultaneously manage more than one child. Both the shell and child taken together are referred to as the pop-up. When you need to use a pop-up, you always refer to the pop-up by the pop-up shell, not the child.

To create a pop-up shell, use XtCreatePopupShell.

Widget XtCreatePopupShell(String name, WidgetClass widget_class, Widget parent, ArgList args, Cardinal num_args);

name	Specifies the instance name for the created shell widget.
widget_class	Specifies the widget class pointer for the created shell widget.
parent	Specifies the parent widget. Must be of class Core or any subclass thereof.
args	Specifies the argument list to override any other resource specifications.
num_args	Specifies the number of entries in the argument list.

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 popup_list directly.

The screen resource for this widget is determined by first scanning args for the XtNscreen argument. If no XtNscreen argument is found, the resource database associated with the parent's screen is queried for the resource name.screen, class Class.Screen where Class is the class_name field from the CoreClassPart of the specified widget_class. If this query fails, the parent's screen is used. Once the screen is determined, the resource database associated with that screen is used to retrieve all remaining resources for the widget not specified in args.

A spring-loaded pop-up invoked from a translation table via XtMenuPopup must already exist at the time that the translation is invoked, so the translation manager can find the shell by name. Pop-ups invoked in other ways can be created when the pop-up actually is needed. This delayed creation of the shell is particularly useful when you pop up an unspecified number of pop-ups. You can look to see if an appropriate unused shell (that is, not currently popped up) exists and create a new shell if needed.

To create a pop-up shell using varargs lists, use XtVaCreatePopupShell.

Widget XtVaCreatePopupShell(String name, WidgetClass widget_class, Widget parent, ...);

name	Specifies the instance name for the created shell widget.
widget_class	Specifies the widget class pointer for the created shell widget.
parent	Specifies the parent widget. Must be of class Core or any subclass thereof.
...	Specifies the variable argument list to override any other resource specifications.

XtVaCreatePopupShell is identical in function to XtCreatePopupShell with the args and num_args parameters replaced by a varargs list as described in Section 2.5.1.

Creating Pop-Up Children

Once a pop-up shell is created, the single child of the pop-up shell can be created either statically or dynamically.

At startup, an application can create the child of the pop-up shell, which is appropriate for pop-up children 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 early 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.

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

Pop-up child creation does not map the pop-up, even if you create the child and call XtRealizeWidget on the pop-up shell.

All shells have pop-up and pop-down callbacks, which 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.

Mapping a Pop-Up Widget

Pop-ups can be popped up through several mechanisms:

• A call to XtPopup or XtPopupSpringLoaded.

• One of the supplied callback procedures XtCallbackNone, XtCallbackNonexclusive, or XtCallbackExclusive.

• The standard translation action XtMenuPopup.

Some of these routines take an argument of type XtGrabKind, which is defined as

typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind;

The create_popup_child_proc procedure pointer in the shell widget instance record is of type *XtCreatePopupChildProc.

void *XtCreatePopupChildProc(Widget w);

void *XtCreatePopupChildProc(Widget w);

w	Specifies the shell widget being popped up.

To map a pop-up from within an application, use XtPopup.

void XtPopup(Widget popup_shell, XtGrabKind grab_kind);

popup_shell	Specifies the shell widget.
grab_kind	Specifies the way in which user events should be constrained.

The XtPopup function performs the following:

• Calls XtCheckSubclass to ensure popup_shell's class is a subclass of shellWidgetClass.

• Raises the window and returns if the shell's popped_up field is already True.

• Calls the callback procedures on the shell's popup_callback list, specifying a pointer to the value of grab_kind as the call_data argument.

• Sets the shell popped_up field to True, the shell spring_loaded field to False, and the shell grab_kind field from grab_kind.

• If the shell's create_popup_child_proc field is non-NULL, XtPopup calls it with popup_shell as the parameter.

• If grab_kind is either XtGrabNonexclusive or XtGrabExclusive, it calls

  
  XtAddGrab(popup_shell, (grab_kind == XtGrabExclusive), False)
  

• Calls XtRealizeWidget with popup_shell specified.

• Calls XMapRaised with the window of popup_shell.

To map a spring-loaded pop-up from within an application, use XtPopupSpringLoaded.

void XtPopupSpringLoaded(Widget popup_shell);

void XtPopupSpringLoaded(Widget popup_shell);

popup_shell

Specifies the shell widget to be popped up.

The XtPopupSpringLoaded function performs exactly as XtPopup except that it sets the shell spring_loaded field to True and always calls XtAddGrab with exclusive True and spring-loaded True.

To map a pop-up from a given widget's callback list, you also can register one of the XtCallbackNone, XtCallbackNonexclusive, or XtCallbackExclusive convenience routines as callbacks, using the pop-up shell widget as the client data.

void XtCallbackNone(Widget w, XtPointer client_data, XtPointer call_data);

w	Specifies the widget.
client_data	Specifies the pop-up shell.
call_data	Specifies the callback data argument, which is not used by this procedure.

void XtCallbackNonexclusive(Widget w, XtPointer client_data, XtPointer call_data);

void XtCallbackNonexclusive(Widget w, XtPointer client_data, XtPointer call_data);

w	Specifies the widget.
client_data	Specifies the pop-up shell.
call_data	Specifies the callback data argument, which is not used by this procedure.

void XtCallbackExclusive(Widget w, XtPointer client_data, XtPointer call_data);

w	Specifies the widget.
client_data	Specifies the pop-up shell.
call_data	Specifies the callback data argument, which is not used by this procedure.

The XtCallbackNone, XtCallbackNonexclusive, and XtCallbackExclusive functions call XtPopup with the shell specified by the client_data argument and grab_kind set as the name specifies. XtCallbackNone, XtCallbackNonexclusive, and XtCallbackExclusive specify XtGrabNone, XtGrabNonexclusive, and XtGrabExclusive, respectively. Each function then sets the widget that executed the callback list to be insensitive by calling XtSetSensitive. Using these functions in callbacks is not required. In particular, an application must provide customized code for callbacks that create pop-up shells dynamically or that must do more than desensitizing the button.

Within a translation table, to pop up a menu when a key or pointer button is pressed or when the pointer is moved into a widget, use XtMenuPopup, or its synonym, MenuPopup. From a translation writer's point of view, the definition for this translation action is

void XtMenuPopup(String shell_name);

void XtMenuPopup(String shell_name);

shell_name

Specifies the name of the shell widget to pop up.

XtMenuPopup is known to the translation manager, which registers the corresponding built-in action procedure XtMenuPopupAction using XtRegisterGrabAction specifying owner_events True, event_mask ButtonPressMask | ButtonReleaseMask, and pointer_mode and keyboard_mode GrabModeAsync.

If XtMenuPopup is invoked on ButtonPress, it calls XtPopupSpringLoaded on the specified shell widget. If XtMenuPopup is invoked on KeyPress or EnterWindow, it calls XtPopup on the specified shell widget with grab_kind set to XtGrabNonexclusive. Otherwise, the translation manager generates a warning message and ignores the action.

XtMenuPopup tries to find the shell by searching the widget tree starting at the widget in which it is invoked. If it finds a shell with the specified name in the pop-up children of that widget, it pops up the shell with the appropriate parameters. Otherwise, it moves up the parent chain to find a pop-up child with the specified name. If XtMenuPopup gets to the application top-level shell widget and has not found a matching shell, it generates a warning and returns immediately.

Unmapping a Pop-Up Widget

Pop-ups can be popped down through several mechanisms:

• A call to XtPopdown

• The supplied callback procedure XtCallbackPopdown

• The standard translation action XtMenuPopdown

To unmap a pop-up from within an application, use XtPopdown.

void XtPopdown(Widget popup_shell);

popup_shell

Specifies the shell widget to pop down.

The XtPopdown function performs the following:

• Calls XtCheckSubclass to ensure popup_shell's class is a subclass of shellWidgetClass.

• Checks that the popped_up field of popup_shell is True; otherwise, it returns immediately.

• Unmaps popup_shell's window and, if override_redirect is False, sends a synthetic UnmapNotify event as specified by the Inter-Client Communication Conventions Manual.

• If popup_shell's grab_kind is either XtGrabNonexclusive or XtGrabExclusive, it calls XtRemoveGrab.

• Sets popup_shell's popped_up field to False.

• Calls the callback procedures on the shell's popdown_callback list, specifying a pointer to the value of the shell's grab_kind field as the call_data argument.

To pop down a pop-up from a callback list, you may use the callback XtCallbackPopdown.

void XtCallbackPopdown(Widget w, XtPointer client_data, XtPointer call_data);

void XtCallbackPopdown(Widget w, XtPointer client_data, XtPointer call_data);

w	Specifies the widget.
client_data	Specifies a pointer to the XtPopdownID structure.
call_data	Specifies the callback data argument, which is not used by this procedure.

The XtCallbackPopdown function casts the client_data parameter to a pointer of type XtPopdownID.

typedef struct {
Widget shell_widget;
Widget enable_widget;
} XtPopdownIDRec, *XtPopdownID;

The shell_widget is the pop-up shell to pop down, and the enable_widget is usually the widget that was used to pop it up in one of the pop-up callback convenience procedures.

XtCallbackPopdown calls XtPopdown with the specified shell_widget and then calls XtSetSensitive to resensitize enable_widget.

Within a translation table, to pop down a spring-loaded menu when a key or pointer button is released or when the pointer is moved into a widget, use XtMenuPopdown or its synonym, MenuPopdown. From a translation writer's point of view, the definition for this translation action is

void XtMenuPopdown(String shell_name);

shell_name

Specifies the name of the shell widget to pop down.

If a shell name is not given, XtMenuPopdown calls XtPopdown with the widget for which the translation is specified. If shell_name is specified in the translation table, XtMenuPopdown tries to find the shell by looking up the widget tree starting at the widget in which it is invoked. If it finds a shell with the specified name in the pop-up children of that widget, it pops down the shell; otherwise, it moves up the parent chain to find a pop-up child with the specified name. If XtMenuPopdown gets to the application top-level shell widget and cannot find a matching shell, it generates a warning and returns immediately.