XtGrabKey(3x) — HPUX 9.05

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

widgetSpecifies the widget in whose window the key is to be grabbed. Must be of class Core or any subclass thereof.

keycodeSpecifies the keycode to be grabbed. It may be a modifier key. Specifying AnyKey is equivalent to issuing the request for all key codes.

modifiersSpecifies 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 combinations (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 window 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:

•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 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_keycode 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 AnyModifier 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.

Museum