XkbGetKeyboardByName - Build a new keyboard description from a set of named
components, and to optionally have the server use the resulting description to
replace an active one
XkbDescPtr
XkbGetKeyboardByName (Display *dpy, unsigned int
device_spec, XkbComponentNamesPtr
names, unsigned int want, unsigned
int need, Bool load);
- dpy
- connection to X server
- device_spec
- device ID, or XkbUseCoreKbd
- names
- names of components to fetch
- want
- desired structures in returned record
- need
- mandatory structures in returned record
- load
- True => load into device_spec
A client may request that the server fetch one or more components from its
database and use those components to build a new server keyboard description.
The new keyboard description may be built from scratch, or it may be built
starting with the current keyboard description for a particular device. Once
the keyboard description is built, all or part of it may be returned to the
client. The parts returned to the client need not include all of the parts
used to build the description. At the time it requests the server to build a
new keyboard description, a client may also request that the server use the
new description internally to replace the current keyboard description for a
specific device, in which case the behavior of the device changes accordingly.
To build a new keyboard description from a set of named components, and to
optionally have the server use the resulting description to replace an active
one, use
XkbGetKeyboardByName.
names contains a set of expressions describing the keyboard components
the server should use to build the new keyboard description.
want and
need are bit fields describing the parts of the resulting keyboard
description that should be present in the returned XkbDescRec.
The individual fields in
names are
component expressions composed
of keyboard component names (no wildcarding as may be used in
XkbListComponents), the special component name symbol `%', and the
special operator characters `+' and `|'. A component expression is parsed left
to right, as follows:
- •
- The special component name "computed" may be used
in keycodes component expressions and refers to a component consisting of
a set of keycodes computed automatically by the server as needed.
- •
- The special component name "canonical" may be
used in types component expressions and refers to a partial component
defining the four standard key types: ALPHABETIC, ONE_LEVEL, TWO_LEVEL,
and KEYPAD.
- •
- The special component name `%' refers to the keyboard
description for the device specified in device_spec or the keymap names
component. If a keymap names component is specified that does not begin
with `+' or `|' and does not contain `%', then `%' refers to the
description generated by the keymap names component. Otherwise, it refers
to the keyboard description for device_spec.
- •
- The `+' operator specifies that the following component
should override the currently assembled description; any definitions that
are present in both components are taken from the second.
- •
- The `|' operator specifies that the next specified
component should augment the currently assembled description; any
definitions that are present in both components are taken from the
first.
- •
- If the component expression begins with an operator, a
leading `%' is implied.
- •
- 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.
The complete description of an Xkb keyboard is given by an XkbDescRec. The
component structures in the XkbDescRec represent the major Xkb components
outlined in Figure 1.1.
typedef struct {
struct _XDisplay * display; /* connection to X server */
unsigned short flags; /* private to Xkb, do not modify */
unsigned short device_spec; /* device of interest */
KeyCode min_key_code; /* minimum keycode for device */
KeyCode max_key_code; /* maximum keycode for device */
XkbControlsPtr ctrls; /* controls */
XkbServerMapPtr server; /* server keymap */
XkbClientMapPtr map; /* client keymap */
XkbIndicatorPtr indicators; /* indicator map */
XkbNamesPtr names; /* names for all components */
XkbCompatMapPtr compat; /* compatibility map */
XkbGeometryPtr geom; /* physical geometry of keyboard */
} XkbDescRec, *XkbDescPtr;
The
display field points to an X display structure. The
flags field is
private to the library: modifying flags may yield unpredictable
results. The
device_spec field specifies the device identifier of the
keyboard input device, or XkbUseCoreKeyboard, which specifies the core
keyboard device. The
min_key_code and
max_key_code fields
specify the least and greatest keycode that can be returned by the keyboard.
Each structure component has a corresponding mask bit that is used in function
calls to indicate that the structure should be manipulated in some manner,
such as allocating it or freeing it. These masks and their relationships to
the fields in the XkbDescRec are shown in Table 3.
Table 3 Mask Bits for XkbDescRec |
|
|
|
Mask Bit |
XkbDescRec Field |
Value |
|
XkbControlsMask |
ctrls |
(1L<<0) |
XkbServerMapMask |
server |
(1L<<1) |
XkbIClientMapMask |
map |
(1L<<2) |
XkbIndicatorMapMask |
indicators |
(1L<<3) |
XkbNamesMask |
names |
(1L<<4) |
XkbCompatMapMask |
compat |
(1L<<5) |
XkbGeometryMask |
geom |
(1L<<6) |
XkbAllComponentsMask |
All Fields |
(0x7f) |
- BadMatch
- A compatible version of Xkb was not available in the server
or an argument has correct type and range, but is otherwise invalid
XkbListComponents(3)