DocsTable of Contents
The complete Xkb description for a keyboard device is accessed using a single structure containing pointers to major Xkb components. This chapter describes this single structure and provides references to other sections of this document that discuss the major Xkb components in detail.
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;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.
The other fields specify structure components of the keyboard description and are described in detail in other sections of this document. Table 6.1 identifies the subsequent sections of this document that discuss the individual components of the XkbDescRec .
Table 6.1. XkbDescRec Component References
| XkbDescRec Field | For more info |
|---|---|
| ctrls | Chapter 10 |
| server | Chapter 16 |
| map | Chapter 15 |
| indicators | Chapter 8 |
| names | Chapter 18 |
| compat | Chapter 17 |
| geom | Chapter 13 |
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 6.2.
Table 6.2. 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) |
To retrieve one or more components of a keyboard device description, use XkbGetKeyboard (see also XkbGetKeyboardbyName ).
| XkbDescPtr XkbGetKeyboard ( display, which, device_spec ) |
| Display * display ; /* connection to X server */ |
| unsigned int which ; /* mask indicating components to return */ |
| unsigned int device_spec ; /* device for which to fetch description, or XkbUseCoreKbd */ |
XkbGetKeyboard allocates and returns a pointer to a keyboard description. It queries the server for those components specified in the which parameter for device device_spec and copies the results to the XkbDescRec it allocated. The remaining fields in the keyboard description are set to NULL . The valid masks for which are those listed in Table 6.2.
XkbGetKeyboard can generate BadAlloc protocol errors.
To free the returned keyboard description, use XkbFreeKeyboard (see section 6.4).
The server can generate events whenever its copy of the keyboard description for a device changes. Refer to section 14.4 for detailed information on tracking changes to the keyboard description.
Applications seldom need to directly allocate a keyboard description; calling XkbGetKeyboard usually suffices. In the event you need to create a keyboard description from scratch, however, use XkbAllocKeyboard rather than directly calling malloc or Xmalloc .
| XkbDescRec * XkbAllocKeyboard (void) |
If XkbAllocKeyboard fails to allocate the keyboard description, it returns NULL . Otherwise, it returns a pointer to an empty keyboard description structure. The device_spec field will have been initialized to XkbUseCoreKbd . You may then either fill in the structure components or use Xkb functions to obtain values for the structure components from a keyboard device.
To destroy either an entire an XkbDescRec or just some of its members, use XkbFreeKeyboard.
| void XkbFreeKeyboard (xkb, which, free_all ) |
| XkbDescPtr xkb ; /* keyboard description with components to free */ |
| unsigned int which ; /* mask selecting components to free */ |
| Bool free_all ; /* True => free all components and xkb */ |
XkbFreeKeyboard frees the components of xkb specified by which and sets the corresponding values to NULL . If free_all is True , XkbFreeKeyboard frees every non- NULL component of xkb and then frees the xkb structure itself.