When the predicate procedure finds a match, _X_C_h_e_c_k_I_f_E_v_e_n_t copies the matched event into the client-supplied _X_E_v_e_n_t structure and returns _T_r_u_e. (This event is removed from the queue.) If the predicate procedure finds no match, _X_C_h_e_c_k_I_f_E_v_e_n_t returns _F_a_l_s_e, and the output buffer will have been flushed. All earlier events stored in the queue are not discarded.
The _X_P_e_e_k_I_f_E_v_e_n_t function returns only when the specified predicate procedure returns _T_r_u_e for an event. After the predicate procedure finds a match, _X_P_e_e_k_I_f_E_v_e_n_t copies the matched event into the client-supplied _X_E_v_e_n_t structure without removing the event from the queue. _X_P_e_e_k_I_f_E_v_e_n_t flushes the output buffer if it blocks waiting for additional events.
Each of these functions requires you to pass a predicate procedure that determines if an event matches what you want. Your predicate procedure must decide if the event is useful without calling any Xlib functions. If the predicate directly or indirectly causes the state of the event queue to change, the result is not defined. If Xlib has been initialized for threads, the predicate is called with the display locked and the result of a call by the predicate to any Xlib function that locks the display is not defined unless the caller has first called _X_L_o_c_k_D_i_s_p_l_a_y.
The predicate procedure and its associated arguments are: Bool (*_p_r_e_d_i_c_a_t_e)(Display *_d_i_s_p_l_a_y, XEvent *_e_v_e_n_t, XPointer _a_r_g)
The predicate procedure is called once for each event in the queue until it finds a match. After finding a match, the predicate procedure must return _T_r_u_e. If it did not find a match, it must return _F_a_l_s_e.