


XtAddGrab(3Xt)						       XtAddGrab(3Xt)
X11R5									X11R5



NAME
  XtAddGrab, XtRemoveGrab - redirect user input	to a modal widget

SYNTAX
  void XtAddGrab(_w, _e_x_c_l_u_s_i_v_e, _s_p_r_i_n_g__l_o_a_d_e_d)
	Widget _w;
	Boolean	_e_x_c_l_u_s_i_v_e;
	Boolean	_s_p_r_i_n_g__l_o_a_d_e_d;

  void XtRemoveGrab(_w)
	Widget _w;

ARGUMENTS

  _e_x_c_l_u_s_i_v_e Specifies whether user events should be dispatched exclusively to
	    this widget	or also	to previous widgets in the cascade.

  _s_p_r_i_n_g__l_o_a_d_e_d
	    Specifies whether this widget was popped up	because	the user
	    pressed a pointer button.

  _w	    Specifies the widget to add	to or remove from the modal cascade.

DESCRIPTION
  The _X_t_A_d_d_G_r_a_b	function appends the widget (and associated parameters)	to
  the modal cascade and	checks that exclusive is _T_r_u_e if spring_loaded is
  _T_r_u_e.	 If these are not _T_r_u_e,	_X_t_A_d_d_G_r_a_b generates an error.

  The modal cascade is used by _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t when it tries to	dispatch a
  user event.  When at least one modal widget is in the	widget cascade,
  _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t first	determines if the event	should be delivered.  It
  starts at the	most recent cascade entry and follows the cascade up to	and
  including the	most recent cascade entry added	with the exclusive parameter
  _T_r_u_e.

  This subset of the modal cascade along with all descendants of these wid-
  gets comprise	the active subset.  User events	that occur outside the wid-
  gets in this subset are ignored or remapped.	Modal menus with submenus
  generally add	a submenu widget to the	cascade	with exclusive _F_a_l_s_e.  Modal
  dialog boxes that need to restrict user input	to the most deeply nested
  dialog box add a subdialog widget to the cascade with	exclusive _T_r_u_e.	 User
  events that occur within the active subset are delivered to the appropriate
  widget, which	is usually a child or further descendant of the	modal widget.

  Regardless of	where on the screen they occur,	remap events are always
  delivered to the most	recent widget in the active subset of the cascade
  that has spring_loaded _T_r_u_e, if any such widget exists.

  The _X_t_R_e_m_o_v_e_G_r_a_b function removes widgets from the modal cascade starting
  at the most recent widget up to and including	the specified widget.  It
  issues an error if the specified widget is not on the	modal cascade.

SEE ALSO
  _X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s - _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
  _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



