XtRegisterGrabAction()XtRegisterGrabAction()NameXtRegisterGrabAction - 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.
DescriptionXtRegisterGrabAction() 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 combina‐
tion, 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 appli‐
cation, 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 XtRegisterGrabAc‐
tion() is used by the predefined action XtMenuPopup.
BackgroundXtRegisterGrabAction() 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.
· For ButtonPress events, the modifiers specified in the grab are
determined directly from the translation specification, and con‐
fine_to and cursor are specified as None.
· For KeyPress events:
+ If the translation table entry specifies colon (:) in the
modifier list, the modifiers are determined by calling the
key translator procedure registered for the display and by
calling XtGrabKey() for every combination of standard modi‐
fiers that map the keycode 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
specified 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 AlsoXtAddActions(1), XtAppAddActionHook(1), XtAppAddActions(1), XtCallAc‐
tionProc(1), XtGetActionKeysym(1), XtRemoveActionHook(1).
Xt - Translations and Actions XtRegisterGrabAction()
