NAME

XGrabKeyboard, XUngrabKeyboard - grab the keyboard

SYNTAX

int XGrabKeyboard(Display *_d_i_s_p_l_a_y, 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, int _k_e_y_b_o_a_r_d___m_o_d_e, Time _t_i_m_e); int XUngrabKeyboard(Display *_d_i_s_p_l_a_y, Time _t_i_m_e);

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.
_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.
_t_i_m_e Specifies the time.
You can pass either a timestamp or _C_u_r_r_e_n_t_T_i_m_e.

DESCRIPTION

The _X_G_r_a_b_K_e_y_b_o_a_r_d function actively grabs control of the keyboard and generates _F_o_c_u_s_I_n and _F_o_c_u_s_O_u_t events. Further key events are reported only to the grabbing client. _X_G_r_a_b_K_e_y_b_o_a_r_d overrides any active keyboard grab by this client. If owner_events is _F_a_l_s_e, all generated key events are reported with respect to grab_window. If owner_events is _T_r_u_e and if a generated key event would normally be reported to this client, it is reported normally; otherwise, the event is reported with respect to the grab_window. Both _K_e_y_P_r_e_s_s and _K_e_y_R_e_l_e_a_s_e events are always reported, independent of any event selection made by the client.

If the keyboard_mode argument is _G_r_a_b_M_o_d_e_A_s_y_n_c, keyboard event processing continues as usual. If the keyboard is currently frozen by this client, then processing of keyboard events is resumed. If the keyboard_mode argument is _G_r_a_b_M_o_d_e_S_y_n_c, the state of the keyboard (as seen by client applications) appears to freeze, and the X server generates no further keyboard events until the grabbing client issues a releasing _X_A_l_l_o_w_E_v_e_n_t_s call or until the keyboard grab is released. Actual keyboard changes are not lost while the keyboard is frozen; they are simply queued in the server for later processing.

If pointer_mode is _G_r_a_b_M_o_d_e_A_s_y_n_c, pointer event processing is unaffected by activation of the grab. If pointer_mode is _G_r_a_b_M_o_d_e_S_y_n_c, the state of the pointer (as seen by client applications) appears to freeze, and the X server generates no further pointer events until the grabbing client issues a releasing _X_A_l_l_o_w_E_v_e_n_t_s call or until the keyboard grab is released. Actual pointer changes are not lost while the pointer is frozen; they are simply queued in the server for later processing.

If the keyboard is actively grabbed by some other client, _X_G_r_a_b_K_e_y_b_o_a_r_d fails and returns _A_l_r_e_a_d_y_G_r_a_b_b_e_d. If grab_window is not viewable, it fails and returns _G_r_a_b_N_o_t_V_i_e_w_a_b_l_e. If the keyboard is frozen by an active grab of another client, it fails and returns _G_r_a_b_F_r_o_z_e_n. If the specified time is earlier than the last-keyboard-grab time or later than the current X server time, it fails and returns _G_r_a_b_I_n_v_a_l_i_d_T_i_m_e. Otherwise, the last-keyboard-grab time is set to the specified time (_C_u_r_r_e_n_t_T_i_m_e is replaced by the current X server time).

_X_G_r_a_b_K_e_y_b_o_a_r_d can generate _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_b_o_a_r_d function releases the keyboard and any queued events if this client has it actively grabbed from either _X_G_r_a_b_K_e_y_b_o_a_r_d or _X_G_r_a_b_K_e_y. _X_U_n_g_r_a_b_K_e_y_b_o_a_r_d does not release the keyboard and any queued events if the specified time is earlier than the last-keyboard-grab time or is later than the current X server time. It also generates _F_o_c_u_s_I_n and _F_o_c_u_s_O_u_t events. The X server automatically performs an _U_n_g_r_a_b_K_e_y_b_o_a_r_d request if the event window for an active keyboard grab becomes not viewable.

DIAGNOSTICS

_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 argument, 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), XGrabKey(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