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