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