1<?xml version="1.0" encoding="UTF-8" ?> 2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> 4<chapter id='Data_Structures'> 5<title>Data Structures</title> 6 7<para> 8An Xkb keyboard description consists of a variety of data structures, each of 9which describes some aspect of the keyboard. Although each data structure has 10its own peculiarities, there are a number of features common to nearly all Xkb 11structures. This chapter describes these common features and techniques for 12manipulating them. 13</para> 14 15 16<para> 17Many Xkb data structures are interdependent; changing a field in one might 18require changes to others. As an additional complication, some Xkb library 19functions allocate related components as a group to reduce fragmentation and 20allocator overhead. In these cases, simply allocating and freeing fields of Xkb 21structures might corrupt program memory. Creating and destroying such 22structures or keeping them properly synchronized during editing is complicated 23and error prone. 24</para> 25 26 27<para> 28Xkb provides functions and macros to allocate and free all major data 29structures. You should use them instead of allocating and freeing the 30structures yourself. 31</para> 32 33<sect1 id='Allocating_Xkb_Data_Structures'> 34<title>Allocating Xkb Data Structures</title> 35 36<para> 37Xkb provides functions, known as allocators, to create and initialize Xkb data 38structures. In most situations, the Xkb functions that read a keyboard 39description from the server call these allocators automatically. As a result, 40you will seldom have to directly allocate or initialize Xkb data structures. 41</para> 42 43 44<para> 45However, if you need to enlarge an existing structure or construct a keyboard 46definition from scratch, you may need to allocate and initialize Xkb data 47structures directly. Each major Xkb data structure has its own unique 48allocator. The allocator functions share common features: allocator functions 49for structures with optional components take as an input argument a mask of 50subcomponents to be allocated. Allocators for data structures containing 51variable-length data take an argument specifying the initial length of the data. 52</para> 53 54 55<para> 56You may call an allocator to change the size of the space allocated for 57variable-length data. When you call an allocator with an existing data 58structure as a parameter, the allocator does not change the data in any of the 59fields, with one exception: variable-length data might be moved. The allocator 60resizes the allocated memory if the current size is too small. This normally 61involves allocating new memory, copying existing data to the newly allocated 62memory, and freeing the original memory. This possible reallocation is 63important to note because local variables pointing into Xkb data structures 64might be invalidated by calls to allocator functions. 65</para> 66 67</sect1> 68<sect1 id='Adding_Data_and_Editing_Data_Structures'> 69<title>Adding Data and Editing Data Structures</title> 70 71<para> 72You should edit most data structures via the Xkb-supplied helper functions and 73macros, although a few data structures can be edited directly. The helper 74functions and macros make sure everything is initialized and interdependent 75values are properly updated for those Xkb structures that have 76interdependencies. As a general rule, if there is a helper function or macro to 77edit the data structure, use it. For example, increasing the width of a type 78requires you to resize every key that uses that type. This is complicated and 79ugly, which is why there’s an 80<function>XkbResizeKeyType</function> 81function. 82</para> 83 84 85<para> 86Many Xkb data structures have arrays whose size is reported by two fields. The 87first field, whose name is usually prefixed by 88<emphasis>sz_</emphasis>, 89represents the total number of elements that can be stored in the array. The 90second field, whose name is usually prefixed by 91<emphasis>num_</emphasis>, 92specifies the number of elements currently stored there. These arrays 93typically represent data whose total size cannot always be determined when the 94array is created. In these instances, the usual way to allocate space and add 95data is as follows: 96</para> 97 98<itemizedlist> 99 <listitem> 100 <para> 101Call the allocator function with some arbitrary size, as a hint. 102 </para> 103 </listitem> 104 <listitem> 105 <para> 106For those arrays that have an 107<function>Xkb...Add...</function> 108function, call it each time you want to add new data to the array. The 109function expands the array if necessary. 110 </para> 111 </listitem> 112</itemizedlist> 113 114<para> 115For example, call: 116 117<programlisting> 118XkbAllocGeomShapes(geom,4) 119</programlisting> 120 121to say <quote>I’ll need space for four new shapes in this geometry.</quote> 122This makes sure that 123<structfield>sz_shapes</structfield> 124− 125<structfield>num_shapes</structfield> 126>= 4, and resizes the shapes array if it isn’t. If this function 127succeeds, you are guaranteed to have space for the number of shapes you need. 128</para> 129 130 131<para> 132When you call an editing function for a structure, you do not need to check for 133space, because the function automatically checks the 134<emphasis>sz_</emphasis> 135and 136<emphasis>num_</emphasis> 137fields of the array, resizes the array if necessary, adds the entry to the 138array, and then updates the 139<emphasis>num_</emphasis> 140field. 141</para> 142 143 144</sect1> 145<sect1 id='Making_Changes_to_the_Servers_Keyboard_Description'> 146<title>Making Changes to the Server’s Keyboard Description</title> 147 148<para> 149In Xkb, as in the core protocol, the client and server have independent copies 150of the data structures that describe the keyboard. The recommended way to 151change some aspect of the keyboard mapping in the X server is to edit a local 152copy of the Xkb keyboard description and then send only the changes to the X 153server. This method helps eliminate the need to transfer the entire keyboard 154description or even an entire data structure for only minor changes. 155</para> 156 157 158<para> 159To help you keep track of the changes you make to a local copy of the keyboard 160description, Xkb provides separate special 161<firstterm>changes</firstterm> 162<indexterm significance="preferred" zone="Making_Changes_to_the_Servers_Keyboard_Description"> 163<primary>changes data structures</primary></indexterm> 164data structures for each major Xkb data structure. These data structures do 165not contain the actual changed values: they only indicate the changes that have 166been made to the structures that actually describe the keyboard. 167</para> 168 169 170<para> 171When you wish to change the keyboard description in the server, you first 172modify a local copy of the keyboard description and then flag the modifications 173in an appropriate changes data structure. When you finish editing the local 174copy of the keyboard description, you pass your modified version of the 175keyboard description and the modified changes data structure to an Xkb 176function. This function uses the modified keyboard description and changes 177structure to pass only the changed information to the server. Note that 178modifying the keyboard description but not setting the appropriate flags in the 179changes data structure causes indeterminate behavior. 180</para> 181 182 183</sect1> 184<sect1 id='Tracking_Keyboard_Changes_in_the_Server'> 185<title>Tracking Keyboard Changes in the Server</title> 186 187<para> 188The server reports all changes in its keyboard description to any interested 189clients via special Xkb events. Just as clients use special changes data 190structures to change the keyboard description in the server, the server uses 191special changes data structures to tell a client what changed in the server’s 192keyboard description. 193</para> 194 195 196<para> 197Unlike clients, however, the server does not always pass the new values when it 198reports changes to its copy of the keyboard description. Instead, the server 199only passes a changes data structure when it reports changes to its keyboard 200description. This is done for efficiency reasons — some clients do not always 201need to update their copy of the keyboard description with every report from 202the server. 203</para> 204 205 206<para> 207When your client application receives a report from the server indicating the 208keyboard description has changed, you can determine the set of changes by 209passing the event to an Xkb function that <quote>notes</quote> event 210information in the corresponding changes data structure. These 211<quote>note changes</quote> functions are 212defined for all major Xkb components, and their names have the form 213<function>XkbNote<replaceable>{Component}</replaceable>Changes</function>, 214where 215<replaceable>Component</replaceable> 216is the name of a major Xkb component such as 217<literal>Map</literal> 218or 219<literal>Names</literal>. 220When you want to copy these changes from the server into a local copy of the 221keyboard description, use the corresponding 222<function>XkbGet<replaceable>{Component}</replaceable>Changes</function> 223function, 224passing it the changes structure. The function then retrieves only the changed 225structures from the server and copies the modified pieces into the local 226keyboard description. 227</para> 228 229</sect1> 230<sect1 id='Freeing_Data_Structures'> 231<title>Freeing Data Structures</title> 232 233<para> 234For the same reasons you should not directly use 235<function>malloc</function> 236to allocate Xkb data structures, you should not free Xkb data structures or 237components directly using 238<function>free</function> 239or 240<function>Xfree</function>. 241Xkb provides functions to free the various data structures and their 242components. Always use the free functions supplied by Xkb. There is no 243guarantee that any particular field can be safely freed by 244<function>free</function> 245or 246<function>Xfree</function>. 247</para> 248</sect1> 249</chapter> 250