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()