XtAddGrab() XtAddGrab()
Name
XtAddGrab - constrain or redirect user input to a modal widget.
Synopsis
void XtAddGrab(w, exclusive, spring_loaded)
Widget w;
Boolean exclusive;
Boolean spring_loaded;
Inputs
w Specifies the widget that is to be made modal. Must be of class Core or any subclass thereof.
exclusive Specifies whether user events should be dispatched exclusively to this widget or also to modal parent widgets.
spring_loaded
Specifies whether this widget was popped up because the user pressed a pointer button.
Description
XtAddGrab() makes a widget modal. When a modal widget exists, XtDispatchEvent() will not deliver events that occur outside of the modal
widget (unless, perhaps, they occur in the modal widget's modal parent) or will redirect events that occur outside of the modal widget to
the modal widget.
A modal popup dialog box may itself have popup children, and a popup menu may have submenus that popup. A modal widget and all of its
descendants are referred to as the modal cascade. If the exclusive argument to XtAddGrab() is True, then events should be delivered only
to the specified widget, not to any previous widgets in the modal cascade. If it is False, then events will be delivered to the specified
widget and any ancestors in the modal cascade until one is found that has exclusive True.
Some popups (menus, for example) popup when the user presses a mouse button, and must pop down when the user releases that button, even if
it is released outside of the popup. This sort of popup should call XtAddGrab() with the spring_loaded argument set to True. XtDis-
patchEvent() will dispatch key and button events to a spring-loaded popup regardless of where those events occur in the application. Note
that if spring_loaded is True, then exclusive must also be True.
Usage
You do not often need to call XtAddGrab() explicitly. XtPopup() will pop up a dialog box and call XtAddGrab() appropriately, and the pre-
defined callback procedures XtCallbackExclusive(), XtCallbackNone(), and XtCallbackNonexclusive() will do the same and are suitable for
registering on widget callback lists. The predefined action named XtMenuPopup will pop up a spring-loaded widget and can be called
directly from a translation table.
If you call XtAddGrab() then you should call XtRemoveGrab() when you are done with your modal widget.
Note that XtAddGrab() does not issue an X button or key grab as XtGrabButton() and XtGrabKey() do (although there is a button grab implic-
itly made while any mouse button is held down over a popup menu, for example). Its name refers to the fact that it uses event remapping to
simulate the effect of a grab without locking out input to other applications running on the same display.
Background
Modal widgets are widgets that, except for the input directed to them, lock out user input to the application.
When a modal menu or modal dialog box is popped up using XtPopup(), user events (keyboard and pointer events) that occur outside the modal
widget should be delivered to the modal widget or ignored. In no case will user events be delivered to a widget outside the modal widget.
Menus can pop up submenus, and dialog boxes can pop up further dialog boxes, to create a popup cascade. In this case, user events may be
delivered to one of several modal widgets in the cascade.
Display-related events should be delivered outside the modal cascade so that exposure events and the like keep the application's display
up-to-date. Any event that occurs within the cascade is delivered as usual. The user events delivered to the most recent spring-loaded
shell in the cascade when they occur outside the cascade are called remap events and are KeyPress, KeyRelease, ButtonPress, and ButtonRe-
lease. The user events ignored when they occur outside the cascade are MotionNotify and EnterNotify. All other events are delivered nor-
mally. In particular, note that this is one way in which widgets can receive LeaveNotify events without first receiving EnterNotify
events; they should be prepared to deal with this, typically by ignoring any unmatched LeaveNotify events.
XtAddGrab() appends the widget to the modal cascade and checks that exclusive is True if spring_loaded is True. If this condition is not
met, XtAddGrab() generates a warning message.
The modal cascade is used by XtDispatchEvent() when it tries to dispatch a user event. When at least one modal widget is in the widget
cascade, XtDispatchEvent() first determines if the event should be delivered. It starts at the most recent cascade entry and follows the
cascade up to and including the most recent cascade entry added with the exclusive parameter True.
This subset of the modal cascade along with all descendants of these widgets comprise the active subset. User events that occur outside
the widgets in this subset are ignored or remapped. Modal menus with submenus generally add a submenu widget to the cascade with exclusive
False. Modal dialog boxes that need to restrict user input to the most deeply nested dialog box add a subdialog widget to the cascade with
exclusive True. User events that occur within the active subset are delivered to the appropriate widget, which is usually a child or fur-
ther descendant of the modal widget.
Regardless of where in the application they occur, remap events are always delivered to the most recent widget in the active subset of the
cascade registered with spring_loaded True, if any such widget exists. If the event occurred in the active subset of the cascade but out-
side the spring-loaded widget, it is delivered normally before being delivered also to the spring-loaded widget. Regardless of where it is
dispatched, the Intrinsics do not modify the contents of the event.
See Also
XtCallbackExclusive(1), XtCallbackNone(1), XtCallbackNonexclusive(1), XtCallbackPopdown(1), XtCreatePopupShell(1), XtDispatchEvent(1),
XtMenuPopup(1), XtPopdown(1), XtPopup(1), XtRemoveGrab(1).
Xt - Pop Ups XtAddGrab()