NAME

XChangeKeyboardMapping, XGetKeyboardMapping, XDisplayKeycodes, XSetModifierMapping, XGetModifierMapping, XNewModifiermap, XInsertModifiermapEntry, XDeleteModifiermapEntry, XFreeModifierMap XModifierKeymap - manipulate keyboard encoding and keyboard encoding structure

SYNTAX

int XChangeKeyboardMapping(Display *_d_i_s_p_l_a_y, int _f_i_r_s_t___k_e_y_c_o_d_e, int _k_e_y_s_y_m_s___p_e_r___k_e_y_c_o_d_e, KeySym *_k_e_y_s_y_m_s, int _n_u_m___c_o_d_e_s); KeySym *XGetKeyboardMapping(Display *_d_i_s_p_l_a_y, KeyCode _f_i_r_s_t___k_e_y_c_o_d_e, int _k_e_y_c_o_d_e___c_o_u_n_t, int *_k_e_y_s_y_m_s___p_e_r___k_e_y_c_o_d_e___r_e_t_u_r_n); int XDisplayKeycodes(Display *_d_i_s_p_l_a_y, int *_m_i_n___k_e_y_c_o_d_e_s___r_e_t_u_r_n, int *_m_a_x___k_e_y_c_o_d_e_s___r_e_t_u_r_n); int XSetModifierMapping(Display *_d_i_s_p_l_a_y, XModifierKeymap *_m_o_d_m_a_p); XModifierKeymap *XGetModifierMapping(Display *_d_i_s_p_l_a_y); XModifierKeymap *XNewModifiermap(int _m_a_x___k_e_y_s___p_e_r___m_o_d); XModifierKeymap *XInsertModifiermapEntry(XModifierKeymap *_m_o_d_m_a_p, KeyCode _k_e_y_c_o_d_e___e_n_t_r_y, int _m_o_d_i_f_i_e_r); XModifierKeymap *XDeleteModifiermapEntry(XModifierKeymap *_m_o_d_m_a_p, KeyCode _k_e_y_c_o_d_e___e_n_t_r_y, int _m_o_d_i_f_i_e_r); int XFreeModifiermap(XModifierKeymap *_m_o_d_m_a_p);

ARGUMENTS

_d_i_s_p_l_a_y Specifies the connection to the X server.
_f_i_r_s_t___k_e_y_c_o_d_e Specifies the first KeyCode that is to be changed or returned.
_k_e_y_c_o_d_e___c_o_u_n_t Specifies the number of KeyCodes that are to be returned.
_k_e_y_c_o_d_e___e_n_t_r_y Specifies the KeyCode.
_k_e_y_s_y_m_s Specifies an array of KeySyms.
_k_e_y_s_y_m_s___p_e_r___k_e_y_c_o_d_e Specifies the number of KeySyms per KeyCode.
_k_e_y_s_y_m_s___p_e_r___k_e_y_c_o_d_e___r_e_t_u_r_n Returns the number of KeySyms per KeyCode.
_m_a_x___k_e_y_s___p_e_r___m_o_d Specifies the number of KeyCode entries preallocated to the modifiers
in the map.
_m_a_x___k_e_y_c_o_d_e_s___r_e_t_u_r_n Returns the maximum number of KeyCodes.
_m_i_n___k_e_y_c_o_d_e_s___r_e_t_u_r_n Returns the minimum number of KeyCodes.
_m_o_d_i_f_i_e_r Specifies the modifier.
_m_o_d_m_a_p Specifies the
_X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure.
_n_u_m___c_o_d_e_s Specifies the number of KeyCodes that are to be changed.

DESCRIPTION

The _X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g function defines the symbols for the specified number of KeyCodes starting with first_keycode. The symbols for KeyCodes outside this range remain unchanged. The number of elements in keysyms must be:


num_codes * keysyms_per_keycode


The specified first_keycode must be greater than or equal to min_keycode returned by _X_D_i_s_p_l_a_y_K_e_y_c_o_d_e_s, or a _B_a_d_V_a_l_u_e error results. In addition, the following expression must be less than or equal to max_keycode as returned by _X_D_i_s_p_l_a_y_K_e_y_c_o_d_e_s, or a _B_a_d_V_a_l_u_e error results:


first_keycode + num_codes - 1


KeySym number N, counting from zero, for KeyCode K has the following index in keysyms, counting from zero:


(K - first_keycode) * keysyms_per_keycode + N


The specified keysyms_per_keycode can be chosen arbitrarily by the client to be large enough to hold all desired symbols. A special KeySym value of _N_o_S_y_m_b_o_l should be used to fill in unused elements for individual KeyCodes. It is legal for _N_o_S_y_m_b_o_l to appear in nontrailing positions of the effective list for a KeyCode. _X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g generates a _M_a_p_p_i_n_g_N_o_t_i_f_y event.

There is no requirement that the X server interpret this mapping. It is merely stored for reading and writing by clients.

