1XkbSetMap(3) XKB FUNCTIONS XkbSetMap(3)
2
6 XkbSetMap - Send a complete new set of values for entire components to
7 the server.
8
10 Bool XkbSetMap (Display *dpy, unsigned int which, XkbDescPtr xkb);
11
13 - dpy connection to X server
14 - which
16 mask selecting subcomponents to update
17 - xkb description from which new values are taken
19
21 There are two ways to make changes to map components: either change a
22 local copy of the keyboard map and call XkbSetMap to send the modified
23 map to the server, or, to reduce network traffic, use an XkbMapChanges‐
24 Rec structure and call XkbChangeMap.
25 Use XkbSetMap to send a complete new set of values for entire compo‐
27 nents (for example, all symbols, all actions, and so on) to the server.
28 The which parameter specifies the components to be sent to the server,
29 and is a bitwise inclusive OR of the masks listed in Table 1. The xkb
30 parameter is a pointer to an XkbDescRec structure and contains the in‐
31 formation to be copied to the server. For each bit set in the which
32 parameter, XkbSetMap takes the corresponding structure values from the
33 xkb parameter and sends it to the server specified by dpy.
34 If any components specified by which are not present in the xkb parame‐
36 ter, XkbSetMap returns False. Otherwise, it sends the update request to
37 the server and returns True. XkbSetMap can generate BadAlloc,
38 BadLength, and BadValue protocol errors.
39 Key types, symbol maps, and actions are all interrelated; changes in
41 one require changes in the others. Xkb provides functions to make it
42 easier to edit these components and handle the interdependencies. Table
43 1 lists these helper functions and provides a pointer to where they are
44 defined.
45 Table 1 Xkb Mapping Component Masks
48 and Convenience Functions
49 ──────────────────────────────────────────────────────────────────────────────────────
50 Mask Value Map Fields Convenience
51 Functions
52 ──────────────────────────────────────────────────────────────────────────────────────
53 XkbKeyTypesMask (1<<0) client types XkbGetKeyTypes
54 size_types XkbResizeKeyType
55 num_types XkbCopyKeyType
56 XkbCopyKeyTypes
57 XkbKeySymsMask (1<<1) client syms XkbGetKeySyms
58 size_syms XkbResizeKeySyms
59 num_syms XkbChangeTypesOfKey
60 key_sym_map
61 XkbModifierMapMask (1<<2) client modmap XkbGetKeyModifierMap
62 XkbExplicitCompo‐ (1<<3) server explicit XkbGetKeyExplicitComponents
63 nentsMask
64 XkbKeyActionsMask (1<<4) server key_acts XkbGetKeyActions
68 acts XkbResizeKeyActions
69 num_acts
70 size_acts
71 XkbKeyBehaviorsMask (1<<5) server behaviors XkbGetKeyBehaviors
72 XkbVirtualModsMask (1<<6) server vmods XkbGetVirtualMods
73 XkbVirtualModMapMask (1<<7) server vmodmap XkbGetVirtualModMap
74 The changed field identifies the map components that have changed in an
76 XkbDescRec structure and may contain any of the bits in Table 1, which
77 are also shown in Table 2. Every 1 bit in changed also identifies which
78 other fields in the XkbMapChangesRec structure contain valid values, as
79 indicated in Table 2. The min_key_code and max_key_code fields are for
80 reference only; they are ignored on any requests sent to the server and
81 are always updated by the server whenever it returns the data for an
82 XkbMapChangesRec.
83 Table 2 XkbMapChangesRec Masks
85 ─────────────────────────────────────────────────────────────────────────────────────────────────────────
86 Valid
87 Mask XkbMapChangesRec XkbDescRec Field Containing
88 Fields Changed Data
89 ─────────────────────────────────────────────────────────────────────────────────────────────────────────
90 XkbKeyTypesMask first_type, map->type[first_type] ..
91 num_types map->type[first_type + num_types - 1]
92 XkbKeySymsMask first_key_sym, map->key_sym_map[first_key_sym] ..
94 num_key_syms map->key_sym_map[first_key_sym +
95 num_key_syms - 1]
96 XkbModifierMapMask first_modmap_key, map->modmap[first_modmap_key] ..
97 num_modmap_keys map->modmap[first_modmap_key +
98 num_modmap_keys-1]
100 XkbExplicitComponentsMask first_key_explicit,
101 server->explicit[first_key_explicit] ..
102 num_key_explicit server->explicit[first_key_explicit +
103 num_key_explicit - 1]
104 XkbKeyActionsMask first_key_act, server->key_acts[first_key_act] ..
105 num_key_acts server->key_acts[first_key_act +
106 num_key_acts - 1]
107 XkbKeyBehaviorsMask first_key_behavior,
108 server->behaviors[first_key_behavior] ..
109 num_key_behaviors server->behaviors[first_key_behavior +
110 num_key_behaviors - 1]
111 XkbVirtualModsMask vmods server->vmods[*]
112 XkbVirtualModMapMask first_vmodmap_key,
113 server->vmodmap[first_vmodmap_key]
114 num_vmodmap_keys ..
116 server->vmodmap[first_vmodmap_key
117 + num_vmodmap_keys - 1]
118
120 True The XkbSetMap function returns True all components spec‐
121 ified by which are present in the xkb parameter.
122 False The XkbSetMap function returns False if any component
124 specified by which is not present in the xkb parameter.
125
127 Use the XkbMapChangesRec structure to identify and track partial modi‐
128 fications to the mapping components and to reduce the amount of traffic
129 between the server and clients.
130 typedef struct _XkbMapChanges {
132 unsigned short changed; /∗ identifies valid components in structure */
133 KeyCode min_key_code; /∗ lowest numbered keycode for device */
134 KeyCode max_key_code; /∗ highest numbered keycode for device */
135 unsigned char first_type; /∗ index of first key type modified */
136 unsigned char num_types; /∗ # types modified */
137 KeyCode first_key_sym; /∗ first key whose key_sym_map changed */
138 unsigned char num_key_syms; /∗ # key_sym_map entries changed */
139 KeyCode first_key_act; /∗ first key whose key_acts entry changed */
140 unsigned char num_key_acts; /∗ # key_acts entries changed */
141 KeyCode first_key_behavior; /∗ first key whose behaviors changed */
142 unsigned char num_key_behaviors; /∗ # behaviors entries changed */
143 KeyCode first_key_explicit; /∗ first key whose explicit entry changed */
144 unsigned char num_key_explicit; /∗ # explicit entries changed */
145 KeyCode first_modmap_key; /∗ first key whose modmap entry changed */
146 unsigned char num_modmap_keys; /∗ # modmap entries changed */
147 KeyCode first_vmodmap_key; /∗ first key whose vmodmap changed */
148 unsigned char num_vmodmap_keys; /∗ # vmodmap entries changed */
149 unsigned char pad1; /∗ reserved */
150 unsigned short vmods; /∗ mask indicating which vmods changed */
151 } XkbMapChangesRec,*XkbMapChangesPtr;
152 The complete description of an Xkb keyboard is given by an XkbDescRec.
155 The component structures in the XkbDescRec represent the major Xkb com‐
156 ponents.
157 typedef struct {
159 struct _XDisplay * display; /∗ connection to X server */
160 unsigned short flags; /∗ private to Xkb, do not modify */
161 unsigned short device_spec; /∗ device of interest */
162 KeyCode min_key_code; /∗ minimum keycode for device */
163 KeyCode max_key_code; /∗ maximum keycode for device */
164 XkbControlsPtr ctrls; /∗ controls */
165 XkbServerMapPtr server; /∗ server keymap */
166 XkbClientMapPtr map; /∗ client keymap */
167 XkbIndicatorPtr indicators; /∗ indicator map */
168 XkbNamesPtr names; /∗ names for all components */
169 XkbCompatMapPtr compat; /∗ compatibility map */
170 XkbGeometryPtr geom; /∗ physical geometry of keyboard */
171 } XkbDescRec, *XkbDescPtr;
172 The display field points to an X display structure. The flags field is
174 private to the library: modifying flags may yield unpredictable re‐
175 sults. The device_spec field specifies the device identifier of the
176 keyboard input device, or XkbUseCoreKeyboard, which specifies the core
177 keyboard device. The min_key_code and max_key_code fields specify the
178 least and greatest keycode that can be returned by the keyboard.
179 Each structure component has a corresponding mask bit that is used in
181 function calls to indicate that the structure should be manipulated in
182 some manner, such as allocating it or freeing it. These masks and their
183 relationships to the fields in the XkbDescRec are shown in Table 3.
184 Table 3 Mask Bits for XkbDescRec
186 ──────────────────────────────────────────────────
187 Mask Bit XkbDescRec Field Value
190 ──────────────────────────────────────────────────
191 XkbControlsMask ctrls (1L<<0)
192 XkbServerMapMask server (1L<<1)
193 XkbIClientMapMask map (1L<<2)
195 XkbIndicatorMapMask indicators (1L<<3)
196 XkbNamesMask names (1L<<4)
197 XkbCompatMapMask compat (1L<<5)
198 XkbGeometryMask geom (1L<<6)
200 XkbAllComponentsMask All Fields (0x7f)
201
203 BadAlloc Unable to allocate storage
204 BadLength The length of a request is shorter or longer than that
206 required to minimally contain the arguments
207 BadValue An argument is out of range
209
211 XkbChangeMap(3), XkbChangeTypesOfKey(3), XkbCopyKeyType(3), XkbCopyKey‐
212 Types(3), XkbGetKeyActions(3), XkbGetKeyBehaviors(3), XkbGetKeyExplic‐
213 itComponents(3), XkbGetKeyModifierMap(3), XkbGetKeySyms(3), XkbGetKey‐
214 Types(3), XkbResizeKeyActions(3), XkbResizeKeySyms(3), XkbResizeKey‐
215 Type(3), XkbGetVirtualModMap(3), XkbGetVirtualMods(3)
216X Version 11 libX11 1.7.0 XkbSetMap(3)