XtGrabKey()XtGrabKey()NameXtGrabKey - 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.
DescriptionXtGrabKey() 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 wid‐
get 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 equiva‐
lent to issuing the grab key request for all possible modifier combina‐
tions (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 loca‐
tion of the pointer. Key grabs can be used by applications like window
managers that want to define keyboard "hot keys" that invoke a particu‐
lar 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 applica‐
tion, 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:
· 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
· 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:
· 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.
· 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.
· 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 logical
state of the modifier keys).
Note that the logical state of a device (as seen by client applica‐
tions) 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 combina‐
tion 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. Other‐
wise, 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 combina‐
tion on the same window, a BadAccess error results. When using AnyMod‐
ifier 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 AlsoXtAddGrab(1), XtGrabButton(1), XtGrabKeyboard(1), XtGrabPointer(1),
XtRegisterGrabAction(1), XtSetKeyboardFocus(1), XtUngrabButton(1),
XtUngrabKey(1), XtUngrabKeyboard(1), XtUngrabPointer(1).
Xt - Keyboard Handling XtGrabKey()