_X_C_h_a_n_g_e_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g can generate _B_a_d_A_l_l_o_c and _B_a_d_V_a_l_u_e errors.

The _X_G_e_t_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g function returns the symbols for the specified number of KeyCodes starting with first_keycode. The value specified in first_keycode must be greater than or equal to min_keycode as returned by _X_D_i_s_p_l_a_y_K_e_y_c_o_d_e_s, or a _B_a_d_V_a_l_u_e error results. In addition, the following expression must be less than or equal to max_keycode as returned by _X_D_i_s_p_l_a_y_K_e_y_c_o_d_e_s:


first_keycode + keycode_count - 1


If this is not the case, a _B_a_d_V_a_l_u_e error results. The number of elements in the KeySyms list is:


keycode_count * keysyms_per_keycode_return


KeySym number N, counting from zero, for KeyCode K has the following index in the list, counting from zero:

(K - first_code) * keysyms_per_code_return + N


The X server arbitrarily chooses the keysyms_per_keycode_return value to be large enough to report all requested symbols. A special KeySym value of _N_o_S_y_m_b_o_l is used to fill in unused elements for individual KeyCodes. To free the storage returned by _X_G_e_t_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g, use _X_F_r_e_e.

_X_G_e_t_K_e_y_b_o_a_r_d_M_a_p_p_i_n_g can generate a _B_a_d_V_a_l_u_e error.

The _X_D_i_s_p_l_a_y_K_e_y_c_o_d_e_s function returns the min-keycodes and max-keycodes supported by the specified display. The minimum number of KeyCodes returned is never less than 8, and the maximum number of KeyCodes returned is never greater than 255. Not all KeyCodes in this range are required to have corresponding keys.

The _X_S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g function specifies the KeyCodes of the keys (if any) that are to be used as modifiers. If it succeeds, the X server generates a _M_a_p_p_i_n_g_N_o_t_i_f_y event, and _X_S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g returns _M_a_p_p_i_n_g_S_u_c_c_e_s_s. X permits at most 8 modifier keys. If more than 8 are specified in the _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure, a _B_a_d_L_e_n_g_t_h error results.

The modifiermap member of the _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure contains 8 sets of max_keypermod KeyCodes, one for each modifier in the order _S_h_i_f_t, _L_o_c_k, _C_o_n_t_r_o_l, _M_o_d_1, _M_o_d_2, _M_o_d_3, _M_o_d_4, and _M_o_d_5. Only nonzero KeyCodes have meaning in each set, and zero KeyCodes are ignored. In addition, all of the nonzero KeyCodes must be in the range specified by min_keycode and max_keycode in the _D_i_s_p_l_a_y structure, or a _B_a_d_V_a_l_u_e error results.

An X server can impose restrictions on how modifiers can be changed, for example, if certain keys do not generate up transitions in hardware, if auto-repeat cannot be disabled on certain keys, or if multiple modifier keys are not supported. If some such restriction is violated, the status reply is _M_a_p_p_i_n_g_F_a_i_l_e_d, and none of the modifiers are changed. If the new KeyCodes specified for a modifier differ from those currently defined and any (current or new) keys for that modifier are in the logically down state, _X_S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g returns _M_a_p_p_i_n_g_B_u_s_y, and none of the modifiers is changed.

_X_S_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g can generate _B_a_d_A_l_l_o_c and _B_a_d_V_a_l_u_e errors.

The _X_G_e_t_M_o_d_i_f_i_e_r_M_a_p_p_i_n_g function returns a pointer to a newly created _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure that contains the keys being used as modifiers. The structure should be freed after use by calling _X_F_r_e_e_M_o_d_i_f_i_e_r_m_a_p. If only zero values appear in the set for any modifier, that modifier is disabled.

The _X_N_e_w_M_o_d_i_f_i_e_r_m_a_p function returns a pointer to _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure for later use.

The _X_I_n_s_e_r_t_M_o_d_i_f_i_e_r_m_a_p_E_n_t_r_y function adds the specified KeyCode to the set that controls the specified modifier and returns the resulting _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure (expanded as needed).

The _X_D_e_l_e_t_e_M_o_d_i_f_i_e_r_m_a_p_E_n_t_r_y function deletes the specified KeyCode from the set that controls the specified modifier and returns a pointer to the resulting _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure.

The _X_F_r_e_e_M_o_d_i_f_i_e_r_m_a_p function frees the specified _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure.

STRUCTURES

The _X_M_o_d_i_f_i_e_r_K_e_y_m_a_p structure contains:


typedef struct {
     int max_keypermod;  /* This server's max number of keys per modifier */
     KeyCode *modifiermap;/* An 8 by max_keypermod array of the modifiers */
} XModifierKeymap;


DIAGNOSTICS

_B_a_d_A_l_l_o_c
The server failed to allocate the requested resource or server memory.
_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.

SEE ALSO

XFree(3X11), XSetPointerMapping(3X11)
_X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e