From 16b53769eba7d5d8249a217aa29287d72b7713c2 Mon Sep 17 00:00:00 2001 From: marha Date: Wed, 14 Sep 2011 14:23:18 +0200 Subject: libX11 git update 14 sep 2011 --- libX11/specs/XKB/ch06.xml | 413 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 413 insertions(+) create mode 100644 libX11/specs/XKB/ch06.xml (limited to 'libX11/specs/XKB/ch06.xml') diff --git a/libX11/specs/XKB/ch06.xml b/libX11/specs/XKB/ch06.xml new file mode 100644 index 000000000..3bd77fab2 --- /dev/null +++ b/libX11/specs/XKB/ch06.xml @@ -0,0 +1,413 @@ + +Complete Keyboard Description + + +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 XkbDescRec Structure + + +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. + + + + +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 +. + + + +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. + + + +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) + + + +
+ + + +Obtaining a Keyboard Description from the Server + + +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). + + + + + +Tracking Changes to the Keyboard Description in the Server + + +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. + + + + + +Allocating and Freeing a 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. + + + + -- cgit v1.2.3