NAME
XGrabDeviceKey, XUngrabDeviceKey - grab/ungrab extension input device Keys
SYNTAX
int XGrabDeviceKey(Display *_d_i_s_p_l_a_y, XDevice *_d_e_v_i_c_e,
unsigned int _K_e_y, unsigned int _m_o_d_i_f_i_e_r_s, XDevice
*_m_o_d_i_f_i_e_r___d_e_v_i_c_e, Window _g_r_a_b___w_i_n_d_o_w, Bool
_o_w_n_e_r___e_v_e_n_t_s, unsigned int _e_v_e_n_t___c_o_u_n_t, XEventClass
_e_v_e_n_t___l_i_s_t, int _t_h_i_s___d_e_v_i_c_e___m_o_d_e, int
_o_t_h_e_r___d_e_v_i_c_e_s___m_o_d_e);
int XUngrabDeviceKey(Display *_d_i_s_p_l_a_y, XDevice *_d_e_v_i_c_e,
unsigned int _K_e_y, unsigned int _m_o_d_i_f_i_e_r_s, XDevice
*_m_o_d_i_f_i_e_r___d_e_v_i_c_e, Window _g_r_a_b___w_i_n_d_o_w);
ARGUMENTS
-
display
-
Specifies the connection to the X server.
-
device
-
Specifies the device that is to be grabbed or released
-
Key
-
Specifies the device Key that is to be grabbed or released or
_A_n_y_K_e_y.
-
modifiers
-
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.
Valid bits are: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
Mod3Mask, Mod4Mask, Mod5Mask.
-
modifier_device
-
Specifies the device whose modifiers are to be used. If a modifier_device of
NULL is specified, the X keyboard will be used as the modifier_device.
-
grab_window
-
Specifies the grab window.
-
owner_events
-
Specifies a Boolean value that indicates whether the device
events are to be reported as usual or reported with respect to the grab window
if selected by the event list.
-
event_count
-
Specifies the number of event classes in the event list.
-
event_list
-
Specifies which device events are reported to the client.
-
this_device_mode
-
Specifies further processing of events from this device.
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.
-
other_devices_mode
-
Specifies further processing of events from other devices.
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_D_e_v_i_c_e_K_e_y request establishes a passive grab.
In the future,
the device is actively grabbed (as for
_X_G_r_a_b_D_e_v_i_c_e,
the last-device-grab time is set to the time at which the Key was pressed
(as transmitted in the
_D_e_v_i_c_e_K_e_y_P_r_e_s_s
event), and the
_D_e_v_i_c_e_K_e_y_P_r_e_s_s
event is reported if all of the following conditions are true:
-
·
The device is not grabbed, and the specified key is logically pressed
-
when the specified modifier keys are logically down,
and no other keys or modifier keys are logically down.
-
·
The grab_window is an ancestor (or is) the focus window OR the grab
-
window is a descendant of the focus window and contains the device.
-
·
The confine_to window (if any) is viewable.
-
-
·
A passive grab on the same key/modifier combination does not exist
-
on any ancestor of grab_window.
The interpretation of the remaining arguments is as for
_X_G_r_a_b_D_e_v_i_c_e .
The active grab is terminated automatically when the logical state of the
device has the specified key released.
Note that the logical state of a device (as seen by means of the X protocol )
may lag the physical state if device event processing is frozen.
If the key is not _A_n_y_K_e_y, it must be in the range specified by
min_keycode and max_keycode as returned by the _X_L_i_s_t_I_n_p_u_t_D_e_v_i_c_e_s
request. Otherwise, a _B_a_d_V_a_l_u_e error results.
This request overrides all previous grabs by the same client on the same
Key/modifier combinations on the same window.
A modifier of
_A_n_y_M_o_d_i_f_i_e_r
is equivalent to issuing the grab 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 key of
_A_n_y_K_e_y
is equivalent to
issuing the request for all possible keys.
Otherwise, it is not required that the specified key currently be assigned
to a physical Key.
If a modifier_device of NULL is specified, the X keyboard will be used as
the modifier_device.
If some other client has already issued a
_X_G_r_a_b_D_e_v_i_c_e_K_e_y
with the same Key/modifier 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_D_e_v_i_c_e_K_e_y
has no effect on an active grab.
_X_G_r_a_b_D_e_v_i_c_e_K_e_y
can generate
_B_a_d_A_c_c_e_s_s,
_B_a_d_C_l_a_s_s,
_B_a_d_D_e_v_i_c_e,
_B_a_d_M_a_t_c_h,
_B_a_d_V_a_l_u_e,
and
_B_a_d_W_i_n_d_o_w
errors. It returns _S_u_c_c_e_s_s on successful completion of the request.
The _X_U_n_g_r_a_b_D_e_v_i_c_e_K_e_y
request releases the passive grab for a key/modifier combination on the
specified window if it was grabbed by this client.
A modifier of _A_n_y_M_o_d_i_f_i_e_r is
equivalent to issuing
the ungrab request for all possible modifier combinations, including
the combination of no modifiers.
A Key of _A_n_y_K_e_y
is equivalent to issuing the request for all possible Keys.
_X_U_n_g_r_a_b_D_e_v_i_c_e_K_e_y has no effect on an active grab.
If a modifier_device of NULL is specified, the X keyboard will be used as the
modifier_device.
_X_U_n_g_r_a_b_D_e_v_i_c_e_K_e_y can generate _B_a_d_D_e_v_i_c_e, _B_a_d_M_a_t_c_h,
_B_a_d_V_a_l_u_e and _B_a_d_W_i_n_d_o_w errors.
DIAGNOSTICS
-
_B_a_d_D_e_v_i_c_e
-
An invalid device was specified. The specified device does not exist or has
not been opened by this client via _X_O_p_e_n_I_n_p_u_t_D_e_v_i_c_e. This error may
also occur if the specified device is the X keyboard or X pointer device.
-
_B_a_d_M_a_t_c_h
-
This error may occur if an _X_G_r_a_b_D_e_v_i_c_e_K_e_y request was made
specifying a device that has no keys, or a modifier device that has no
keys.
-
_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
XAllowDeviceEvents(3X),
XGrabDevice(3X),
XGrabDeviceButton(3X),
_P_r_o_g_r_a_m_m_i_n_g _w_i_t_h _X_l_i_b