XtGrabKey() XtGrabKey()
Name
XtGrabKey - passively grab a single key of the keyboard.
Synopsis
void XtGrabKey(widget, keycode, modifiers, owner_events, pointer_mode,
keyboard_mode)
Widget widget;
KeyCode keycode;
Modifiers modifiers;
Boolean owner_events;
int pointer_mode, keyboard_mode;
Inputs
widget Specifies the widget in whose window the key is to be grabbed. Must be of class Core or any subclass thereof.
keycode Specifies the keycode to be grabbed. It may be a modifier key. Specifying AnyKey is equivalent to issuing the request for all
key codes.
modifiers Specifies a set of modifiers that must be down to trigger the grab.
owner_events
Specifies whether events generated during the grab are reported normally within the application (True) or only to the specified
widget (False).
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.
Description
XtGrabKey() calls XGrabKey() to establish a passive grab on the key specified by keycode. It specifies the widget's window as the
grab_window and passes its remaining arguments unmodified. If the widget is not realized, the call to XGrabKey() will be performed when
the widget is realized and its window becomes mapped. If the widget is unrealized and later realized again, the call to XGrabKey() will be
performed again.
The modifiers argument is a bitwise OR of one or more of the following symbols: ShiftMask, LockMask, Control Mask, Mod1Mask, Mod2Mask,
Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier. AnyModifier is equivalent to issuing the grab key request for all possible modifier combi-
nations (including no modifiers).
See XtGrabKeyboard() for a description of the owner_events, pointer_mode, and keyboard_mode arguments.
See the "Description" section below for details of event processing when an passive key grab is triggered.
Usage
When you passively grab a key/modifiers combination, all events that occur when that button and those modifiers are down will be delivered
to your widget's window or to your application, regardless of the location of the pointer. Key grabs can be used by applications like win-
dow managers that want to define keyboard "hot keys" that invoke a particular function regardless of which application is currently in use.
Most applications will never need to issue a grab. XtAddGrab() (called by XtPopup()) can be used to implement modal popups inside an
application, and XtSetKeyboardFocus() can be used to redirect keyboard focus within an application. Neither function actually issues a
grab, and so does not interrupt event processing by other clients.
To cancel a passive key grab, use XtUngrabKey().
Background
After this call, if XtDispatchEvent() is called with a KeyPress event matching the specified keycode and modifiers (which may be AnyKey or
AnyModifier, respectively) for the widget's window, the Intrinsics will undo the grab by calling XtUngrabKeyboard() with the timestamp from
the KeyPress event if either of the following conditions is true:
o There is a modal cascade and the widget is not in the active subset of the cascade and the keyboard was not previously grabbed, or
o XFilterEvent() returns True.
Otherwise, after this call, the keyboard will be actively grabbed (as for XGrabKeyboard()), the last-keyboard-grab time will be set to the
time at which the key was pressed (as transmitted in the KeyPress event), and the KeyPress event will be reported if all of the following
conditions are true:
o The keyboard is not grabbed and the specified key (which can itself be a modifier key) is logically pressed when the specified modifier
keys are logically down, and no other modifier keys are logically down.
o Either the grab_window is an ancestor of (or is) the focus window, or the grab_window is a descendant of the focus window and contains
the pointer.
o A passive grab on the same key combination does not exist on any ancestor of grab_window.
The active grab is terminated automatically when the logical state of the keyboard has the specified key released (independent of the logi-
cal state of the modifier keys).
Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen.
A modifiers argument of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination
of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A keycode argument of AnyKey is
equivalent to issuing the request for all possible KeyCodes. Otherwise, the specified keycode must be in the range specified by min_key-
code and max_keycode in the connection setup, or a BadValue error results.
If some other client has issued a XGrabKey() with the same key combination on the same window, a BadAccess error results. When using Any-
Modifier or AnyKey, the request fails completely, and a BadAccess error results (no grabs are established) if there is a conflicting grab
for any combination.
XGrabKey() can generate BadAccess, BadValue, and BadWindow errors.
See Also
XtAddGrab(1), XtGrabButton(1), XtGrabKeyboard(1), XtGrabPointer(1), XtRegisterGrabAction(1), XtSetKeyboardFocus(1), XtUngrabButton(1),
XtUngrabKey(1), XtUngrabKeyboard(1), XtUngrabPointer(1).
Xt - Keyboard Handling XtGrabKey()