If any unknown or illegal characters appear anywhere in the expression,
the entire expression is invalid and is ignored.
For example, if names->symbols contained the
expression "+de", it specifies that the default member of the
"de" class of symbols should be applied to the current
keyboard mapping, overriding any existing definitions (it could also be
written "+de(default)").
Here is a slightly more involved example: the expression
"acme(ascii)+de(basic)|iso9995-3" constructs a German (de)
mapping for the ASCII keyboard supplied by the "acme" vendor.
The new definition begins with the symbols for the ASCII keyboard for
Acme (acme(ascii)), overrides them with definitions for the basic
German keyboard (de(basic)), and then applies the definitions
from the default iso9995-3 keyboard (iso9995-3) to any undefined
keys or groups of keys (part three of the iso9995 standard defines a
common set of bindings for the secondary group, but allows national
layouts to override those definitions where necessary).
NOTE The interpretation of the above expression
components (acme, ascii, de, basic, iso9995-3) is not defined by Xkb;
only the operations and their ordering are.
Note that the presence of a keymap names component that
does not contain `%' (either explicit or implied by virtue of an
expression starting with an operator) indicates a description that is
independent of the keyboard description for the device specified in
device_spec. The same is true of requests in which the keymap
names component is empty and all five other names components contain
expressions void of references to `%'. Requests of this form allow you
to deal with keyboard definitions independent of any actual device.
The server parses all non-NULL fields in names and uses
them to build a keyboard description. However, before parsing the
expressions in names, the server ORs the bits in want and
need together and examines the result in relationship to the
expressions in names. Table 1 identifies the components that are
required for each of the possible bits in want or need. If
a required component has not been specified in the names structure
(the corresponding field is NULL), the server substitutes the
expression "%", resulting in the component values being taken
from device_spec. In addition, if load is True, the server
modifies names if necessary (again using a "%" entry)
to ensure all of the following fields are non-NULL: types, keycodes,
symbols, and compat.
Table 1 Want and Need Mask
Bits and Required Names Components |
want or need mask bit |
Required names Components |
value |
XkbGBN_TypesMask |
Types |
(1L<<0) |
XkbGBN_CompatMapMask |
Compat |
(1L<<1) |
XkbGBN_ClientSymbolsMask |
Types + Symbols + Keycodes |
(1L<<2) |
XkbGBN_ServerSymbolsMask |
Types + Symbols + Keycodes |
(1L<<3) |
XkbGBN_SymbolsMask |
Symbols |
(1L<<1) |
XkbGBN_IndicatorMapMask |
Compat |
(1L<<4) |
XkbGBN_KeyNamesMask |
Keycodes |
(1L<<5) |
XkbGBN_GeometryMask |
Geometry |
(1L<<6) |
XkbGBN_OtherNamesMask |
Types + Symbols + Keycodes + Compat + Geometry |
(1L<<7) |
XkbGBN_AllComponentsMask |
|
(0xff) |
need specifies a set of keyboard components that the
server must be able to resolve in order for XkbGetKeyboardByName
to succeed; if any of the components specified in need cannot be
successfully resolved, XkbGetKeyboardByName fails.
want specifies a set of keyboard components that the
server should attempt to resolve, but that are not mandatory. If the
server is unable to resolve any of these components,
XkbGetKeyboardByName still succeeds. Bits specified in
want that are also specified in need have no effect in the
context of want.
If load is True, the server updates its keyboard
description for device_spec to match the result of the keyboard
description just built. If load is False, the server's description for
device device_spec is not updated. In all cases, the parts
specified by want and need from the just-built keyboard
description are returned.
The names structure in an XkbDescRec keyboard
description record contains one field for each of the five component
types used to build a keyboard description. When a keyboard description
is built from a set of database components, the corresponding fields in
this names structure are set to match the expressions used to
build the component.
Building a New Keyboard Description from the Server
Database
The information returned to the client in the XkbDescRec is
essentially the result of a series of calls to extract information from
a fictitious device whose description matches the one just built. The
calls corresponding to each of the mask bits are summarized in Table 2,
together with the XkbDescRec components that are filled in.
Table 2 XkbDescRec
Components Returned for Values of Want & Needs |
Request (want+need) |
Fills in Xkb components |
Equivalent Function Call |
XkbGBN_TypesMask |
map.types |
XkbGetUpdatedMap(dpy, XkbTypesMask, Xkb) |
XkbGBN_ServerSymbolsMask |
server |
XkbGetUpdatedMap(dpy, |
XkbAllClientInfoMask, Xkb) |
XkbGBN_ClientSymbolsMask |
map, including map.types |
XkbGetUpdatedMap(dpy, XkbAllServerInfoMask, Xkb) |
XkbGBN_IndicatorMaps |
indicators |
XkbGetIndicatorMap(dpy, |
XkbAllIndicators, Xkb) |
XkbGBN_CompatMapMask |
compat |
XkbGetCompatMap(dpy, XkbAllCompatMask, Xkb) |
XkbGBN_GeometryMask |
geom |
XkbGetGeometry(dpy, Xkb) |
XkbGBN_KeyNamesMask |
names.keys |
XkbGetNames(dpy, XkbKeyNamesMask | |
|
names.key_aliases |
XkbKeyAliasesMask, Xkb) |
XkbGBN_OtherNamesMask |
names.keycodes |
XkbGetNames(dpy, XkbAllNamesMask & |
|
names.geometry |
~(XkbKeyNamesMask | XkbKeyAliasesMask), |
|
names.symbols |
Xkb) |
|
names.types |
|
map.types[*].lvl_names[*] |
|
names.compat |
|
names.vmods |
|
names.indicators |
|
names.groups |
|
names.radio_groups |
|
names.phys_symbols |
There is no way to determine which components specified in
want (but not in need) were actually fetched, other than
breaking the call into successive calls to XkbGetKeyboardByName
and specifying individual components.
XkbGetKeyboardByName always sets min_key_code
and max_key_code in the returned XkbDescRec structure.
XkbGetKeyboardByName is synchronous; it sends the
request to the server to build a new keyboard description and waits for
the reply. If successful, the return value is non-NULL.
XkbGetKeyboardByName generates a BadMatch protocol error if
errors are encountered when building the keyboard description.