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