


XtAppNextEvent(3Xt)					  XtAppNextEvent(3Xt)
X11R5									X11R5



NAME
  XtAppNextEvent, XtAppPending,	XtAppPeekEvent,	XtAppProcessEvent,
  XtDispatchEvent, XtAppMainLoop - query and process events and	input

SYNTAX
  void XtAppNextEvent(_a_p_p__c_o_n_t_e_x_t, _e_v_e_n_t__r_e_t_u_r_n)
	XtAppContext _a_p_p__c_o_n_t_e_x_t;
	XEvent *_e_v_e_n_t__r_e_t_u_r_n;

  Boolean XtAppPeekEvent(_a_p_p__c_o_n_t_e_x_t, _e_v_e_n_t__r_e_t_u_r_n)
	XtAppContext _a_p_p__c_o_n_t_e_x_t;
	XEvent *_e_v_e_n_t__r_e_t_u_r_n;

  XtInputMask XtAppPending(_a_p_p__c_o_n_t_e_x_t)
	XtAppContext _a_p_p__c_o_n_t_e_x_t;

  void XtAppProcessEvent(_a_p_p__c_o_n_t_e_x_t, _m_a_s_k)
	XtAppContext _a_p_p__c_o_n_t_e_x_t;
	XtInputMask _m_a_s_k;

  Boolean XtDispatchEvent(_e_v_e_n_t)
	XEvent *_e_v_e_n_t;

  void XtAppMainLoop(_a_p_p__c_o_n_t_e_x_t)
	XtAppContext _a_p_p__c_o_n_t_e_x_t;

ARGUMENTS

  _a_p_p__c_o_n_t_e_x_t
	    Specifies the application context that identifies the application
	    .

  _e_v_e_n_t	    Specifies a	pointer	to the event structure that is to be
	    dispatched to the appropriate event	handler.

  _e_v_e_n_t__r_e_t_u_r_n
	    Returns the	event information to the specified event structure.

  _m_a_s_k	    Specifies what types of events to process.	The mask is the	bit-
	    wise inclusive OR of any combination of _X_t_I_M_X_E_v_e_n_t,	_X_t_I_M_T_i_m_e_r,
	    and	_X_t_I_M_A_l_t_e_r_n_a_t_e_I_n_p_u_t.  The X Toolkit defines the symbolic	name
	    _X_t_I_M_A_l_l to be the bitwise inclusive	OR of all event	types.

DESCRIPTION
  If no	input is on the	X input	queue, _X_t_A_p_p_N_e_x_t_E_v_e_n_t flushes the X output
  buffer and waits for an event	while looking at the other input sources and
  timeout values and calling any callback procedures triggered by them.	 This
  wait time can	be used	for background processing (see Section 7.8).

  If there is an event in the queue, _X_t_A_p_p_P_e_e_k_E_v_e_n_t fills in the event and
  returns a nonzero value.  If no X input is on	the queue, _X_t_A_p_p_P_e_e_k_E_v_e_n_t
  flushes the output buffer and	blocks until input is available	(possibly
  calling some timeout callbacks in the	process).  If the input	is an event,
  _X_t_A_p_p_P_e_e_k_E_v_e_n_t fills in the event and	returns	a nonzero value.  Otherwise,
  the input is for an alternate	input source, and _X_t_A_p_p_P_e_e_k_E_v_e_n_t returns
  zero.


  The _X_t_A_p_p_P_e_n_d_i_n_g function returns a nonzero value if there are events	pend-
  ing from the X server, timer pending,	or other input sources pending.	The
  value	returned is a bit mask that is the OR of _X_t_I_M_X_E_v_e_n_t, _X_t_I_M_T_i_m_e_r,	and
  _X_t_I_M_A_l_t_e_r_n_a_t_e_I_n_p_u_t (see _X_t_A_p_p_P_r_o_c_e_s_s_E_v_e_n_t).  If there	are no events pend-
  ing, _X_t_A_p_p_P_e_n_d_i_n_g flushes the	output buffer and returns zero.

  The _X_t_A_p_p_P_r_o_c_e_s_s_E_v_e_n_t	function processes one timer, alternate	input, or X
  event.  If there is nothing of the appropriate type to process, _X_t_A_p_p_P_r_o_-
  _c_e_s_s_E_v_e_n_t blocks until there is.  If there is	more than one type of thing
  available to process,	it is undefined	which will get processed.  Usually,
  this procedure is not	called by client applications (see _X_t_A_p_p_M_a_i_n_L_o_o_p).
  _X_t_A_p_p_P_r_o_c_e_s_s_E_v_e_n_t processes timer events by calling any appropriate timer
  callbacks, alternate input by	calling	any appropriate	alternate input	call-
  backs, and X events by calling _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t.

  When an X event is received, it is passed to _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t,	which calls
  the appropriate event	handlers and passes them the widget, the event,	and
  client-specific data registered with each procedure.	If there are no
  handlers for that event registered, the event	is ignored and the dispatcher
  simply returns.  The order in	which the handlers are called is undefined.

  The _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t function sends those events to the event handler func-
  tions	that have been previously registered with the dispatch routine.
  _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t returns _T_r_u_e if it dispatched	the event to some handler and
  _F_a_l_s_e	if it found no handler to dispatch the event to.  The most common use
  of _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t is	to dispatch events acquired with the _X_t_A_p_p_N_e_x_t_E_v_e_n_t
  procedure.  However, it also can be used to dispatch user-constructed
  events.  _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t also	is responsible for implementing	the grab
  semantics for	_X_t_A_d_d_G_r_a_b.

  The _X_t_A_p_p_M_a_i_n_L_o_o_p function first reads the next incoming X event by calling
  _X_t_A_p_p_N_e_x_t_E_v_e_n_t and then it dispatches	the event to the appropriate
  registered procedure by calling _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t.  This constitutes the main
  loop of X Toolkit applications, and, as such,	it does	not return.  Applica-
  tions	are expected to	exit in	response to some user action.  There is	noth-
  ing special about _X_t_A_p_p_M_a_i_n_L_o_o_p; it is simply	an infinite loop that calls
  _X_t_A_p_p_N_e_x_t_E_v_e_n_t and then _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t.

  Applications can provide their own version of	this loop, which tests some
  global termination flag or tests that	the number of top-level	widgets	is
  larger than zero before circling back	to the call to _X_t_A_p_p_N_e_x_t_E_v_e_n_t.

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





















