Name
XtRegisterGrabAction — register button and key grabs for a widget’s window according to the event bindings in the widget’s translation table.
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;
Arguments
action_proc
Specifies the action procedure to search for in the translation table(s).
owner_events
Specifies a Boolean value of either True or False. See Description below.
event_mask
Specifies the event mask to take effect during the grab. This mask is the bitwise OR of one or more of the event masks listed on the reference page for XSelectInput.
pointer_mode
Controls processing of pointer events during the grab. Pass one of these constants: GrabModeSync or GrabModeAsync.
keyboard_mode
Controls processing of keyboard events during the grab. Pass one of these constants: GrabModeSync or GrabModeAsync.
Description
To register button and key grabs for a widget’s window according to the event bindings in the widget’s translation table, use XtRegisterGrabAction.
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.
•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.
•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 modifiers 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.
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).