XtGrabKeyboard()														  XtGrabKeyboard()

Name
  XtGrabKeyboard - actively grab the keyboard.

Synopsis
  int XtGrabKeyboard(widget, owner_events, pointer_mode, keyboard_mode, time)
	   Widget widget;
	   Boolean owner_events;
	   int pointer_mode, keyboard_mode;
	   Time time;

Inputs
  widget    Specifies the widget for whose window the keyboard is to be grabbed.  Must be of class Core or any subclass thereof.

  owner_events
	    Specifies  whether	the pointer events are to be reported normally within this application (pass True) or only to the grab window
	    (pass 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.

  time	    Specifies the time when the grab should take place.  Pass either a timestamp (from an event) or the constant CurrentTime.

Description
  If the specified widget is realized XtGrabKeyboard() calls XGrabKeyboard() specifying the widget's window as the grab_window,  passing  its
  remaining  argument unmodified, and returning whatever XGrabKeyboard() returns.  If the widget is not realized, XGrabKeyboard() immediately
  returns GrabNotViewable.  No future automatic ungrab is implied by XtGrabKeyboard().

  See the "Background" section below for a description of the arguments and an explanation of event  processing  during  an  active  keyboard
  grab.

Usage
  When	the keyboard is grabbed, all key events are delivered to the widget you specify or to your application, regardless of the location of
  the pointer.	There are not many occasions when this is a reasonable thing to do, because it locks out input to other applications.	xterm
  grabs the keyboard to implement secure mode.

  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 an active keyboard grab, use XtUngrabKeyboard().

Background
  The  XGrabKeyboard()	function  actively  grabs  control of the keyboard and generates FocusIn and FocusOut events.  Further key events are
  reported only to the grabbing client.  XGrabKeyboard() overrides any active keyboard grab by this client.  If owner_events  is  False,  all
  generated  key  events  are  reported  with  respect to grab_window. If owner_events is True and if a generated key event would normally be
  reported to this client, it is reported normally; otherwise, the event is reported with respect  to  the  grab_window.  Both	KeyPress  and
  KeyRelease events are always reported, independent of any event selection made by the client.

  If  the keyboard_mode argument is GrabModeAsync, keyboard event processing continues as usual.  If the keyboard is currently frozen by this
  client, then processing of keyboard events is resumed.  If the keyboard_mode argument is GrabModeSync, the state of the keyboard  (as  seen
  by client applications) appears to freeze, and the X server generates no further keyboard events until the grabbing client issues a releas-
  ing XAllowEvents() call or until the keyboard grab is released.  Actual keyboard changes are not lost while the keyboard  is	frozen;  they
  are simply queued in the server for later processing.

  If  pointer_mode  is GrabModeAsync, pointer event processing is unaffected by activation of the grab.  If pointer_mode is GrabModeSync, the
  state of the pointer (as seen by client applications) appears to freeze, and the X server generates no further  pointer  events  until  the
  grabbing  client  issues a releasing XAllowEvents() call or until the keyboard grab is released.  Actual pointer changes are not lost while
  the pointer is frozen; they are simply queued in the server for later processing.

  If the keyboard is actively grabbed by some other client, XGrabKeyboard() fails and returns AlreadyGrabbed.  If grab_window  is  not	view-
  able,  it  fails  and  returns  GrabNotViewable.   If  the  keyboard	is  frozen  by an active grab of another client, it fails and returns
  GrabFrozen.  If the specified time is earlier than the last-keyboard-grab time or later than the  current  X	server	time,  it  fails  and
  returns  GrabInvalidTime.   Otherwise,  the  last-keyboard-grab time is set to the specified time (CurrentTime is replaced by the current X
  server time).

  XGrabKeyboard() can generate BadValue and BadWindow errors.

See Also
  XtAddGrab(1), XtGrabButton(1), XtGrabKey(1), XtGrabPointer(1), XtRegisterGrabAction(1), XtUngrabButton(1), XtUngrabKey(1), XtUngrabKey-
  board(1), XtUngrabPointer(1).

Xt - Keyboard Handling														  XtGrabKeyboard()