Tribblix: manual page: XkbGetKeyboardByName.3

XkbGetKeyboardByName(3) XKB FUNCTIONS XkbGetKeyboardByName(3)

NAME

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

SYNOPSIS

XkbDescPtr XkbGetKeyboardByName (Display *dpy, unsigned int
device_spec, XkbComponentNamesPtr names, unsigned int want,
unsigned int need, Bool load);

ARGUMENTS

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

DESCRIPTION

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:

+o 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.

+o 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.

+o 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.

+o 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.

+o 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.

+o If the component expression begins with an operator, a leading
`%' is implied.

+o 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.

STRUCTURES

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)

DIAGNOSTICS