XKB FUNCTIONS XkbGetKeyboardByName(3x11)
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 oneSYNOPSIS
cc [ flag... ] file... -lX11 [ library... ]
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 com-
ponents from its database and use those components to builda new server keyboard description. The new keyboard descrip-
tion may be built from scratch, or it may be built startingwith the current keyboard description for a particular dev-
ice. 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 com-
ponents, and to optionally have the server use the resultingdescription to replace an active one, use XkbGetKeyboard-
ByName. names contains a set of expressions describing the keyboard X Version 11 Last change: libX11 1.3.5 1XKB FUNCTIONS XkbGetKeyboardByName(3x11)
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 namesymbol `%', 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 inkeycodes component expressions and refers to a com-
ponent 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 partialcomponent defining the four standard key types: ALPHA-
BETIC, 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 `|' anddoes not contain `%', then `%' refers to the descrip-
tion generated by the keymap names component. Other-
wise, it refers to the keyboard description fordevice_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 com-
ponent should augment the currently assembled descrip-
tion; any definitions that are present in both com-
ponents are taken from the first. +o If the component expression begins with an operator, aleading `%' 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 key-
board mapping, overriding any existing definitions (it X Version 11 Last change: libX11 1.3.5 2XKB FUNCTIONS XkbGetKeyboardByName(3x11)
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 definitionsfrom 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 ordering are. Note that the presence of a keymap names component thatdoes not contain `%' (either explicit or implied by
virtue of an expression starting with an operator)indicates a description that is independent of the key-
board description for the device specified indevice_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 referencesto `%'. 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 ofthe possible bits in want or need. If a required com-
ponent has not been specified in the names structure(the corresponding field is expression "%", resulting
in the component values being taken from device_spec.
In addition, if load is True, the server modifies namesif necessary (again using a "%" entry) to ensure all of
the following fields are non-NULL: types, keycodes,
symbols, and compat. X Version 11 Last change: libX11 1.3.5 3XKB FUNCTIONS XkbGetKeyboardByName(3x11)
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 theserver must be able to resolve in order for XkbGetKey-
boardByName to succeed; if any of the components speci-
fied in need cannot be successfully resolved, XkbGet-
KeyboardByName fails. want specifies a set of keyboard components that theserver should attempt to resolve, but that are not man-
datory. If the server is unable to resolve any of thesecomponents, 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 keyboarddescription for device_spec to match the result of the
keyboard description just built. If load is False, theserver's description for device device_spec is not
updated. In all cases, the parts specified by want andneed from the just-built keyboard description are
returned.The names structure in an XkbDescRec keyboard descrip-
tion 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 X Version 11 Last change: libX11 1.3.5 4XKB FUNCTIONS XkbGetKeyboardByName(3x11)
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.typesmap.types[*].lvl_names[*]
names.compat names.vmods names.indicators names.groupsnames.radio_groups
names.phys_symbols
There is no way to determine which components specified in want (but not in need) were actually fetched, otherthan breaking the call into successive calls to XkbGet-
KeyboardByName 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 descrip-
tion and waits for the reply. If successful, the returnvalue 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 */
X Version 11 Last change: libX11 1.3.5 5XKB FUNCTIONS XkbGetKeyboardByName(3x11)
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 flags may yield unpredictableresults. The device_spec field specifies the device identif-
ier 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 key-
code 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 available in the server or an argument has correct type and range, but is otherwise invalidSEE ALSO
XkbListComponents(3x11) X Version 11 Last change: libX11 1.3.5 6XKB FUNCTIONS XkbGetKeyboardByName(3x11)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | x11/library/libx11 ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | See XInitThreads(3X11) |
|_____________________________|_____________________________|
X Version 11 Last change: libX11 1.3.5 7