Table of Contents


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 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)


A compatible version of Xkb was not available in the server or an argument has correct type and range, but is otherwise invalid

See Also


Table of Contents