NAME

XGrabKey, XUngrabKey - grab keyboard keys

SYNTAX

int XGrabKey(Display *_d_i_s_p_l_a_y, int _k_e_y_c_o_d_e, 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, 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); int XUngrabKey(Display *_d_i_s_p_l_a_y, int _k_e_y_c_o_d_e, unsigned int _m_o_d_i_f_i_e_r_s, Window _g_r_a_b___w_i_n_d_o_w);

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.
_k_e_y_c_o_d_e Specifies the KeyCode or
_A_n_y_K_e_y.
_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 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.

DESCRIPTION

The _X_G_r_a_b_K_e_y function establishes a passive grab on the keyboard. In the future, the keyboard is actively grabbed (as for _X_G_r_a_b_K_e_y_b_o_a_r_d), the last-keyboard-grab time is set to the time at which the key was pressed (as transmitted in the _K_e_y_P_r_e_s_s event), and the _K_e_y_P_r_e_s_s event is reported if all of the following conditions are true:
· The keyboard is not grabbed and the specified key
(which can itself be a modifier key) is logically pressed when the specified modifier keys are logically down, and no other modifier keys are logically down.
· Either the grab_window is an ancestor of (or is) the focus window,
or the grab_window is a descendant of the focus window and contains the pointer.
· A passive grab on the same 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_K_e_y_b_o_a_r_d. The active grab is terminated automatically when the logical state of the keyboard has the specified key released (independent of the logical state of the modifier keys), at which point a _K_e_y_R_e_l_e_a_s_e event is reported to the grabbing window.

Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen.

A modifiers argument of _A_n_y_M_o_d_i_f_i_e_r is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A keycode argument of _A_n_y_K_e_y is equivalent to issuing the request for all possible KeyCodes. Otherwise, the specified keycode must be in the range specified by min_keycode and max_keycode in the connection setup, or a _B_a_d_V_a_l_u_e error results.

If some other client has issued a _X_G_r_a_b_K_e_y with the same 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_K_e_y, 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_K_e_y can generate _B_a_d_A_c_c_e_s_s, _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 function releases the key combination on the specified window if it was grabbed by this client. It has no effect on an active grab. A modifiers of _A_n_y_M_o_d_i_f_i_e_r is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A keycode argument of _A_n_y_K_e_y is equivalent to issuing the request for all possible key codes.

_X_U_n_g_r_a_b_K_e_y can generate _B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w error.

DIAGNOSTICS

_B_a_d_A_c_c_e_s_s
A client attempted to grab a key/button combination already grabbed by another client.
_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

XAllowAccess(3X11), XGrabButton(3X11), XGrabKeyboard(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