


XGrabKey(3X11)						       XGrabKey(3X11)
X11R5									X11R5



NAME
  XGrabKey, XUngrabKey - grab keyboard keys

SYNTAX
  XGrabKey(_d_i_s_p_l_a_y, _k_e_y_c_o_d_e, _m_o_d_i_f_i_e_r_s,	_g_r_a_b__w_i_n_d_o_w, _o_w_n_e_r__e_v_e_n_t_s,
  _p_o_i_n_t_e_r__m_o_d_e,
	       _k_e_y_b_o_a_r_d__m_o_d_e)
	Display	*_d_i_s_p_l_a_y;
	int _k_e_y_c_o_d_e;
	unsigned int _m_o_d_i_f_i_e_r_s;
	Window _g_r_a_b__w_i_n_d_o_w;
	Bool _o_w_n_e_r__e_v_e_n_t_s;
	int _p_o_i_n_t_e_r__m_o_d_e, _k_e_y_b_o_a_r_d__m_o_d_e;

  XUngrabKey(_d_i_s_p_l_a_y, _k_e_y_c_o_d_e, _m_o_d_i_f_i_e_r_s, _g_r_a_b__w_i_n_d_o_w)
	Display	*_d_i_s_p_l_a_y;
	int _k_e_y_c_o_d_e;
	unsigned int _m_o_d_i_f_i_e_r_s;
	Window _g_r_a_b__w_i_n_d_o_w;

ARGUMENTS

  _d_i_s_p_l_a_y   Specifies the connection to	the X server.

  _g_r_a_b__w_i_n_d_o_w
	    Specifies the grab window.

  _k_e_y_b_o_a_r_d__m_o_d_e
	    Specifies further processing of keyboard events.  You can pass
	    _G_r_a_b_M_o_d_e_S_y_n_c or _G_r_a_b_M_o_d_e_A_s_y_n_c.

  _k_e_y_c_o_d_e   Specifies the KeyCode or _A_n_y_K_e_y.

  _m_o_d_i_f_i_e_r_s Specifies the set of keymasks or _A_n_y_M_o_d_i_f_i_e_r.  The mask is the
	    bitwise inclusive OR of the	valid keymask bits.

  _o_w_n_e_r__e_v_e_n_t_s
	    Specifies a	Boolean	value that indicates whether the keyboard
	    events are to be reported as usual.

  _p_o_i_n_t_e_r__m_o_d_e
	    Specifies further processing of pointer events.  You can pass
	    _G_r_a_b_M_o_d_e_S_y_n_c or _G_r_a_b_M_o_d_e_A_s_y_n_c.

DESCRIPTION
  The _X_G_r_a_b_K_e_y function	establishes a passive grab on the keyboard.  In	the
  future, the keyboard is actively grabbed (as for _X_G_r_a_b_K_e_y_b_o_a_r_d), the last-
  keyboard-grab	time is	set to the time	at which the key was pressed (as
  transmitted in the _K_e_y_P_r_e_s_s event), and the _K_e_y_P_r_e_s_s event is	reported if
  all of the following conditions are true:

  o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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o++    A passive grab on the same key combination does not exist on any
       ancestor	of grab_window.

  The interpretation of	the remaining arguments	is as for _X_G_r_a_b_K_e_y_b_o_a_r_d.  The
  active grab is terminated automatically when the logical state of the	key-
  board	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 _A_n_y_M_o_d_i_f_i_e_r 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 _A_n_y_K_e_y 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 con-
  nection setup, or a _B_a_d_V_a_l_u_e error results.

  If some other	client has issued a _X_G_r_a_b_K_e_y with the same key combination on
  the same window, a _B_a_d_A_c_c_e_s_s error results.  When using _A_n_y_M_o_d_i_f_i_e_r or _A_n_y_-
  _K_e_y, the request fails completely, and a _B_a_d_A_c_c_e_s_s error results (no grabs
  are established) if there is a conflicting grab for any combination.

  _X_G_r_a_b_K_e_y can generate	_B_a_d_A_c_c_e_s_s, _B_a_d_V_a_l_u_e, and _B_a_d_W_i_n_d_o_w errors.

  The _X_U_n_g_r_a_b_K_e_y function releases the key combination on the specified	win-
  dow if it was	grabbed	by this	client.	 It has	no effect on an	active grab.
  A modifiers of _A_n_y_M_o_d_i_f_i_e_r is	equivalent to issuing the request for all
  possible modifier combinations (including the	combination of no modifiers).
  A keycode argument of	_A_n_y_K_e_y is equivalent to	issuing	the request for	all
  possible key codes.

  _X_U_n_g_r_a_b_K_e_y can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w error.

DIAGNOSTICS

  _B_a_d_A_c_c_e_s_s A client attempted to grab a key/button combination	already
	    grabbed by another client.

  _B_a_d_V_a_l_u_e  Some numeric value falls outside the range of values accepted by
	    the	request.  Unless a specific range is specified for an argu-
	    ment, the full range defined by the	argument's type	is accepted.
	    Any	argument defined as a set of alternatives can generate this
	    error.

  _B_a_d_W_i_n_d_o_w A value for	a Window argument does not name	a defined Window.

SEE ALSO
  XAllowEvents(3X11), XGrabButton(3X11), XGrabKeyboard(3X11),
  XGrabPointer(3X11)
  _X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e













