XtAddGrab()XtAddGrab()NameXtAddGrab - 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 exclu‐
sively 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.
DescriptionXtAddGrab() makes a widget modal. When a modal widget exists, XtDis‐
patchEvent() 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 cas‐
cade. 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 prede‐
fined callback procedures XtCallbackExclusive(), XtCallbackNone(), and
XtCallbackNonexclusive() will do the same and are suitable for regis‐
tering 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 XtGrab‐
Button() and XtGrabKey() do (although there is a button grab implicitly
made while any mouse button is held down over a popup menu, for exam‐
ple). Its name refers to the fact that it uses event remapping to sim‐
ulate the effect of a grab without locking out input to other applica‐
tions 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 ButtonRelease. The user
events ignored when they occur outside the cascade are MotionNotify and
EnterNotify. All other events are delivered normally. In particular,
note that this is one way in which widgets can receive LeaveNotify
events without first receiving EnterNotify events; they should be pre‐
pared to deal with this, typically by ignoring any unmatched LeaveNo‐
tify 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 dis‐
patch 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 sub‐
menus 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 outside
the spring-loaded widget, it is delivered normally before being deliv‐
ered also to the spring-loaded widget. Regardless of where it is dis‐
patched, the Intrinsics do not modify the contents of the event.
See AlsoXtCallbackExclusive(1), XtCallbackNone(1), XtCallbackNonexclusive(1),
XtCallbackPopdown(1), XtCreatePopupShell(1), XtDispatchEvent(1),
XtMenuPopup(1), XtPopdown(1), XtPopup(1), XtRemoveGrab(1).
Xt - Pop Ups XtAddGrab()
