specs/XKB/ch06.xml

   1 <chapter id='Complete_Keyboard_Description'>
   2 <title>Complete Keyboard Description</title>
   3
   4 <para>
   5 The complete Xkb description for a keyboard device is accessed using a single
   6 structure containing pointers to major Xkb components. This chapter describes
   7 this single structure and provides references to other sections of this
   8 document that discuss the major Xkb components in detail.
   9 </para>
  10
  11 <sect1 id='The_XkbDescRec_Structure'>
  12 <title>The XkbDescRec Structure</title>
  13
  14 <para>
  15 The complete description of an Xkb keyboard is given by an <emphasis>
  16 XkbDescRec</emphasis>
  17 . The component structures in the <emphasis>
  18 XkbDescRec</emphasis>
  19  represent the major Xkb components outlined in Figure 1.1. <!-- xref -->
  20 </para>
  21
  22 <para><programlisting>
  23 typedef struct {
  24       struct _XDisplay *                  display;            /* connection to
  25 X server */
  26       unsigned short                  flags;            /* private to Xkb, do
  27 not modify */
  28       unsigned short                  device_spec;            /* device of
  29 interest */
  30       KeyCode                  min_key_code;            /* minimum keycode for
  31 device */
  32       KeyCode                  max_key_code;            /* maximum keycode for
  33 device */
  34       XkbControlsPtr                  ctrls;            /* controls */
  35       XkbServerMapPtr                  server;            /* server keymap */
  36       XkbClientMapPtr                  map;            /* client keymap */
  37       XkbIndicatorPtr                  indicators;            /* indicator map
  38 */
  39       XkbNamesPtr                  names;            /* names for all
  40 components */
  41       XkbCompatMapPtr                  compat;            /* compatibility map
  42 */
  43       XkbGeometryPtr                  geom;            /* physical geometry of
  44 keyboard */
  45 } <emphasis>
  46 XkbDescRec</emphasis>
  47 , *XkbDescPtr;
  48 </programlisting></para>
  49
  50 <para>
  51 The <emphasis>
  52 display</emphasis>
  53  field points to an X display structure. The <emphasis>
  54 flags</emphasis>
  55  field is private to the library: modifying <emphasis>
  56 flags</emphasis>
  57  may yield unpredictable results. The <emphasis>
  58 device_spec</emphasis>
  59  field specifies the device identifier of the keyboard input device, or
  60 <emphasis>
  61 XkbUseCoreKeyboard</emphasis>
  62 , which specifies the core keyboard device. The <emphasis>
  63 min_key_code</emphasis>
  64  and <emphasis>
  65 max_key_code</emphasis>
  66  fields specify the least and greatest keycode that can be returned by the
  67 keyboard.
  68 </para>
  69
  70
  71 <para>
  72 The other fields specify structure components of the keyboard description and
  73 are described in detail in other sections of this document. Table 6.1
  74 identifies the subsequent sections of this document that discuss the individual
  75 components of the <emphasis>
  76 XkbDescRec</emphasis>
  77 .
  78 </para>
  79
  80 <table frame='topbot'>
  81 <title>XkbDescRec Component References</title>
  82 <?dbfo keep-together="always" ?>
  83 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
  84 <colspec colname='c1' colwidth='1.0*'/>
  85 <colspec colname='c2' colwidth='2.0*'/>
  86 <thead>
  87 <row rowsep='1'>
  88   <entry>XkbDescRec Field</entry>
  89   <entry>For more info</entry>
  90 </row>
  91 </thead>
  92 <tbody>
  93 <row>
  94     <entry>ctrls</entry>
  95     <entry>Chapter 10</entry>
  96 </row>
  97 <row>
  98     <entry>server</entry>
  99     <entry>Chapter 16</entry>
 100 </row>
 101 <row>
 102     <entry>map</entry>
 103     <entry>Chapter 15</entry>
 104 </row>
 105 <row>
 106     <entry>indicators</entry>
 107     <entry>Chapter 8</entry>
 108 </row>
 109 <row>
 110     <entry>names</entry>
 111     <entry>Chapter 18</entry>
 112 </row>
 113 <row>
 114     <entry>compat</entry>
 115     <entry>Chapter 17</entry>
 116 </row>
 117 <row>
 118     <entry>geom</entry>
 119     <entry>Chapter 13</entry>
 120   </row>
 121 </tbody>
 122 </tgroup>
 123 </table>
 124
 125 <para>
 126 Each structure component has a corresponding mask bit that is used in function
 127 calls to indicate that the structure should be manipulated in some manner, such
 128 as allocating it or freeing it. These masks and their relationships to the
 129 fields in the <emphasis>
 130 XkbDescRec</emphasis>
 131  are shown in Table 6.2. <!-- xref -->
 132 </para>
 133
 134 <table frame='topbot'>
 135 <title>Mask Bits for XkbDescRec</title>
 136 <?dbfo keep-together="always" ?>
 137 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 138 <colspec colname='c1' colwidth='1.0*'/>
 139 <colspec colname='c2' colwidth='1.0*'/>
 140 <colspec colname='c3' colwidth='1.0*'/>
 141 <thead>
 142 <row rowsep='1'>
 143   <entry>Mask Bit</entry>
 144   <entry>XkbDescRec Field</entry>
 145   <entry>Value</entry>
 146 </row>
 147 </thead>
 148 <tbody>
 149 <row>
 150     <entry>XkbControlsMask</entry>
 151     <entry>ctrls</entry>
 152     <entry>(1L&lt;&lt;0)</entry>
 153 </row>
 154 <row>
 155     <entry>XkbServerMapMask</entry>
 156     <entry>server</entry>
 157     <entry>(1L&lt;&lt;1)</entry>
 158 </row>
 159 <row>
 160     <entry>XkbIClientMapMask</entry>
 161     <entry>map</entry>
 162     <entry>(1L&lt;&lt;2)</entry>
 163 </row>
 164 <row>
 165     <entry>XkbIndicatorMapMask</entry>
 166     <entry>indicators</entry>
 167     <entry>(1L&lt;&lt;3)</entry>
 168 </row>
 169 <row>
 170     <entry>XkbNamesMask</entry>
 171     <entry>names</entry>
 172     <entry>(1L&lt;&lt;4)</entry>
 173 </row>
 174 <row>
 175     <entry>XkbCompatMapMask</entry>
 176     <entry>compat</entry>
 177     <entry>(1L&lt;&lt;5)</entry>
 178 </row>
 179 <row>
 180     <entry>XkbGeometryMask</entry>
 181     <entry>geom</entry>
 182     <entry>(1L&lt;&lt;6)</entry>
 183 </row>
 184 <row>
 185     <entry>XkbAllComponentsMask</entry>
 186     <entry>All Fields</entry>
 187     <entry>(0x7f)</entry>
 188   </row>
 189 </tbody>
 190 </tgroup>
 191 </table>
 192
 193 </sect1>
 194 <sect1 id='Obtaining_a_Keyboard_Description_from_the_Server'>
 195 <title>Obtaining a Keyboard Description from the Server</title>
 196
 197 <para>
 198 To retrieve one or more components of a keyboard device description, use
 199 <emphasis>
 200 XkbGetKeyboard</emphasis>
 201  (see also <emphasis>
 202 XkbGetKeyboardbyName</emphasis>
 203 ).
 204 </para>
 205
 206 <informaltable frame='none'>
 207 <?dbfo keep-together="always" ?>
 208 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 209 <colspec colname='c1' colwidth='1.0*'/>
 210 <tbody>
 211   <row>
 212     <entry role='functiondecl'>
 213 XkbDescPtr <emphasis>
 214 XkbGetKeyboard</emphasis>
 215 (<emphasis>
 216 display, which, device_spec</emphasis>
 217 )
 218     </entry>
 219   </row>
 220   <row>
 221     <entry role='functionargdecl'>
 222 Display * <emphasis>
 223       display</emphasis>
 224 ;            /* connection to X server */
 225     </entry>
 226   </row>
 227   <row>
 228     <entry role='functionargdecl'>
 229 unsigned int      <emphasis>
 230 which</emphasis>
 231 ;            /* mask indicating components to return */
 232     </entry>
 233   </row>
 234   <row>
 235     <entry role='functionargdecl'>
 236 unsigned int<emphasis>
 237       device_spec</emphasis>
 238 ;            /* device for which to fetch description, or <emphasis>
 239 XkbUseCoreKbd</emphasis>
 240  */
 241     </entry>
 242 </row>
 243 </tbody>
 244 </tgroup>
 245 </informaltable>
 246
 247 <para>
 248 <emphasis>
 249 XkbGetKeyboard </emphasis>
 250 allocates and returns a pointer to a keyboard description. It queries the
 251 server for those components specified in the <emphasis>
 252 which</emphasis>
 253  parameter for device <emphasis>
 254 device_spec</emphasis>
 255  and copies the results to the <emphasis>
 256 XkbDescRec</emphasis>
 257  it allocated. The remaining fields in the keyboard description are set to
 258 <emphasis>
 259 NULL</emphasis>
 260 . The valid masks for <emphasis>
 261 which</emphasis>
 262  are those listed in Table 6.2. <!-- xref -->
 263 </para>
 264
 265
 266 <para>
 267 <emphasis>
 268 XkbGetKeyboard</emphasis>
 269  can generate <emphasis>
 270 BadAlloc</emphasis>
 271  protocol errors.
 272 </para>
 273
 274
 275 <para>
 276 To free the returned keyboard description, use <emphasis>
 277 XkbFreeKeyboard</emphasis>
 278  (see section 6.4). <!-- xref -->
 279 </para>
 280
 281
 282 </sect1>
 283 <sect1 id='Tracking_Changes_to_the_Keyboard_Description_in_the_Server'>
 284 <title>Tracking Changes to the Keyboard Description in the Server</title>
 285
 286 <para>
 287 The server can generate events whenever its copy of the keyboard description
 288 for a device changes. Refer to section 14.4 for detailed information on  <!-- xref -->
 289 tracking changes to the keyboard description.
 290 </para>
 291
 292
 293 </sect1>
 294 <sect1 id='Allocating_and_Freeing_a_Keyboard_Description'>
 295 <title>Allocating and Freeing a Keyboard Description</title>
 296
 297 <para>
 298 Applications seldom need to directly allocate a keyboard description; calling
 299 <emphasis>
 300 XkbGetKeyboard</emphasis>
 301  usually suffices. In the event you need to create a keyboard description from
 302 scratch, however, use <emphasis>
 303 XkbAllocKeyboard</emphasis>
 304  rather than directly calling <emphasis>
 305 malloc </emphasis>
 306 or <emphasis>
 307 Xmalloc</emphasis>
 308 .
 309 </para>
 310
 311 <informaltable frame='none'>
 312 <?dbfo keep-together="always" ?>
 313 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 314 <colspec colname='c1' colwidth='1.0*'/>
 315 <tbody>
 316   <row>
 317     <entry role='functiondecl'>
 318 XkbDescRec * <emphasis>
 319 XkbAllocKeyboard</emphasis>
 320 (void)
 321     </entry>
 322   </row>
 323 </tbody>
 324 </tgroup>
 325 </informaltable>
 326
 327 <para>
 328 If <emphasis>
 329 XkbAllocKeyboard</emphasis>
 330  fails to allocate the keyboard description, it returns <emphasis>
 331 NULL</emphasis>
 332 . Otherwise, it returns a pointer to an empty keyboard description structure.
 333 The <emphasis>
 334 device_spec</emphasis>
 335  field will have been initialized to <emphasis>
 336 XkbUseCoreKbd</emphasis>
 337 . You may then either fill in the structure components or use Xkb functions to
 338 obtain values for the structure components from a keyboard device.
 339 </para>
 340
 341
 342 <para>
 343 To destroy either an entire an <emphasis>
 344 XkbDescRec</emphasis>
 345  or just some of its members, use <emphasis>
 346 XkbFreeKeyboard.</emphasis>
 347 </para>
 348
 349
 350 <informaltable frame='none'>
 351 <?dbfo keep-together="always" ?>
 352 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 353 <colspec colname='c1' colwidth='1.0*'/>
 354 <tbody>
 355   <row>
 356     <entry role='functiondecl'>
 357 void <emphasis>
 358 XkbFreeKeyboard</emphasis>
 359 <emphasis>
 360 (xkb, which, free_all</emphasis>
 361 )
 362     </entry>
 363   </row>
 364   <row>
 365     <entry role='functionargdecl'>
 366 XkbDescPtr <emphasis>
 367             xkb</emphasis>
 368 ;            /* keyboard description with components to free */
 369     </entry>
 370   </row>
 371   <row>
 372     <entry role='functionargdecl'>
 373 unsigned int      <emphasis>
 374       which</emphasis>
 375 ;            /* mask selecting components to free */
 376     </entry>
 377   </row>
 378   <row>
 379     <entry role='functionargdecl'>
 380 Bool <emphasis>
 381             free_all</emphasis>
 382 ;            /* <emphasis>
 383 True</emphasis>
 384  =&gt; free all components and <emphasis>
 385 xkb</emphasis>
 386  */
 387     </entry>
 388 </row>
 389 </tbody>
 390 </tgroup>
 391 </informaltable>
 392
 393 <para>
 394 <emphasis>
 395 XkbFreeKeyboard</emphasis>
 396  frees the components of <emphasis>
 397 xkb</emphasis>
 398  specified by <emphasis>
 399 which</emphasis>
 400  and sets the corresponding values to <emphasis>
 401 NULL</emphasis>
 402 . If <emphasis>
 403 free_all</emphasis>
 404  is <emphasis>
 405 True</emphasis>
 406 , <emphasis>
 407 XkbFreeKeyboard</emphasis>
 408  frees every non-<emphasis>
 409 NULL</emphasis>
 410  component of <emphasis>
 411 xkb</emphasis>
 412  and then frees the <emphasis>
 413 xkb</emphasis>
 414  structure itself.
 415 </para>
 416
 417 </sect1>
 418 </chapter>