An Xkb keyboard description consists of a variety of data structures, each of which describes some aspect of the keyboard. Although each data structure has its own peculiarities, there are a number of features common to nearly all Xkb structures. This chapter describes these common features and techniques for manipulating them. Many Xkb data structures are interdependent; changing a field in one might require changes to others. As an additional complication, some Xkb library functions allocate related components as a group to reduce fragmentation and allocator overhead. In these cases, simply allocating and freeing fields of Xkb structures might corrupt program memory. Creating and destroying such structures or keeping them properly synchronized during editing is complicated and error prone. Xkb provides functions and macros to allocate and free all major data structures. You should use them instead of allocating and freeing the structures yourself. Xkb provides functions, known as allocators, to create and initialize Xkb data structures. In most situations, the Xkb functions that read a keyboard description from the server call these allocators automatically. As a result, you will seldom have to directly allocate or initialize Xkb data structures. However, if you need to enlarge an existing structure or construct a keyboard definition from scratch, you may need to allocate and initialize Xkb data structures directly. Each major Xkb data structure has its own unique allocator. The allocator functions share common features: allocator functions for structures with optional components take as an input argument a mask of subcomponents to be allocated. Allocators for data structures containing variable-length data take an argument specifying the initial length of the data. You may call an allocator to change the size of the space allocated for variable-length data. When you call an allocator with an existing data structure as a parameter, the allocator does not change the data in any of the fields, with one exception: variable-length data might be moved. The allocator resizes the allocated memory if the current size is too small. This normally involves allocating new memory, copying existing data to the newly allocated memory, and freeing the original memory. This possible reallocation is important to note because local variables pointing into Xkb data structures might be invalidated by calls to allocator functions. You should edit most data structures via the Xkb-supplied helper functions and macros, although a few data structures can be edited directly. The helper functions and macros make sure everything is initialized and interdependent values are properly updated for those Xkb structures that have interdependencies. As a general rule, if there is a helper function or macro to edit the data structure, use it. For example, increasing the width of a type requires you to resize every key that uses that type. This is complicated and ugly, which is why there’s an XkbResizeKeyType function. Many Xkb data structures have arrays whose size is reported by two fields. The first field, whose name is usually prefixed by sz_, represents the total number of elements that can be stored in the array. The second field, whose name is usually prefixed by num_, specifies the number of elements currently stored there. These arrays typically represent data whose total size cannot always be determined when the array is created. In these instances, the usual way to allocate space and add data is as follows: Call the allocator function with some arbitrary size, as a hint. For those arrays that have an Xkb...Add... function, call it each time you want to add new data to the array. The function expands the array if necessary. For example, call: XkbAllocGeomShapes(geom,4) to say I’ll need space for four new shapes in this geometry. This makes sure that sz_shapes − num_shapes >= 4, and resizes the shapes array if it isn’t. If this function succeeds, you are guaranteed to have space for the number of shapes you need. When you call an editing function for a structure, you do not need to check for space, because the function automatically checks the sz_ and num_ fields of the array, resizes the array if necessary, adds the entry to the array, and then updates the num_ field. In Xkb, as in the core protocol, the client and server have independent copies of the data structures that describe the keyboard. The recommended way to change some aspect of the keyboard mapping in the X server is to edit a local copy of the Xkb keyboard description and then send only the changes to the X server. This method helps eliminate the need to transfer the entire keyboard description or even an entire data structure for only minor changes. To help you keep track of the changes you make to a local copy of the keyboard description, Xkb provides separate special changes changes data structures data structures for each major Xkb data structure. These data structures do not contain the actual changed values: they only indicate the changes that have been made to the structures that actually describe the keyboard. When you wish to change the keyboard description in the server, you first modify a local copy of the keyboard description and then flag the modifications in an appropriate changes data structure. When you finish editing the local copy of the keyboard description, you pass your modified version of the keyboard description and the modified changes data structure to an Xkb function. This function uses the modified keyboard description and changes structure to pass only the changed information to the server. Note that modifying the keyboard description but not setting the appropriate flags in the changes data structure causes indeterminate behavior. The server reports all changes in its keyboard description to any interested clients via special Xkb events. Just as clients use special changes data structures to change the keyboard description in the server, the server uses special changes data structures to tell a client what changed in the server’s keyboard description. Unlike clients, however, the server does not always pass the new values when it reports changes to its copy of the keyboard description. Instead, the server only passes a changes data structure when it reports changes to its keyboard description. This is done for efficiency reasons — some clients do not always need to update their copy of the keyboard description with every report from the server. When your client application receives a report from the server indicating the keyboard description has changed, you can determine the set of changes by passing the event to an Xkb function that notes event information in the corresponding changes data structure. These note changes functions are defined for all major Xkb components, and their names have the form XkbNote{Component}Changes, where Component is the name of a major Xkb component such as Map or Names. When you want to copy these changes from the server into a local copy of the keyboard description, use the corresponding XkbGet{Component}Changes function, passing it the changes structure. The function then retrieves only the changed structures from the server and copies the modified pieces into the local keyboard description. For the same reasons you should not directly use malloc to allocate Xkb data structures, you should not free Xkb data structures or components directly using free or Xfree. Xkb provides functions to free the various data structures and their components. Always use the free functions supplied by Xkb. There is no guarantee that any particular field can be safely freed by free or Xfree.