


XGrabButton(3X11)					    XGrabButton(3X11)
X11R5									X11R5



NAME
  XGrabButton, XUngrabButton - grab pointer buttons

SYNTAX
  XGrabButton(_d_i_s_p_l_a_y, _b_u_t_t_o_n, _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,
  _e_v_e_n_t__m_a_s_k,
		  _p_o_i_n_t_e_r__m_o_d_e,	_k_e_y_b_o_a_r_d__m_o_d_e, _c_o_n_f_i_n_e__t_o, _c_u_r_s_o_r)
	Display	*_d_i_s_p_l_a_y;
	unsigned int _b_u_t_t_o_n;
	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;
	unsigned int _e_v_e_n_t__m_a_s_k;
	int _p_o_i_n_t_e_r__m_o_d_e, _k_e_y_b_o_a_r_d__m_o_d_e;
	Window _c_o_n_f_i_n_e__t_o;
	Cursor _c_u_r_s_o_r;

  XUngrabButton(_d_i_s_p_l_a_y, _b_u_t_t_o_n, _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;
	unsigned int _b_u_t_t_o_n;
	unsigned int _m_o_d_i_f_i_e_r_s;
	Window _g_r_a_b__w_i_n_d_o_w;

ARGUMENTS

  _b_u_t_t_o_n    Specifies the pointer button that is to be grabbed or released or
	    _A_n_y_B_u_t_t_o_n.

  _c_o_n_f_i_n_e__t_o
	    Specifies the window to confine the	pointer	in or _N_o_n_e.

  _c_u_r_s_o_r    Specifies the cursor that is to be displayed or _N_o_n_e.

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

  _e_v_e_n_t__m_a_s_k
	    Specifies which pointer events are reported	to the client.	The
	    mask is the	bitwise	inclusive OR of	the valid pointer event	mask
	    bits.

  _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.

  _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 pointer
	    events are to be reported as usual or reported with	respect	to
	    the	grab window if selected	by the event mask.

  _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_B_u_t_t_o_n function establishes a passive grab.	In the future, the
  pointer is actively grabbed (as for _X_G_r_a_b_P_o_i_n_t_e_r), the last-pointer-grab
  time is set to the time at which the button was pressed (as transmitted in
  the _B_u_t_t_o_n_P_r_e_s_s event), and the _B_u_t_t_o_n_P_r_e_s_s event is reported	if all of the
  following conditions are true:

  oo++    The pointer is not grabbed, and the specified button is logically
       pressed when the	specified modifier keys	are logically down, and	no
       other buttons or	modifier keys are logically down.

  oo++    The grab_window contains	the pointer.

  oo++    The confine_to window (if any) is viewable.

  oo++    A passive grab on the same button/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_P_o_i_n_t_e_r.	 The
  active grab is terminated automatically when the logical state of the
  pointer has all buttons released (independent	of the state of	the logical
  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.

  This request overrides all previous grabs by the same	client on the same
  button/key combinations on the same window.  A modifiers of _A_n_y_M_o_d_i_f_i_e_r is
  equivalent to	issuing	the grab request for all possible modifier combina-
  tions	(including the combination of no modifiers). It	is not required	that
  all modifiers	specified have currently assigned KeyCodes.  A button of
  _A_n_y_B_u_t_t_o_n is equivalent to issuing the request for all possible buttons.
  Otherwise, it	is not required	that the specified button currently be
  assigned to a	physical button.

  If some other	client has already issued a _X_G_r_a_b_B_u_t_t_o_n	with the same
  button/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_B_u_t_t_o_n, 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_B_u_t_t_o_n has no	effect on an active grab.

  _X_G_r_a_b_B_u_t_t_o_n can generate _B_a_d_C_u_r_s_o_r, _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_B_u_t_t_o_n function releases the passive button/key combination on
  the specified	window if it was grabbed by this client.  A modifiers of
  _A_n_y_M_o_d_i_f_i_e_r is equivalent to issuing the ungrab request for all possible
  modifier combinations, including the combination of no modifiers.  A button
  of _A_n_y_B_u_t_t_o_n is equivalent to	issuing	the request for	all possible buttons.
  _X_U_n_g_r_a_b_B_u_t_t_o_n	has no effect on an active grab.

  _X_U_n_g_r_a_b_B_u_t_t_o_n	can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w errors.

DIAGNOSTICS

  _B_a_d_C_u_r_s_o_r A value for	a Cursor argument does not name	a defined Cursor.

  _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), XGrabPointer(3X11), XGrabKey(3X11),
  XGrabKeyboard(3X11),
  _X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e	delim off






























































