Name

XtAddGrab — redirect user input to a modal widget. 

Synopsis

void XtAddGrab(w, exclusive, spring_loaded)

    Widget w;
    Boolean exclusive;
    Boolean spring_loaded;

Arguments

wSpecifies the widget to add to the modal cascade. 

exclusiveSpecifies whether user events should be dispatched exclusively to this widget or also to previous widgets in the cascade. 

spring_loaded
Specifies whether this widget was popped up because the user pressed a pointer button.

Description

XtAddGrab appends a widget to a modal cascade.  Modal widgets are widgets that, except for the input directly to them, lock out user input to the application.  XtAddGrab affects only Xt’s event dispatching--it does not request a key or button grab on the server. 

When a modal menu or modal dialog box is popped up, user events (keyboard and pointer events) that occur outside the modal widget should either be delivered to the modal widget or be ignored.  In no case should 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 pop-up 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 Expose 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 that are delivered to the most recent spring-loaded shell in the cascade when they occur outside the cascade are called remap events.  These events are KeyPress, KeyRelease, ButtonPress, and ButtonRelease.  The user events that are 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 prepared to deal with this, typically by ignoring the unmatched LeaveNotify events. 

XtPopup uses the XtAddGrab and XtRemoveGrab functions to constrain user events to a modal cascade and subsequently to remove a grab when the modal widget goes away.  Usually you should have no need to call them explicitly.  XtAddGrab is called implicitly by XtCallbackExclusive and other calls. 

The XtAddGrab function appends the widget (and associated parameters) to the modal cascade and checks that exclusive is True if spring_loaded is True.  If these are not both True, XtAddGrab generates a warning message and asserts an exclusive grab anyway. 

When the modal cascade holds at least one widget, XtDispatchEvent determines if the event should be delivered or held.  It starts with the last cascade entry and follows the cascade till it finds the youngest cascade entry added with exclusive True.  If it finds a widget in the cascade interested in the event, it delivers the event to it. 

This modal cascade, along with all descendants of the widgets it contains, comprise the active subset.  User events that occur outside the widgets in this subset are ignored or remapped.  Modal menus generally add pop-up submenus to the cascade with exclusive set to False, so that the submenu can receive input event after it pops up.  Modal dialog boxes that restrict user input to the most deeply nested dialog box add a subdialog widget to the cascade with exclusive set to True.  User events that occur within the active subset are delivered to the appropriate widget, which is usually a 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, the event is delivered normally before being delivered also to the spring-loaded widget. 

See Also

XtCallbackExclusive(1), XtCreatePopupShell(1), XtDispatchEvent(1), XtPopup(1), XtRemoveGrab(1).