XtRegisterGrabAction()													    XtRegisterGrabAction()

Name
  XtRegisterGrabAction - register an action procedure as one that needs a passive grab to function properly.

Synopsis
  void XtRegisterGrabAction(action_proc, owner_events, event_mask, pointer_mode, keyboard_mode)
	 XtActionProc action_proc;
	 Boolean owner_events;
	 unsigned int event_mask;
	 int pointer_mode, keyboard_mode;

Inputs
  action_proc
	    Specifies the action procedure that requires a passive grab.

  owner_events
	    Specifies  whether	pointer  events  generated during the grab are reported normally within the application (True) or only to the
	    widget that invokes the action (False).

  event_mask
	    Specifies the event mask to take effect during the grab.

  pointer_mode
	    Controls processing of pointer events during the grab.  Either GrabModeSync or GrabModeAsync.

  keyboard_mode
	    Controls processing of keyboard events during the grab.  Either GrabModeSync or GrabModeAsync.

Availability
  Release 4 and later.

Description
  XtRegisterGrabAction() registers action_proc as an action procedure that needs to have a passive grab in order for  it  to  work  properly.
  When	this  action  appears  in  a translation table, the Intrinsics will automatically perform the appropriate passive key or button grab,
  depending on the event sequence that invokes the action.  The owner_events,  event_mask,  pointer_mode,  and	keyboard_mode  arguments  are
  passed to XtGrabKey() or XtGrabButton() when the passive grab is made.

  See the "Background" section below for full details.	See XtGrabKey() and XtGrabButton() for more information about passive grabs.

Usage
  When	you passively grab a button/modifiers or key/modifiers combination, all events that occur when that button or key and those modifiers
  are down will be delivered to the widget you specify or to your application, regardless of the location of the pointer.

  Very few action procedures need a grab to function properly.	Note that a button grab is always automatically invoked between a button down
  and  the  corresponding button up event, so that a text widget, for example, that wanted to scroll its text when the user dragged the mouse
  out of the window could do so without registering the action procedure with this function.

  Grabs are required by some kinds of popup menus, and XtRegisterGrabAction() is used by the predefined action XtMenuPopup.

Background
  XtRegisterGrabAction() adds the specified action_proc to a list known to the translation manager.  When a widget is realized, or  when  the
  translations	of a realized widget or the accelerators installed on a realized widget are modified, its translation table and any installed
  accelerators are scanned for action procs on this list.

  If any are invoked on ButtonPress or KeyPress events as the only or final event in a sequence, the Intrinsics will call  XtGrabButton()  or
  XtGrabKey()  for  the  widget  with  every  button  or  keycode  that  maps  to the event detail field, passing the specified owner_events,
  event_mask, pointer_mode, and keyboard_mode.

  o  For ButtonPress events, the modifiers specified in the grab are determined directly from the translation specification,  and  confine_to
     and cursor are specified as None.

  o  For KeyPress events:

     +	    If the translation table entry specifies colon (:) in the modifier list, the modifiers are determined by calling the key transla-
	    tor procedure registered for the display and by calling XtGrabKey() for every combination of standard modifiers that map the key-
	    code  to  the  specified event detail keysym, and ORing any modifiers specified in the translation table entry, and event_mask is
	    ignored.

     +	    If the translation table entry does not specify colon in the modifier list, the modifiers specified in the grab are those  speci-
	    fied in the translation table entry only.

  For both ButtonPress and KeyPress events, "don't care modifiers" are ignored unless the translation entry explicitly specifies "Any" in the
  modifiers field.

  If the specified action_proc is already registered for the calling process, the new values replace the previously specified values for  any
  widgets that are realized following the call, but existing grabs are not altered on currently-realized widgets.

  When	translations or installed accelerators are modified for a realized widget, any previous key or button grabs that were registered as a
  result of the old bindings are released, provided that the old bindings do not appear in the new bindings and are not explicitly grabbed by
  the client with XtGrabKey() or XtGrabButton().

See Also
  XtAddActions(1), XtAppAddActionHook(1), XtAppAddActions(1), XtCallActionProc(1), XtGetActionKeysym(1), XtRemoveActionHook(1).

Xt - Translations and Actions												    XtRegisterGrabAction()