1XkbGetKeyboardByName(3) XKB FUNCTIONS XkbGetKeyboardByName(3)
2
6 XkbGetKeyboardByName - Build a new keyboard description from a set of
7 named components, and to optionally have the server use the resulting
8 description to replace an active one
9
11 XkbDescPtr XkbGetKeyboardByName (Display *dpy, unsigned int de‐
12 vice_spec, XkbComponentNamesPtr names, unsigned int want, un‐
13 signed int need, Bool load);
14
16 - dpy connection to X server
17 - device_spec
19 device ID, or XkbUseCoreKbd
20 - names
22 names of components to fetch
23 - want desired structures in returned record
25 - need mandatory structures in returned record
27 - load True => load into device_spec
29
31 A client may request that the server fetch one or more components from
32 its database and use those components to build a new server keyboard
33 description. The new keyboard description may be built from scratch,
34 or it may be built starting with the current keyboard description for a
35 particular device. Once the keyboard description is built, all or part
36 of it may be returned to the client. The parts returned to the client
37 need not include all of the parts used to build the description. At the
38 time it requests the server to build a new keyboard description, a
39 client may also request that the server use the new description inter‐
40 nally to replace the current keyboard description for a specific de‐
41 vice, in which case the behavior of the device changes accordingly.
42 To build a new keyboard description from a set of named components, and
44 to optionally have the server use the resulting description to replace
45 an active one, use XkbGetKeyboardByName.
46 names contains a set of expressions describing the keyboard components
48 the server should use to build the new keyboard description. want and
49 need are bit fields describing the parts of the resulting keyboard de‐
50 scription that should be present in the returned XkbDescRec.
51 The individual fields in names are component expressions composed of
53 keyboard component names (no wildcarding as may be used in XkbListCom‐
54 ponents), the special component name symbol `%', and the special opera‐
55 tor characters `+' and `|'. A component expression is parsed left to
56 right, as follows:
57 • The special component name "computed" may be used in keycodes com‐
60 ponent expressions and refers to a component consisting of a set
61 of keycodes computed automatically by the server as needed.
62 • The special component name "canonical" may be used in types compo‐
64 nent expressions and refers to a partial component defining the
65 four standard key types: ALPHABETIC, ONE_LEVEL, TWO_LEVEL, and
66 KEYPAD.
67 • The special component name `%' refers to the keyboard description
69 for the device specified in device_spec or the keymap names compo‐
70 nent. If a keymap names component is specified that does not begin
71 with `+' or `|' and does not contain `%', then `%' refers to the
72 description generated by the keymap names component. Otherwise,
73 it refers to the keyboard description for device_spec.
74 • The `+' operator specifies that the following component should
76 override the currently assembled description; any definitions that
77 are present in both components are taken from the second.
78 • The `|' operator specifies that the next specified component
80 should augment the currently assembled description; any defini‐
81 tions that are present in both components are taken from the
82 first.
83 • If the component expression begins with an operator, a leading `%'
85 is implied.
86 • If any unknown or illegal characters appear anywhere in the ex‐
88 pression, the entire expression is invalid and is ignored.
89 For example, if names->symbols contained the expression "+de", it
91 specifies that the default member of the "de" class of symbols
92 should be applied to the current keyboard mapping, overriding any
93 existing definitions (it could also be written "+de(default)").
94 Here is a slightly more involved example: the expression
96 "acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping
97 for the ASCII keyboard supplied by the "acme" vendor. The new def‐
98 inition begins with the symbols for the ASCII keyboard for Acme
99 (acme(ascii)), overrides them with definitions for the basic Ger‐
100 man keyboard (de(basic)), and then applies the definitions from
101 the default iso9995-3 keyboard (iso9995-3) to any undefined keys
102 or groups of keys (part three of the iso9995 standard defines a
103 common set of bindings for the secondary group, but allows na‐
104 tional layouts to override those definitions where necessary).
105 NOTE The interpretation of the above expression components (acme,
107 ascii, de, basic, iso9995-3) is not defined by Xkb; only the oper‐
108 ations and their ordering are.
109 Note that the presence of a keymap names component that does not
111 contain `%' (either explicit or implied by virtue of an expression
112 starting with an operator) indicates a description that is inde‐
113 pendent of the keyboard description for the device specified in
114 device_spec. The same is true of requests in which the keymap
115 names component is empty and all five other names components con‐
116 tain expressions void of references to `%'. Requests of this form
117 allow you to deal with keyboard definitions independent of any ac‐
118 tual device.
119 The server parses all non-NULL fields in names and uses them to
121 build a keyboard description. However, before parsing the expres‐
122 sions in names, the server ORs the bits in want and need together
123 and examines the result in relationship to the expressions in
124 names. Table 1 identifies the components that are required for
125 each of the possible bits in want or need. If a required compo‐
126 nent has not been specified in the names structure (the corre‐
127 sponding field is NULL), the server substitutes the expression
128 "%", resulting in the component values being taken from de‐
129 vice_spec. In addition, if load is True, the server modifies
130 names if necessary (again using a "%" entry) to ensure all of the
131 following fields are non-NULL: types, keycodes, symbols, and com‐
132 pat.
133 Table 1 Want and Need Mask Bits and Required Names Components
134 ────────────────────────────────────────────────────────────────────────────────────
135 want or need mask bit Required names Components value
136 ────────────────────────────────────────────────────────────────────────────────────
137 XkbGBN_TypesMask Types (1L<<0)
138 XkbGBN_CompatMapMask Compat (1L<<1)
139 XkbGBN_ClientSymbolsMask Types + Symbols + Keycodes (1L<<2)
140 XkbGBN_ServerSymbolsMask Types + Symbols + Keycodes (1L<<3)
141 XkbGBN_SymbolsMask Symbols (1L<<1)
142 XkbGBN_IndicatorMapMask Compat (1L<<4)
143 XkbGBN_KeyNamesMask Keycodes (1L<<5)
144 XkbGBN_GeometryMask Geometry (1L<<6)
145 XkbGBN_OtherNamesMask Types + Symbols + Keycodes + Compat + Geometry (1L<<7)
146 XkbGBN_AllComponentsMask (0xff)
147 need specifies a set of keyboard components that the server must
148 be able to resolve in order for XkbGetKeyboardByName to succeed;
149 if any of the components specified in need cannot be successfully
150 resolved, XkbGetKeyboardByName fails.
151 want specifies a set of keyboard components that the server should
152 attempt to resolve, but that are not mandatory. If the server is
153 unable to resolve any of these components, XkbGetKeyboardByName
154 still succeeds. Bits specified in want that are also specified in
155 need have no effect in the context of want.
156 If load is True, the server updates its keyboard description for
157 device_spec to match the result of the keyboard description just
158 built. If load is False, the server's description for device de‐
159 vice_spec is not updated. In all cases, the parts specified by
160 want and need from the just-built keyboard description are re‐
161 turned.
162 The names structure in an XkbDescRec keyboard description record
163 contains one field for each of the five component types used to
164 build a keyboard description. When a keyboard description is built
165 from a set of database components, the corresponding fields in
166 this names structure are set to match the expressions used to
167 build the component.
168 Building a New Keyboard Description from the Server Database
169 The information returned to the client in the XkbDescRec is essen‐
170 tially the result of a series of calls to extract information from
171 a fictitious device whose description matches the one just built.
172 The calls corresponding to each of the mask bits are summarized in
173 Table 2, together with the XkbDescRec components that are filled
174 in.
175 Table 2 XkbDescRec Components Returned for Values of Want & Needs
176 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
177 Request (want+need) Fills in Xkb components Equivalent Function Call
178 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
179 XkbGBN_TypesMask map.types XkbGetUpdatedMap(dpy, XkbTypesMask, Xkb)
180 XkbGBN_ServerSymbolsMask server XkbGetUpdatedMap(dpy,
181 XkbAllClientInfoMask, Xkb)
182 XkbGBN_ClientSymbolsMask map, including map.types
183 XkbGetUpdatedMap(dpy, XkbAllServerInfoMask, Xkb)
184 XkbGBN_IndicatorMaps indicators XkbGetIndicatorMap(dpy,
185 XkbAllIndicators, Xkb)
186 XkbGBN_CompatMapMask compat XkbGetCompatMap(dpy, XkbAllCompatMask, Xkb)
187 XkbGBN_GeometryMask geom XkbGetGeometry(dpy, Xkb)
188 XkbGBN_KeyNamesMask names.keys XkbGetNames(dpy, XkbKeyNamesMask |
189 names.key_aliases XkbKeyAliasesMask, Xkb)
190 XkbGBN_OtherNamesMask names.keycodes XkbGetNames(dpy, XkbAllNamesMask &
191 names.geometry ~(XkbKeyNamesMask | XkbKeyAliasesMask),
192 names.symbols Xkb)
193 names.types
194 map.types[*].lvl_names[*]
195 names.compat
196 names.vmods
197 names.indicators
198 names.groups
199 names.radio_groups
200 names.phys_symbols
201 There is no way to determine which components specified in want
202 (but not in need) were actually fetched, other than breaking the
203 call into successive calls to XkbGetKeyboardByName and specifying
204 individual components.
205 XkbGetKeyboardByName always sets min_key_code and max_key_code in
206 the returned XkbDescRec structure.
207 XkbGetKeyboardByName is synchronous; it sends the request to the
208 server to build a new keyboard description and waits for the re‐
209 ply. If successful, the return value is non-NULL. XkbGetKeyboard‐
210 ByName generates a BadMatch protocol error if errors are encoun‐
211 tered when building the keyboard description.
213 The complete description of an Xkb keyboard is given by an XkbDescRec.
214 The component structures in the XkbDescRec represent the major Xkb com‐
215 ponents outlined in Figure 1.1.
216 typedef struct {
218 struct _XDisplay * display; /* connection to X server */
219 unsigned short flags; /* private to Xkb, do not modify */
220 unsigned short device_spec; /* device of interest */
221 KeyCode min_key_code; /* minimum keycode for device */
222 KeyCode max_key_code; /* maximum keycode for device */
223 XkbControlsPtr ctrls; /* controls */
224 XkbServerMapPtr server; /* server keymap */
225 XkbClientMapPtr map; /* client keymap */
226 XkbIndicatorPtr indicators; /* indicator map */
227 XkbNamesPtr names; /* names for all components */
228 XkbCompatMapPtr compat; /* compatibility map */
229 XkbGeometryPtr geom; /* physical geometry of keyboard */
230 } XkbDescRec, *XkbDescPtr;
231 The display field points to an X display structure. The flags field is
233 private to the library: modifying flags may yield unpredictable re‐
234 sults. The device_spec field specifies the device identifier of the
235 keyboard input device, or XkbUseCoreKeyboard, which specifies the core
236 keyboard device. The min_key_code and max_key_code fields specify the
237 least and greatest keycode that can be returned by the keyboard.
238 Each structure component has a corresponding mask bit that is used in
240 function calls to indicate that the structure should be manipulated in
241 some manner, such as allocating it or freeing it. These masks and their
242 relationships to the fields in the XkbDescRec are shown in Table 3.
243 Table 3 Mask Bits for XkbDescRec
246 ──────────────────────────────────────────────────
247 Mask Bit XkbDescRec Field Value
249 ──────────────────────────────────────────────────
250 XkbControlsMask ctrls (1L<<0)
252 XkbServerMapMask server (1L<<1)
253 XkbIClientMapMask map (1L<<2)
255 XkbIndicatorMapMask indicators (1L<<3)
256 XkbNamesMask names (1L<<4)
258 XkbCompatMapMask compat (1L<<5)
259 XkbGeometryMask geom (1L<<6)
261 XkbAllComponentsMask All Fields (0x7f)
262
264 BadMatch A compatible version of Xkb was not available in the
265 server or an argument has correct type and range, but is
266 otherwise invalid
267
269 XkbListComponents(3)
270X Version 11 libX11 1.7.2 XkbGetKeyboardByName(3)