Index of Section 3 Manual Pages
| Interix / SUA | XkbGetKeyboardByName.3 | Interix / SUA |
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 ( dpy, device_spec, names,
want, need, load )
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 par-
ticular 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 key-
board 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 compo-
nent consisting of a set of keycodes computed auto-
matically 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 com-
ponent 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 compo-
nent should override the currently assembled descrip-
tion; any definitions that are present in both compo-
nents 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 expres-
sion "+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 expres-
sion "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 com-
ponents (acme, ascii, de, basic, iso9995-3) is not
defined by Xkb; only the operations and their order-
ing 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 compo-
nents 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 suc-
ceeds. 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 key-
board 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 XkbDe-
scRec 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 speci-
fied in want (but not in need) were actually fetched,
other than breaking the call into successive calls to
XkbGetKeyboardByName and specifying individual compo-
nents.
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 speci-
fies 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
BadMatch A compatible version of Xkb was not avail-
able in the server or an argument has cor-
rect type and range, but is otherwise
invalid
SEE ALSO
XkbListComponents(3)
X Version 11 libX11 1.1.5 XkbGetKeyboardByName(3)