specs/XKB/ch13.xml

   1 <chapter id='Keyboard_Geometry'>
   2 <title>Keyboard Geometry</title>
   3
   4 <para>
   5 The Xkb description of a keyboard includes an optional keyboard geometry that
   6 describes the physical appearance of the keyboard. Keyboard geometry describes
   7 the shape, location, and color of all keyboard keys or other visible keyboard
   8 components such as indicators. The information contained in a keyboard geometry
   9 is sufficient to allow a client program to draw an accurate two-dimensional
  10 image of the keyboard.
  11 </para>
  12
  13
  14 <para>
  15 You can retrieve a keyboard geometry from an X server that supports Xkb, or you
  16 can allocate it from scratch and initialize it in a client program. The
  17 keyboard geometry need not have any correspondence with the physical keyboard
  18 that is connected to the X server.
  19 </para>
  20
  21
  22 <para>
  23 Geometry measurements are specified in mm/10 units. The origin (0,0) is in the
  24 top left corner of the keyboard image. A component’s own origin is also its
  25 upper left corner. In some cases a component needs to be drawn rotated. For
  26 example, a special keyboard may have a section of keys arranged in rows in a
  27 rectangular area, but the entire rectangle may not be in alignment with the
  28 rest of the keyboard, and instead, it is rotated from horizontal by 30<emphasis>
  29 o</emphasis>
  30 . Rotation for a geometry object is specified in 1/10 o increments about its
  31 origin. An example of a keyboard with rotated sections is shown in Figure 13.1.
  32 </para>
  33
  34 <mediaobject>
  35  <imageobject> <imagedata format="SVG" fileref="XKBlib-7.svg"/>
  36  </imageobject>
  37 <caption>Rotated Keyboard Sections</caption>
  38 </mediaobject>
  39
  40
  41 <!-- <H5 CLASS="Figure">
  42 Rotated Keyboard Sections</H5>
  43 -->
  44
  45 <para>
  46 Some geometry components include a <emphasis>
  47 priority</emphasis>
  48 , which indicates the order in which overlapping objects should be drawn.
  49 Objects should be drawn in order from highest priority (0) to lowest (255).
  50 </para>
  51
  52
  53 <para>
  54 The keyboard geometry’s top-level description is stored in a <emphasis>
  55 XkbGeometryRec</emphasis>
  56  structure. This structure contains three types of information:
  57 </para>
  58
  59 <orderedlist>
  60   <listitem>
  61     <para>
  62 Lists of items, not used to draw the basic keyboard, but indexed by the
  63 geometry descriptions that comprise the entire keyboard geometry (colors,
  64 geometry properties, key aliases, shapes)
  65     </para>
  66   </listitem>
  67   <listitem>
  68     <para>
  69 A number of singleton items that describe the keyboard as a whole (keyboard
  70 name, width and height, a color for the keyboard as a whole, and a color for
  71 keyboard key labels)
  72     </para>
  73   </listitem>
  74   <listitem>
  75     <para>
  76 A list of the keyboard’s sections and nonkey doodads
  77     </para>
  78   </listitem>
  79 </orderedlist>
  80
  81 <para>
  82 The top-level geometry is described in more detail in the following.
  83 </para>
  84
  85
  86 <para>
  87 The lists of items used by components of the keyboard geometry description is
  88 as follows:
  89 </para>
  90
  91 <itemizedlist>
  92 <listitem>
  93   <para>
  94 The top-level keyboard geometry description includes a list of up to <emphasis>
  95 MaxColors</emphasis>
  96  (32) <emphasis>
  97 color names</emphasis>
  98 . A color name is a string whose interpretation is not specified by Xkb. The
  99 <emphasis>
 100 XkbColorRec</emphasis>
 101  structure provides a field for this name as well as a pixel field. The pixel
 102 field is a convenient place for an application to store a pixel value or color
 103 definition, if it needs to. All other geometry data structures refer to colors
 104 using their indices in this global list.
 105   </para>
 106 </listitem>
 107 <listitem>
 108   <para>
 109 The top-level keyboard geometry description includes a list of <emphasis>
 110 geometry properties</emphasis>
 111 . A geometry property associates an arbitrary string with an equally arbitrary
 112 name. Geometry properties can be used to provide hints to programs that display
 113 images of keyboards, but they are not interpreted by Xkb. No other geometry
 114 structures refer to geometry properties. As an example of a possible use of
 115 <emphasis>
 116 properties</emphasis>
 117 , consider the pause/break key on most PC keyboards: the "break" symbol is
 118 usually on the front of the key and is often a different color. A program might
 119 set a property to:
 120   </para>
 121   <para>
 122 LBL_PAUS = "{Pause/top/black,Break/front/red}"
 123   </para>
 124   <para>
 125 and use the property information to draw the key with a front label as well as
 126 a top label.
 127   </para>
 128 </listitem>
 129 <listitem>
 130   <para>
 131 The top-level keyboard geometry description includes a list of <emphasis>
 132 key aliases</emphasis>
 133  (see Chapter 18). Key aliases allow the keyboard layout designer to assign
 134 multiple key names to a single key.
 135   </para>
 136 <note><para>Key aliases defined in the geometry component of a keyboard mapping
 137 override those defined in the keycodes component of the server database, which
 138 are stored in the <emphasis>
 139 XkbNamesRec</emphasis>
 140  (<emphasis>
 141 xkb-&gt;names</emphasis>
 142 ). Therefore, consider the key aliases defined by the geometry before
 143 considering key aliases supplied by the keycodes.</para></note>
 144 </listitem>
 145 <listitem>
 146   <para>
 147 The top-level keyboard geometry description includes a list of <emphasis>
 148 shapes</emphasis>
 149 ; other keyboard components refer to shapes by their index in this list. A
 150 shape consists of an arbitrary name of type Atom and one or more closed-polygon
 151 <emphasis>
 152 outlines</emphasis>
 153 . All points in an outline are specified relative to the origin of its
 154 enclosing shape, that is, whichever shape that contains this outline in its
 155 list of outlines. One outline is the primary outline. The primary outline is by
 156 default the first outline, or it can be optionally specified by the <emphasis>
 157 primary</emphasis>
 158  field in the <emphasis>
 159 XkbShapeRec</emphasis>
 160  structure. A keyboard display application can generate a simpler but still
 161 accurate keyboard image by displaying only the primary outlines for each shape.
 162 Nonrectangular keys must include a rectangular <emphasis>
 163 approximation</emphasis>
 164  as one of the outlines associated with the shape. The approximation is not
 165 normally displayed but can be used by very simple keyboard display applications
 166 to generate a recognizable but degraded image of the keyboard.
 167   </para>
 168 </listitem>
 169 </itemizedlist>
 170
 171 <para>
 172 The <emphasis>
 173 XkbGeometryRec</emphasis>
 174  top-level geometry description contains the following information that
 175 pertains to the keyboard as a whole:
 176 </para>
 177
 178 <itemizedlist>
 179 <listitem>
 180   <para>
 181 A <emphasis>
 182 keyboard symbolic name</emphasis>
 183  of type Atom to help users identify the keyboard.
 184   </para>
 185 </listitem>
 186 <listitem>
 187   <para>
 188 The <emphasis>
 189 width</emphasis>
 190  and <emphasis>
 191 height</emphasis>
 192  of the keyboard, in mm/10. For nonrectangular keyboards, the width and height
 193 describe the smallest bounding box that encloses the outline of the keyboard.
 194   </para>
 195 </listitem>
 196 <listitem>
 197   <para>
 198 The<emphasis>
 199  base color</emphasis>
 200  of the keyboard is the predominant color on the keyboard and is used as the
 201 default color for any components whose color is not explicitly specified.
 202   </para>
 203 </listitem>
 204 <listitem>
 205   <para>
 206 The <emphasis>
 207 label color</emphasis>
 208  is the color used to draw the labels on most of the keyboard keys.
 209   </para>
 210 </listitem>
 211 <listitem>
 212   <para>
 213 The <emphasis>
 214 label font</emphasis>
 215  is a string that describes the font used to draw labels on most keys; label
 216 fonts are arbitrary strings, because Xkb does not specify the format or name
 217 space for font names.
 218   </para>
 219 </listitem>
 220 </itemizedlist>
 221
 222 <para>
 223 The keyboard is subdivided into named <emphasis>
 224 sections</emphasis>
 225  of related keys and doodads. The sections and doodads on the keyboard are
 226 listed in the <emphasis>
 227 XkbGeometryRec</emphasis>
 228  top-level keyboard geometry description. A section is composed of keys that
 229 are physically together and logically related. Figure 13.2 shows a keyboard
 230 that is divided into four sections. A <emphasis>
 231 doodad</emphasis>
 232  describes some visible aspect of the keyboard that is not a key and is not a
 233 section.
 234 </para>
 235
 236 <mediaobject>
 237  <imageobject> <imagedata format="SVG" fileref="XKBlib-8.svg"/>
 238  </imageobject>
 239 <caption>Keyboard with Four Sections</caption>
 240 </mediaobject>
 241
 242 <!--
 243 <H5 CLASS="Figure">
 244 Keyboard with Four Sections</H5>
 245 -->
 246
 247 <sect1 id='Shapes_and_Outlines'>
 248 <title>Shapes and Outlines</title>
 249
 250 <para>
 251 A <emphasis>
 252 shape</emphasis>
 253 , used to draw keyboard components and stored in a <emphasis>
 254 XkbShapeRec</emphasis>
 255  structure, has:
 256 </para>
 257
 258 <itemizedlist>
 259 <listitem>
 260   <para>
 261 An arbitrary name of type Atom.
 262   </para>
 263 </listitem>
 264 <listitem>
 265   <para>
 266 Bounds (two x and y coordinates) that describe the corners of a rectangle
 267 containing the shape’s top surface outline.
 268   </para>
 269 </listitem>
 270 <listitem>
 271   <para>
 272 A list of one or more outlines (described below).
 273   </para>
 274 </listitem>
 275 <listitem>
 276   <para>
 277 Optional pointers to a primary and an approximation outline (described below).
 278 If either of these pointers is <emphasis>
 279 NULL</emphasis>
 280 , the default primary/approximation outline is the first one in the list of
 281 outlines for the shape.
 282   </para>
 283 </listitem>
 284 </itemizedlist>
 285
 286 <para>
 287 An <emphasis>
 288 outline</emphasis>
 289 , stored in a <emphasis>
 290 XkbOutlineRec</emphasis>
 291  structure, is a list of one or more points that describes a single
 292 closed-polygon, as follows:
 293 </para>
 294
 295 <itemizedlist>
 296 <listitem>
 297   <para>
 298 A list with a single point describes a rectangle with one corner at the origin
 299 of the shape (0,0) and the opposite corner at the specified point.
 300   </para>
 301 </listitem>
 302 <listitem>
 303   <para>
 304 A list of two points describes a rectangle with one corner at the position
 305 specified by the first point and the opposite corner at the position specified
 306 by the second point.
 307   </para>
 308 </listitem>
 309 <listitem>
 310   <para>
 311 A list of three or more points describes an arbitrary polygon. If necessary,
 312 the polygon is automatically closed by connecting the last point in the list
 313 with the first.
 314   </para>
 315 </listitem>
 316 <listitem>
 317   <para>
 318 A nonzero value for the <emphasis>
 319 corner_radius</emphasis>
 320  field specifies that the corners of the polygon should be drawn as circles
 321 with the specified radius.
 322   </para>
 323 </listitem>
 324 </itemizedlist>
 325
 326 <para>
 327 All points in an outline are specified relative to the origin of the enclosing
 328 shape. Points in an outline may have negative values for the X and Y coordinate.
 329 </para>
 330
 331
 332 <para>
 333 One outline is the primary outline; a keyboard display application can generate
 334 a simple but still accurate keyboard image by displaying only the primary
 335 outlines for each shape. The default primary outline is the first in a
 336 shape’s list of outlines. If the <emphasis>
 337 primary</emphasis>
 338  field of the <emphasis>
 339 XkbShapeRec</emphasis>
 340  structure is not <emphasis>
 341 NULL</emphasis>
 342 , it points to the primary outline. A rectangular <emphasis>
 343 approximation</emphasis>
 344  must be included for nonrectangular keys as one of the outlines associated
 345 with the shape; the approximation is not normally displayed but can be used by
 346 very simple keyboard display applications to generate a recognizable but
 347 degraded image of the keyboard.
 348 </para>
 349
 350 </sect1>
 351 <sect1 id='Sections'>
 352 <title>Sections</title>
 353
 354 <para>
 355 As previously noted, a keyboard is subdivided into <emphasis>
 356 sections</emphasis>
 357  of related keys. Each section has its own coordinate system — if a section
 358 is rotated, the coordinates of any components within the section are
 359 interpreted relative to the edges that were on the top and left before
 360 rotation. The components that make up a section, stored in a <emphasis>
 361 XkbSectionRec</emphasis>
 362 , include:
 363 </para>
 364
 365 <itemizedlist>
 366 <listitem>
 367   <para>
 368 An arbitrary name of type Atom.
 369   </para>
 370 </listitem>
 371 <listitem>
 372   <para>
 373 A priority, to indicate drawing order. 0 is the highest priority, 255 the
 374 lowest.
 375   </para>
 376 </listitem>
 377 <listitem>
 378   <para>
 379 Origin of the section, relative to the origin of the keyboard.
 380   </para>
 381 </listitem>
 382 <listitem>
 383   <para>
 384 The width and height and the angle of rotation.
 385   </para>
 386 </listitem>
 387 <listitem>
 388   <para>
 389 A list of <emphasis>
 390 rows</emphasis>
 391 . A row is a list of horizontally or vertically adjacent keys. Horizontal rows
 392 parallel the (prerotation) top of the section, and vertical rows parallel the
 393 (prerotation) left of the section. All keys in a horizontal row share a common
 394 top coordinate; all keys in a vertical row share a left coordinate. Figure 13.3
 395 shows the alpha section from the keyboard shown in Figure 13.2, divided into
 396 rows. Rows and keys are defined below.
 397   </para>
 398 </listitem>
 399 </itemizedlist>
 400
 401 <mediaobject>
 402   <imageobject> <imagedata format="SVG" fileref="XKBlib-9.svg"/>
 403   </imageobject>
 404   <caption>Rows in a Section</caption>
 405 </mediaobject>
 406
 407
 408
 409 <!--
 410 <H5 CLASS="Figure">
 411 Rows in a Section</H5>
 412 -->
 413 <itemizedlist>
 414 <listitem>
 415   <para>
 416 An optional list of <emphasis>
 417 doodads</emphasis>
 418 ; any type of doodad can be enclosed within a section. Position and angle of
 419 rotation are relative to the origin and angle of rotation of the sections that
 420 contain them. Priority for doodads in a section is relative to the other
 421 components of the section, not to the keyboard as a whole.
 422   </para>
 423 </listitem>
 424 <listitem>
 425   <para>
 426 An optional <emphasis>
 427 overlay</emphasis>
 428  with a name of type Atom and a list of overlay rows (described below).
 429   </para>
 430 </listitem>
 431 <listitem>
 432   <para>
 433 Bounds (two x and y coordinates) that describe the corners of a rectangle
 434 containing the entire section.
 435   </para>
 436 </listitem>
 437 </itemizedlist>
 438 </sect1>
 439 <sect1 id='Rows_and_Keys'>
 440 <title>Rows and Keys</title>
 441
 442 <para>
 443 A row description (<emphasis>
 444 XkbRowRec</emphasis>
 445 ) consists of the coordinates of its origin relative to its enclosing section,
 446 a flag indicating whether the row is horizontal or vertical, and a list of keys
 447 in the row.
 448 </para>
 449
 450
 451 <para>
 452 A key description (<emphasis>
 453 XkbKeyRec</emphasis>
 454 ) consists of a key name, a shape, a key color, and a gap. The key name should
 455 correspond to one of the keys named in the keyboard names description, the
 456 shape specifies the appearance of the key, and the key color specifies the
 457 color of the key (not the label on the key; the label color is stored in the
 458 <emphasis>
 459 XkbGeometryRec</emphasis>
 460 ). Keys are normally drawn immediately adjacent to one another from left to
 461 right (or top to bottom) within a row. The gap field specifies the distance
 462 between a key and its predecessor.
 463 </para>
 464
 465
 466 </sect1>
 467 <sect1 id='Doodads'>
 468 <title>Doodads</title>
 469
 470 <para>
 471 Doodads can be global to the keyboard or part of a section. Doodads have
 472 symbolic names of arbitrary length. The only doodad name whose interpretation
 473 is specified by Xkb is "Edges", which, if present, describes the outline of the
 474 entire keyboard.
 475 </para>
 476
 477
 478 <para>
 479 Each doodad’s origin is stored in fields named <emphasis>
 480 left</emphasis>
 481  and <emphasis>
 482 top</emphasis>
 483 , which are the coordinates of the doodad’s origin relative to its enclosing
 484 object, whether it be a section or the top-level keyboard. The priority for
 485 doodads that are listed in the top-level geometry is relative to the other
 486 doodads listed in the top-level geometry and the sections listed in the
 487 top-level geometry. The priority for doodads listed in a section are relative
 488 to the other components of the section. Each doodad is stored in a structure
 489 with a <emphasis>
 490 type</emphasis>
 491  field, which specifies the type of doodad.
 492 </para>
 493
 494 <para>
 495 Xkb supports five types of doodads:
 496 </para>
 497
 498 <itemizedlist>
 499 <listitem>
 500   <para>
 501 An <emphasis>
 502 indicator doodad</emphasis>
 503  describes one of the physical keyboard indicators. Indicator doodads specify
 504 the shape of the indicator, the indicator color when it is lit (<emphasis>
 505 on_color</emphasis>
 506 ) and the indicator color when it is dark (<emphasis>
 507 off_color</emphasis>
 508 ).
 509   </para>
 510 </listitem>
 511 <listitem>
 512   <para>
 513 An <emphasis>
 514 outline doodad</emphasis>
 515  describes some aspect of the keyboard to be drawn as one or more hollow,
 516 closed polygons. Outline doodads specify the shape, color, and angle of
 517 rotation about the doodad origin at which they should be drawn.
 518   </para>
 519 </listitem>
 520 <listitem>
 521   <para>
 522 A <emphasis>
 523 solid doodad</emphasis>
 524  describes some aspect of the keyboard to be drawn as one or more filled
 525 polygons. Solid doodads specify the shape, color, and angle of rotation about
 526 the doodad origin at which they should be drawn.
 527   </para>
 528 </listitem>
 529 <listitem>
 530   <para>
 531 A <emphasis>
 532 text doodad</emphasis>
 533  describes a text label somewhere on the keyboard. Text doodads specify the
 534 label string, the font and color to use when drawing the label, and the angle
 535 of rotation of the doodad about its origin.
 536   </para>
 537 </listitem>
 538 <listitem>
 539   <para>
 540 A <emphasis>
 541 logo doodad </emphasis>
 542 is a catch-all, which describes some other visible element of the keyboard. A
 543 logo doodad is essentially an outline doodad with an additional symbolic name
 544 that describes the element to be drawn. If a keyboard display program
 545 recognizes the symbolic name, it can draw something appropriate within the
 546 bounding region of the shape specified in the doodad. If the symbolic name does
 547 not describe a recognizable image, it should draw an outline using the
 548 specified shape, outline, and angle of rotation. The Xkb extension does not
 549 specify the interpretation of logo names.
 550   </para>
 551 </listitem>
 552 </itemizedlist>
 553
 554 <para>
 555 The structures these doodads are stored in and the values of the <emphasis>
 556 type</emphasis>
 557  fields are shown in Table 13.1.
 558 </para>
 559
 560 <table frame='topbot'>
 561 <title>Doodad Types</title>
 562 <?dbfo keep-together="always" ?>
 563 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 564 <colspec colname='c1' colwidth='1.0*'/>
 565 <colspec colname='c2' colwidth='1.0*'/>
 566 <colspec colname='c3' colwidth='1.0*'/>
 567 <thead>
 568 <row rowsep='1'>
 569   <entry>Doodad</entry>
 570   <entry>Structure</entry>
 571   <entry>Type</entry>
 572   </row>
 573 </thead>
 574 <tbody>
 575   <row>
 576     <entry><emphasis>
 577 indicator doodad</emphasis>
 578 </entry>
 579     <entry><emphasis>
 580 XkbIndicatorDoodadRec</emphasis>
 581 </entry>
 582     <entry><emphasis>
 583 XkbIndicatorDoodad</emphasis>
 584 </entry>
 585   </row>
 586   <row>
 587     <entry><emphasis>
 588 outline doodad</emphasis>
 589 </entry>
 590     <entry><emphasis>
 591 XkbShapeDoodadRec</emphasis>
 592 </entry>
 593     <entry><emphasis>
 594 XkbOutlineDoodad</emphasis>
 595 </entry>
 596   </row>
 597   <row>
 598     <entry><emphasis>
 599 solid doodad</emphasis>
 600 </entry>
 601     <entry><emphasis>
 602 XkbShapeDoodadRec</emphasis>
 603 </entry>
 604     <entry><emphasis>
 605 XkbSolidDoodad</emphasis>
 606 </entry>
 607   </row>
 608   <row>
 609     <entry><emphasis>
 610 text doodad</emphasis>
 611 </entry>
 612     <entry><emphasis>
 613 XkbTextDoodadRec</emphasis>
 614 </entry>
 615     <entry><emphasis>
 616 XkbTextDoodad</emphasis>
 617 </entry>
 618   </row>
 619   <row>
 620     <entry><emphasis>
 621 logo doodad</emphasis>
 622 </entry>
 623     <entry><emphasis>
 624 XkbLogoDoodadRec</emphasis>
 625 </entry>
 626     <entry><emphasis>
 627 XkbLogoDoodad</emphasis>
 628 </entry>
 629   </row>
 630 </tbody>
 631 </tgroup>
 632 </table>
 633
 634 </sect1>
 635 <sect1 id='Overlay_Rows_and_Overlay_Keys'>
 636 <title>Overlay Rows and Overlay Keys</title>
 637
 638 <para>
 639 An <emphasis>
 640 overlay row</emphasis>
 641  (<emphasis>
 642 XkbOverlayRowRec</emphasis>
 643 ) contains a pointer to the row it overlays and a list of <emphasis>
 644 overlay keys</emphasis>
 645 .
 646 </para>
 647
 648
 649 <para>
 650 Each overlay key definition (<emphasis>
 651 XkbOverlayKeyRec</emphasis>
 652 ) indicates a key that can yield multiple keycodes and consists of a field
 653 named <emphasis>
 654 under</emphasis>
 655 , which specifies the primary name of the key and a field named <emphasis>
 656 over</emphasis>
 657 , which specifies the name for the key when the overlay keycode is selected.
 658 The key specified in <emphasis>
 659 under</emphasis>
 660  must be a member of the section that contains the overlay key definition,
 661 while the key specified in over must not be.
 662 </para>
 663
 664
 665 </sect1>
 666 <sect1 id='Drawing_a_Keyboard_Representation'>
 667 <title>Drawing a Keyboard Representation</title>
 668
 669 <para>
 670 To draw a representation of the keyboard, draw in the following order:
 671 </para>
 672
 673 <para><programlisting>
 674      Draw the top-level keyboard as a rectangle, using its width and height.
 675      For each component (section or doodad) of the top-level geometry, in priority order:
 676         If component is a section
 677            For each row, in the order it appears in the section
 678               Draw keys in the order they appear in the row
 679            Draw doodads within the section in priority order.
 680         Else draw doodad
 681 </programlisting></para>
 682
 683 </sect1>
 684 <sect1 id='Geometry_Data_Structures'>
 685 <title>Geometry Data Structures</title>
 686
 687 <para>
 688 In the following figures, a solid arrow denotes a pointer to an array of
 689 structures or a singleton structure. A dotted arrow denotes an index or a
 690 pointer into the array.
 691 </para>
 692
 693 <!--
 694 <MAP NAME="XKBlib-10">
 695 </MAP>
 696 -->
 697 <mediaobject>
 698  <imageobject> <imagedata format="SVG" fileref="XKBlib-10.svg"/>
 699  </imageobject>
 700 <caption>Xkb Geometry Data Structures</caption>
 701 </mediaobject>
 702
 703 <!--
 704 <H5 CLASS="Figure">
 705 Xkb Geometry Data Structures</H5>
 706 <P CLASS="SmallBody">
 707 &nbsp;</P>
 708 <MAP NAME="XKBlib-11">
 709 </MAP>
 710 -->
 711 <mediaobject>
 712  <imageobject> <imagedata format="SVG" fileref="XKBlib-11.svg"/>
 713  </imageobject>
 714 <caption>Xkb Geometry Data Structures (Doodads)</caption>
 715 </mediaobject>
 716
 717 <!--
 718 <H5 CLASS="Figure">
 719 Xkb Geometry Data Structures (Doodads)</H5>
 720 -->
 721
 722 <!--
 723 <MAP NAME="XKBlib-12">
 724 </MAP>
 725 -->
 726 <mediaobject>
 727  <imageobject> <imagedata format="SVG" fileref="XKBlib-12.svg"/>
 728  </imageobject>
 729 <caption>Xkb Geometry Data Structures (Overlays)</caption>
 730 </mediaobject>
 731
 732 <!--
 733 <H5 CLASS="Figure">
 734 Xkb Geometry Data Structures (Overlays)</H5>
 735 -->
 736 <para><programlisting>
 737 typedef struct _XkbGeometry {              /* top-level keyboard geometry structure */
 738       Atom                name;            /* keyboard name */
 739       unsigned short      width_mm;        /* keyboard width in <emphasis> mm</emphasis> /<emphasis> 10</emphasis> */
 740       unsigned short      height_mm;       /* keyboard height in <emphasis> mm</emphasis> /<emphasis> 10</emphasis> */
 741       char *              label_font;      /* font for key labels */
 742       XkbColorPtr         label_color;     /* color for key labels - pointer into colors array */
 743       XkbColorPtr         base_color;      /* color for basic keyboard - pointer into colors array */
 744       unsigned short      sz_properties;   /* size of properties array */
 745       unsigned short      sz_colors;       /* size of colors array */
 746       unsigned short      sz_shapes;       /* size of shapes array */
 747       unsigned short      sz_sections;     /* size of sections array */
 748       unsigned short      sz_doodads;      /* size of doodads array */
 749       unsigned short      sz_key_aliases;  /* size of key aliases array */
 750       unsigned short      num_properties;  /* number of properties in the properties array */
 751       unsigned short      num_colors;      /* number of colors in the colors array */
 752       unsigned short      num_shapes;      /* number of shapes in the shapes array */
 753       unsigned short      num_sections;    /* number of sections in the sections array */
 754       unsigned short      num_doodads;     /* number of doodads in the doodads array */
 755       unsigned short      num_key_aliases; /* number of key aliases in the key */
 756       XkbPropertyPtr      properties;      /* properties array */
 757       XkbColorPtr         colors;          /* colors array */
 758       XkbShapePtr         shapes;          /* shapes array */
 759       XkbSectionPtr       sections;        /* sections array */
 760       XkbDoodadPtr        doodads;         /* doodads array */
 761       XkbKeyAliasPtr      key_aliases;     /* key aliases array */
 762 } <emphasis>XkbGeometryRec</emphasis>*XkbGeometryPtr;
 763 </programlisting></para>
 764
 765 <para>
 766 The <emphasis>
 767 doodads</emphasis>
 768  array is only for doodads not contained in any of the <emphasis>
 769 sections</emphasis>
 770  that has its own <emphasis>
 771 doodads</emphasis>
 772 . The key aliases contained in the <emphasis>
 773 key_aliases</emphasis>
 774  array take precedence over any defined in the keycodes component of the
 775 keyboard description.
 776 </para>
 777
 778 <para><programlisting>
 779 typedef struct _XkbProperty {
 780       char *      name;            /* property name */
 781       char *      value;           /* property value */
 782 } <emphasis>XkbPropertyRec</emphasis>,*XkbPropertyPtr;
 783 </programlisting></para>
 784
 785 <para><programlisting>
 786 typedef struct _XkbColor {
 787       unsigned int      pixel;     /* color */
 788       char *            spec;      /* color name */
 789 } <emphasis>XkbColorRec</emphasis>,*XkbColorPtr;
 790 </programlisting></para>
 791
 792 <para><programlisting>
 793 typedef struct _XkbKeyAliasRec {
 794       char      real[XkbKeyNameLength];   /* real name of the key */
 795       char      alias[XkbKeyNameLength];  /* alias for the key */
 796 } <emphasis>XkbKeyAliasRec</emphasis>,*XkbKeyAliasPtr;
 797 </programlisting></para>
 798
 799 <para><programlisting>
 800 typedef struct _XkbPoint {                /* x,y coordinates */
 801       short      x;
 802       short      y;
 803 } <emphasis>XkbPointRec</emphasis>, *XkbPointPtr;
 804 </programlisting></para>
 805
 806 <para><programlisting>
 807 typedef struct _XkbOutline {
 808       unsigned short      num_points;     /* number of points in the outline */
 809       unsigned short      sz_points;      /* size of the points array */
 810       unsigned short      corner_radius;  /* draw corners as circles with this radius */
 811       XkbPointPtr         points;         /* array of points defining the outline */
 812 } <emphasis>XkbOutlineRec</emphasis>, *XkbOutlinePtr;
 813 </programlisting></para>
 814
 815 <para><programlisting>
 816 typedef struct _XkbBounds {
 817       short      x1,y1;            /* upper left corner of the bounds,
 818                                       in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
 819        short      x2,y2;            /* lower right corner of the bounds, in
 820                                       <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
 821 } <emphasis>XkbBoundsRec</emphasis>, *XkbBoundsPtr;
 822 </programlisting></para>
 823
 824 <para><programlisting>
 825 typedef struct _XkbShape {
 826       Atom              name;           /* shape’s name */
 827       unsigned short    num_outlines;   /* number of outlines for the shape */
 828       unsigned short    sz_outlines;    /* size of the outlines array */
 829       XkbOutlinePtr     outlines;       /* array of outlines for the shape */
 830       XkbOutlinePtr     approx;         /* pointer into the array to the approximating outline */
 831       XkbOutlinePtr     primary;        /* pointer into the array to the primary outline */
 832       XkbBoundsRec      bounds;         /* bounding box for the shape; encompasses all outlines */
 833 } <emphasis>XkbShapeRec</emphasis>, *XkbShapePtr;
 834 </programlisting></para>
 835
 836 <para>
 837 If <emphasis>
 838 approx</emphasis>
 839  and/or <emphasis>
 840 primary</emphasis>
 841  is <emphasis>
 842 NULL</emphasis>
 843 , the default value is used. The default primary outline is the first element
 844 in the outlines array, as is the default approximating outline.
 845 </para>
 846
 847 <para><programlisting>
 848 typedef struct _XkbKey {         /* key in a row */
 849       XkbKeyNameRec    name;     /* key name */
 850       short            gap;      /* gap in <emphasis>mm</emphasis>/<emphasis>10</emphasis> from previous key in row */
 851       unsigned char    shape_ndx;      /* index of shape for key */
 852       unsigned char    color_ndx;      /* index of color for key body */
 853 } <emphasis>XkbKeyRec</emphasis>, *XkbKeyPtr;
 854 </programlisting></para>
 855
 856 <para><programlisting>
 857 typedef struct _XkbRow {             /* row in a section */
 858       short               top;       /* top coordinate of row origin, relative to section’s origin */
 859       short               left;      /* left coordinate of row origin, relative to section’s origin */
 860       unsigned short      num_keys;  /* number of keys in the keys array */
 861       unsigned short      sz_keys;   /* size of the keys array */
 862       int                 vertical;  /* <emphasis>True</emphasis> =&gt;vertical row,
 863                                         <emphasis> False</emphasis> =&gt;horizontal row */
 864       XkbKeyPtr           keys;      /* array of keys in the row*/
 865       XkbBoundsRec        bounds;    /* bounding box for the row */
 866 } <emphasis>XkbRowRec</emphasis>, *XkbRowPtr;
 867 </programlisting></para>
 868
 869 <para>
 870 <emphasis>
 871 top</emphasis>
 872  and <emphasis>
 873 left</emphasis>
 874  are in <emphasis>
 875 mm</emphasis>
 876 /<emphasis>
 877 10</emphasis>
 878 .
 879 </para>
 880
 881 <para><programlisting>
 882 typedef struct _XkbOverlayRec {
 883       Atom              name;           /* overlay name */
 884       XkbSectionPtr     section_under;  /* the section under this overlay */
 885       unsigned short    num_rows;       /* number of rows in the rows array */
 886       unsigned short    sz_rows;        /* size of the rows array */
 887       XkbOverlayRowPtr  rows;           /* array of rows in the overlay */
 888       XkbBoundsPtr      bounds;         /* bounding box for the overlay */
 889 } <emphasis>XkbOverlayRec</emphasis>,*XkbOverlayPtr;
 890 </programlisting></para>
 891
 892 <para><programlisting>
 893 typedef struct _XkbOverlayRow {
 894       unsigned short      row_under;     /* index into the row under this overlay row */
 895       unsigned short      num_keys;      /* number of keys in the keys array */
 896       unsigned short      sz_keys;       /* size of the keys array */
 897       XkbOverlayKeyPtr    keys;          /* array of keys in the overlay row */
 898 } <emphasis>XkbOverlayRowRec</emphasis>,*XkbOverlayRowPtr;
 899 </programlisting></para>
 900
 901 <para>
 902 <emphasis>
 903 row_under</emphasis>
 904  is an index into the array of <emphasis>
 905 rows</emphasis>
 906  in the section under this overlay. The section under this overlay row is the
 907 one pointed to by <emphasis>
 908 section_under</emphasis>
 909  in this overlay row’s <emphasis>
 910 XkbOverlayRec</emphasis>
 911 .
 912 </para>
 913
 914 <para><programlisting>
 915 typedef struct _XkbOverlayKey {
 916       XkbKeyNameRec      over;      /* name of this overlay key */
 917       XkbKeyNameRec      under;     /* name of the key under this overlay key */
 918 } <emphasis>XkbOverlayKeyRec</emphasis>,*XkbOverlayKeyPtr;
 919 </programlisting></para>
 920
 921 <para><programlisting>
 922 typedef struct _XkbSection {
 923       Atom            name;          /* section name */
 924       unsigned char   priority;      /* drawing priority, 0=&gt;highest, 255=&gt;lowest */
 925       short           top;           /* top coordinate of section origin */
 926       short           left;          /* left coordinate of row origin */
 927       unsigned short  width;         /* section width, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
 928       unsigned short  height;        /* section height, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
 929       short           angle;         /* angle of section rotation, counterclockwise */
 930       unsigned short  num_rows;      /* number of rows in the rows array */
 931       unsigned short  num_doodads;   /* number of doodads in the doodads array */
 932       unsigned short  num_overlays;  /* number of overlays in the overlays array */
 933       unsigned short  sz_rows;       /* size of the rows array */
 934       unsigned short  sz_doodads;    /* size of the doodads array */
 935       unsigned short  sz_overlays;   /* size of the overlays array */
 936       XkbRowPtr       rows;          /* section rows array */
 937       XkbDoodadPtr    doodads;       /* section doodads array */
 938       XkbBoundsRec    bounds;        /* bounding box for the section, before rotation*/
 939       XkbOverlayPtr   overlays;      /* section overlays array */
 940 } <emphasis>XkbSectionRec</emphasis>, *XkbSectionPtr;
 941 </programlisting></para>
 942
 943 <para>
 944 <emphasis>
 945 top</emphasis>
 946  and <emphasis>
 947 left</emphasis>
 948  are the origin of the section, relative to the origin of the keyboard, in
 949 <emphasis>
 950 mm</emphasis>
 951 /<emphasis>
 952 10</emphasis>
 953 . <emphasis>
 954 angle</emphasis>
 955  is in <emphasis>
 956 1</emphasis>
 957 /<emphasis>
 958 10</emphasis>
 959  degrees.
 960 </para>
 961
 962 <sect2 id='DoodadRec_Structures'>
 963 <title>DoodadRec Structures</title>
 964
 965 <para>
 966 The doodad arrays in the <emphasis>
 967 XkbGeometryRec</emphasis>
 968  and the <emphasis>
 969 XkbSectionRec</emphasis>
 970  may contain any of the doodad structures and types shown in Table 13.1.
 971 </para>
 972
 973
 974 <para>
 975 The doodad structures form a union:
 976 </para>
 977
 978 <para><programlisting>
 979 typedef union _XkbDoodad {
 980         XkbAnyDoodadRec        any;
 981         XkbShapeDoodadRec      shape;
 982         XkbTextDoodadRec       text;
 983         XkbIndicatorDoodadRec  indicator;
 984         XkbLogoDoodadRec       logo;
 985 } <emphasis>XkbDoodadRec</emphasis>, *XkbDoodadPtr;
 986 </programlisting></para>
 987
 988 <para>
 989 The <emphasis>
 990 top</emphasis>
 991  and <emphasis>
 992 left</emphasis>
 993  coordinates of each doodad are the coordinates of the origin of the doodad
 994 relative to the keyboard’s origin if the doodad is in the <emphasis>
 995 XkbGeometryRec</emphasis>
 996  doodad array, and with respect to the section’s origin if the doodad is in a
 997 <emphasis>
 998 XkbSectionRec</emphasis>
 999  doodad array. The <emphasis>
1000 color_ndx</emphasis>
1001  or <emphasis>
1002 on_color_ndx</emphasis>
1003  and <emphasis>
1004 off_color_ndx</emphasis>
1005  fields are color indices into the <emphasis>
1006 XkbGeometryRec</emphasis>
1007 ’s color array and are the colors to draw the doodads with. Similarly, the
1008 <emphasis>
1009 shape_ndx</emphasis>
1010  fields are indices into the <emphasis>
1011 XkbGeometryRec</emphasis>
1012 ’s shape array.
1013 </para>
1014
1015 <para><programlisting>
1016 typedef struct _XkbShapeDoodad {
1017       Atom       name;                /* doodad name */
1018       unsigned char      type;        /* <emphasis>XkbOutlineDoodad</emphasis>
1019                                          or <emphasis>XkbSolidDoodad</emphasis> */
1020       unsigned char      priority;    /* drawing priority,
1021                                          0=&gt;highest, 255=&gt;lowest */
1022       short      top;                 /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
1023       short      left;                /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
1024       short      angle;               /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */
1025       unsigned short      color_ndx;  /* doodad color */
1026       unsigned short      shape_ndx;  /* doodad shape */
1027 } <emphasis>XkbShapeDoodadRec</emphasis>, *XkbShapeDoodadPtr;
1028 </programlisting></para>
1029
1030 <para><programlisting>
1031 typedef struct _XkbTextDoodad {
1032       Atom            name;         /* doodad name */
1033       unsigned char   type;         /* <emphasis> XkbTextDoodad</emphasis> */
1034       unsigned char   priority;     /* drawing priority,
1035                                        0=&gt;highest, 255=&gt;lowest */
1036       short           top;          /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
1037       short           left;         /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
1038       short           angle;        /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */
1039       short           width;        /* width in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
1040       short           height;       /* height in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
1041       unsigned short  color_ndx;    /* doodad color */
1042       char *           text;        /* doodad text */
1043       char *           font;        /* arbitrary font name for doodad text */
1044 } <emphasis>XkbTextDoodadRec</emphasis>, *XkbTextDoodadPtr;
1045 </programlisting></para>
1046
1047 <para><programlisting>
1048 typedef struct _XkbIndicatorDoodad {
1049       Atom           name;          /* doodad name */
1050       unsigned char  type;          /* <emphasis>XkbIndicatorDoodad</emphasis> */
1051       unsigned char  priority;      /* drawing priority, 0=&gt;highest, 255=&gt;lowest */
1052       short          top;           /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
1053       short          left;          /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
1054       short          angle;         /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */
1055       unsigned short shape_ndx;     /* doodad shape */
1056       unsigned short on_color_ndx;  /* color for doodad if indicator is on */
1057       unsigned short off_color_ndx; /* color for doodad if indicator is off */
1058 } <emphasis>XkbIndicatorDoodadRec</emphasis>, *XkbIndicatorDoodadPtr;
1059 </programlisting></para>
1060
1061 <para><programlisting>
1062 typedef struct _XkbLogoDoodad {
1063       Atom               name;        /* doodad name */
1064       unsigned char      type;        /* <emphasis> XkbLogoDoodad</emphasis> */
1065       unsigned char      priority;    /* drawing priority, 0=&gt;highest, 255=&gt;lowest */
1066       short              top;         /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
1067       short              left;        /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
1068       short              angle;       /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */
1069       unsigned short      color_ndx;  /* doodad color */
1070       unsigned short      shape_ndx;  /* doodad shape */
1071       char *      logo_name;          /* text for logo */
1072 } <emphasis>XkbLogoDoodadRec</emphasis>, *XkbLogoDoodadPtr
1073 </programlisting></para>
1074
1075 </sect2>
1076 </sect1>
1077 <sect1 id='Getting_Keyboard_Geometry_From_the_Server'>
1078 <title>Getting Keyboard Geometry From the Server</title>
1079
1080 <para>
1081 You can load a keyboard geometry as part of the keyboard description returned
1082 by <emphasis>
1083 XkbGetKeyboard</emphasis>
1084 . However, if a keyboard description has been previously loaded, you can
1085 instead obtain the geometry by calling the <emphasis>
1086 XkbGetGeometry</emphasis>
1087 . In this case, the geometry returned is the one associated with the keyboard
1088 whose device ID is contained in the keyboard description.
1089 </para>
1090
1091 <para>
1092 To load a keyboard geometry if you already have the keyboard description, use
1093 <emphasis>XkbGetGeometry</emphasis>.
1094 </para>
1095
1096 <informaltable frame='none'>
1097 <?dbfo keep-together="always" ?>
1098 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1099 <colspec colname='c1' colwidth='1.0*'/>
1100 <tbody>
1101   <row>
1102     <entry role='functiondecl'>
1103 Status <emphasis>
1104 XkbGetGeometry</emphasis>
1105 (<emphasis>
1106 dpy</emphasis>
1107 ,<emphasis>
1108  xkb</emphasis>
1109 )
1110     </entry>
1111   </row>
1112   <row>
1113     <entry role='functionargdecl'>
1114 Display *            <emphasis>
1115 dpy</emphasis>
1116 ;      /* connection to the X server */
1117     </entry>
1118   </row>
1119   <row>
1120     <entry role='functionargdecl'>
1121 XkbDescPtr      <emphasis>
1122       xkb</emphasis>
1123 ;      /* keyboard description that contains the ID for the keyboard and into
1124 which the geometry should be loaded */
1125     </entry>
1126 </row>
1127 </tbody>
1128 </tgroup>
1129 </informaltable>
1130
1131 <para>
1132 <emphasis>
1133 XkbGetGeometry</emphasis>
1134  can return <emphasis>
1135 BadValue</emphasis>
1136 , <emphasis>
1137 BadImplementation</emphasis>
1138 , <emphasis>
1139 BadName</emphasis>
1140 , <emphasis>
1141 BadAlloc,</emphasis>
1142  or <emphasis>
1143 BadLength</emphasis>
1144  errors or <emphasis>
1145 Success</emphasis>
1146  if it succeeds.
1147 </para>
1148
1149 <para>
1150 It is also possible to load a keyboard geometry by name. The X server maintains
1151 a database of keyboard components (see Chapter 20). To load a keyboard geometry
1152 description from this database by name, use <emphasis>
1153 XkbGetNamedGeometry</emphasis>.
1154 </para>
1155
1156 <informaltable frame='none'>
1157 <?dbfo keep-together="always" ?>
1158 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1159 <colspec colname='c1' colwidth='1.0*'/>
1160 <tbody>
1161   <row>
1162     <entry role='functiondecl'>
1163 Status <emphasis>
1164 XkbGetNamedGeometry</emphasis>
1165 (<emphasis>
1166 dpy</emphasis>
1167 ,<emphasis>
1168  xkb</emphasis>
1169 ,<emphasis>
1170  name</emphasis>
1171 )
1172     </entry>
1173   </row>
1174   <row>
1175     <entry role='functionargdecl'>
1176 Display *      <emphasis>
1177 dpy</emphasis>
1178 ;      /* connection to the X server */
1179     </entry>
1180   </row>
1181   <row>
1182     <entry role='functionargdecl'>
1183 XkbDescPtr      <emphasis>
1184 xkb</emphasis>
1185 ;      /* keyboard description into which the geometry should be loaded */
1186     </entry>
1187   </row>
1188   <row>
1189     <entry role='functionargdecl'>
1190 Atom      <emphasis>
1191 name</emphasis>
1192 ;      /* name of the geometry to be loaded */
1193     </entry>
1194 </row>
1195 </tbody>
1196 </tgroup>
1197 </informaltable>
1198
1199 <para>
1200 <emphasis>
1201 XkbGetNamedGeometry</emphasis>
1202  can return <emphasis>
1203 BadName</emphasis>
1204  if the <emphasis>
1205 name</emphasis>
1206  cannot be found.
1207 </para>
1208
1209 </sect1>
1210 <sect1 id='Using_Keyboard_Geometry'>
1211 <title>Using Keyboard Geometry</title>
1212
1213 <para>
1214 Xkb provides a number of convenience functions to help use a keyboard geometry.
1215 These include functions to return the bounding box of a shape’s top surface
1216 and to update the bounding box of a shape row or section.
1217 </para>
1218
1219 <para>
1220 A shape is made up of a number of outlines. Each outline is a polygon made up
1221 of a number of points. The bounding box of a shape is a rectangle that contains
1222 all the outlines of that shape.
1223 </para>
1224
1225 <mediaobject>
1226  <imageobject> <imagedata format="SVG" fileref="XKBlib-13.svg"/>
1227  </imageobject>
1228 <caption>Key Surface, Shape Outlines, and Bounding Box</caption>
1229  </mediaobject>
1230
1231
1232 <!--
1233 <H5 CLASS="Figure">
1234 Key Surface, Shape Outlines, and Bounding Box</H5>
1235 -->
1236
1237 <para>
1238 To determine the bounding box of the top surface of a shape, use <emphasis>
1239 XkbComputeShapeTop</emphasis>.
1240 </para>
1241
1242 <informaltable frame='none'>
1243 <?dbfo keep-together="always" ?>
1244 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1245 <colspec colname='c1' colwidth='1.0*'/>
1246 <tbody>
1247   <row>
1248     <entry role='functiondecl'>
1249 Bool <emphasis>
1250 XkbComputeShapeTop</emphasis>
1251 (<emphasis>
1252 shape</emphasis>
1253 ,<emphasis>
1254  bounds_rtrn</emphasis>
1255 )
1256     </entry>
1257   </row>
1258   <row>
1259     <entry role='functionargdecl'>
1260 XkbShapePtr      <emphasis>
1261       shape</emphasis>
1262 ;      /* shape to be examined */
1263     </entry>
1264   </row>
1265   <row>
1266     <entry role='functionargdecl'>
1267 XkbBoundsPtr      <emphasis>
1268       bounds_rtrn</emphasis>
1269       /* backfilled with the bounding box for the shape */
1270     </entry>
1271 </row>
1272 </tbody>
1273 </tgroup>
1274 </informaltable>
1275
1276 <para>
1277 <emphasis>
1278 XkbComputeShapeTop</emphasis>
1279  returns a <emphasis>
1280 BoundsRec</emphasis>
1281  that contains two x and y coordinates. These coordinates describe the corners
1282 of a rectangle that contains the outline that describes the top surface of the
1283 shape. The top surface is defined to be the approximating outline if the
1284 <emphasis>
1285 approx</emphasis>
1286  field of <emphasis>
1287 shape</emphasis>
1288  is not <emphasis>
1289 NULL</emphasis>
1290 . If <emphasis>
1291 approx</emphasis>
1292  is <emphasis>
1293 NULL</emphasis>
1294 , the top surface is defined as the last outline in the <emphasis>
1295 shape</emphasis>
1296 ’s array of outlines. <emphasis>
1297 XkbComputeShapeTop</emphasis>
1298  returns <emphasis>
1299 False</emphasis>
1300  if <emphasis>
1301 shape</emphasis>
1302  is <emphasis>
1303 NULL</emphasis>
1304  or if there are no outlines for the shape; otherwise, it returns
1305 <emphasis>True</emphasis>.
1306 </para>
1307
1308
1309 <para>
1310 A <emphasis>
1311 ShapeRec</emphasis>
1312  contains a <emphasis>
1313 BoundsRec</emphasis>
1314  that describes the bounds of the shape. If you add or delete an outline to or
1315 from a shape, the bounding box must be updated. To update the bounding box of a
1316 shape, use <emphasis>XkbComputeShapeBounds</emphasis>.
1317 </para>
1318
1319
1320 <informaltable frame='none'>
1321 <?dbfo keep-together="always" ?>
1322 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1323 <colspec colname='c1' colwidth='1.0*'/>
1324 <tbody>
1325   <row>
1326     <entry role='functiondecl'>
1327 Bool <emphasis>
1328 XkbComputeShapeBounds</emphasis>
1329 (<emphasis>
1330 shape</emphasis>
1331 )
1332     </entry>
1333   </row>
1334   <row>
1335     <entry role='functionargdecl'>
1336 XkbShapePtr      <emphasis>
1337       shape</emphasis>
1338 ;            /* shape to be examined */
1339     </entry>
1340 </row>
1341 </tbody>
1342 </tgroup>
1343 </informaltable>
1344
1345 <para>
1346 <emphasis>
1347 XkbComputeShapeBounds</emphasis>
1348  updates the <emphasis>
1349 BoundsRec</emphasis>
1350  contained in the <emphasis>
1351 shape</emphasis>
1352  by examining all the outlines of the shape and setting the <emphasis>
1353 BoundsRec</emphasis>
1354  to the minimum x and minimum y, and maximum x and maximum y values found in
1355 those outlines. <emphasis>
1356 XkbComputeShapeBounds</emphasis>
1357  returns <emphasis>
1358 False</emphasis>
1359  if <emphasis>
1360 shape</emphasis>
1361  is <emphasis>
1362 NULL</emphasis>
1363  or if there are no outlines for the shape; otherwise, it returns <emphasis>
1364 True</emphasis>
1365 .
1366 </para>
1367
1368 <para>
1369  If you add or delete a key to or from a row, or if you update the shape of one
1370 of the keys in that row, you may need to update the bounding box of that row.
1371 To update the bounding box of a row, use <emphasis>XkbComputeRowBounds</emphasis>.
1372 </para>
1373
1374 <informaltable frame='none'>
1375 <?dbfo keep-together="always" ?>
1376 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1377 <colspec colname='c1' colwidth='1.0*'/>
1378 <tbody>
1379   <row>
1380     <entry role='functiondecl'>
1381 Bool <emphasis>
1382 XkbComputeRowBounds</emphasis>
1383 (<emphasis>
1384 geom</emphasis>
1385 ,<emphasis>
1386  section</emphasis>
1387 ,<emphasis>
1388  row</emphasis>
1389 )
1390     </entry>
1391   </row>
1392   <row>
1393     <entry role='functionargdecl'>
1394 XkbGeometryPtr      <emphasis>
1395       geom</emphasis>
1396 ;      /* geometry that contains the <emphasis>
1397 section</emphasis>
1398  */
1399     </entry>
1400   </row>
1401   <row>
1402     <entry role='functionargdecl'>
1403 XkbSectionPtr      <emphasis>
1404       section</emphasis>
1405 ;      /* section that contains the row */
1406     </entry>
1407   </row>
1408   <row>
1409     <entry role='functionargdecl'>
1410 XkbRowPtr            <emphasis>
1411 row</emphasis>
1412 ;      /* row to be examined and updated */
1413     </entry>
1414 </row>
1415 </tbody>
1416 </tgroup>
1417 </informaltable>
1418
1419 <para>
1420 <emphasis>
1421 XkbComputeRowBounds</emphasis>
1422  checks the bounds of all keys in the <emphasis>
1423 row </emphasis>
1424 and updates the bounding box of the row if necessary. <emphasis>
1425 XkbComputeRowBounds</emphasis>
1426  returns <emphasis>
1427 False</emphasis>
1428  if any of the arguments is <emphasis>
1429 NULL</emphasis>
1430 ; otherwise, it returns <emphasis>
1431 True</emphasis>
1432 .
1433 </para>
1434
1435 <para>
1436  If you add or delete a row to or from a section, or if you change the geometry
1437 of any of the rows in that section, you may need to update the bounding box for
1438 that section. To update the bounding box of a section, use
1439 <emphasis>XkbComputeSectionBounds</emphasis>.
1440 </para>
1441
1442 <informaltable frame='none'>
1443 <?dbfo keep-together="always" ?>
1444 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1445 <colspec colname='c1' colwidth='1.0*'/>
1446 <tbody>
1447   <row>
1448     <entry role='functiondecl'>
1449 Bool <emphasis>
1450 XkbComputeSectionBounds</emphasis>
1451 (<emphasis>
1452 geom</emphasis>
1453 ,<emphasis>
1454  section</emphasis>
1455 )
1456     </entry>
1457   </row>
1458   <row>
1459     <entry role='functionargdecl'>
1460 XkbGeometryPtr      <emphasis>
1461       geom</emphasis>
1462 ;      /* geometry that contains the <emphasis>
1463 section</emphasis>
1464  */
1465     </entry>
1466   </row>
1467   <row>
1468     <entry role='functionargdecl'>
1469 XkbSectionPtr      <emphasis>
1470       section</emphasis>
1471 ;      /* section to be examined and updated */
1472     </entry>
1473 </row>
1474 </tbody>
1475 </tgroup>
1476 </informaltable>
1477
1478 <para>
1479 <emphasis>
1480 XkbComputeSectionBounds</emphasis>
1481  examines all the rows of the <emphasis>
1482 section</emphasis>
1483  and updates the bounding box of that section so that it contains all rows.
1484 <emphasis>
1485 XkbComputeSectionBounds</emphasis>
1486  returns <emphasis>
1487 False</emphasis>
1488  if any of the arguments is <emphasis>
1489 NULL</emphasis>
1490 ; otherwise, it returns <emphasis>
1491 True</emphasis>
1492 .
1493 </para>
1494
1495 <para>
1496 Keys that can generate multiple keycodes may be associated with multiple names.
1497 Such keys have a primary name and an alternate name. To find the alternate name
1498 by using the primary name for a key that is part of an overlay, use <emphasis>
1499 XkbFindOverlayForKey</emphasis>.
1500 </para>
1501
1502 <informaltable frame='none'>
1503 <?dbfo keep-together="always" ?>
1504 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1505 <colspec colname='c1' colwidth='1.0*'/>
1506 <tbody>
1507   <row>
1508     <entry role='functiondecl'>
1509 char * <emphasis>
1510 XkbFindOverlayForKey</emphasis>
1511 (<emphasis>
1512 geom</emphasis>
1513 ,<emphasis>
1514  section</emphasis>
1515 ,<emphasis>
1516  under</emphasis>
1517 )
1518     </entry>
1519   </row>
1520   <row>
1521     <entry role='functionargdecl'>
1522 XkbGeometryPtr      <emphasis>
1523       geom</emphasis>
1524 ;      /* geometry that contains the <emphasis>
1525 section</emphasis>
1526  */
1527     </entry>
1528   </row>
1529   <row>
1530     <entry role='functionargdecl'>
1531 XkbSectionPtr      <emphasis>
1532       section</emphasis>
1533 ;      /* section to be searched for matching keys */
1534     </entry>
1535   </row>
1536   <row>
1537     <entry role='functionargdecl'>
1538 char *      <emphasis>
1539       under</emphasis>
1540 .      /* primary name of the key to be considered */
1541     </entry>
1542 </row>
1543 </tbody>
1544 </tgroup>
1545 </informaltable>
1546
1547 <para>
1548 <emphasis>
1549 XkbFindOverlayForKey</emphasis>
1550  uses the primary name of the key, <emphasis>
1551 under</emphasis>
1552 , to look up the alternate name, which it returns.
1553 </para>
1554
1555
1556 </sect1>
1557 <sect1 id='Adding_Elements_to_a_Keyboard_Geometry'>
1558 <title>Adding Elements to a Keyboard Geometry</title>
1559
1560 <para>
1561 Xkb provides functions to add a single new element to the top-level keyboard
1562 geometry. In each case the <emphasis>
1563 num_ </emphasis>
1564 <emphasis>
1565 *</emphasis>
1566  fields of the corresponding structure is incremented by 1. These functions do
1567 not change <emphasis>
1568 sz_</emphasis>
1569 <emphasis>
1570 *</emphasis>
1571  unless there is no more room in the array. Some of these functions fill in the
1572 values of the element’s structure from the arguments. For other functions,
1573 you must explicitly write code to fill the structure’s elements.
1574 </para>
1575
1576
1577 <para>
1578 The top-level geometry description includes a list of <emphasis>
1579 geometry properties</emphasis>
1580 . A geometry property associates an arbitrary string with an equally arbitrary
1581 name. Programs that display images of keyboards can use geometry properties as
1582 hints, but they are not interpreted by Xkb. No other geometry structures refer
1583 to geometry properties.
1584 </para>
1585
1586
1587 <para>
1588 To add one property to an existing keyboard geometry description, use <emphasis>
1589 XkbAddGeomProperty</emphasis>
1590 .
1591 </para>
1592
1593 <informaltable frame='none'>
1594 <?dbfo keep-together="always" ?>
1595 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1596 <colspec colname='c1' colwidth='1.0*'/>
1597 <tbody>
1598   <row>
1599     <entry role='functiondecl'>
1600 XkbPropertyPtr <emphasis>
1601 XkbAddGeomProperty</emphasis>
1602 (<emphasis>
1603 geom</emphasis>
1604 ,<emphasis>
1605  name</emphasis>
1606 ,<emphasis>
1607  value</emphasis>
1608 )
1609     </entry>
1610   </row>
1611   <row>
1612     <entry role='functionargdecl'>
1613 XkbGeometryPtr      <emphasis>
1614       geom</emphasis>
1615 ;      /* geometry to be updated */
1616     </entry>
1617   </row>
1618   <row>
1619     <entry role='functionargdecl'>
1620 char *      <emphasis>
1621       name</emphasis>
1622 ;      /* name of the new property */
1623     </entry>
1624   </row>
1625   <row>
1626     <entry role='functionargdecl'>
1627 char *      <emphasis>
1628       value</emphasis>
1629 ;      /* value for the new property */
1630     </entry>
1631 </row>
1632 </tbody>
1633 </tgroup>
1634 </informaltable>
1635
1636 <para>
1637 <emphasis>
1638 XkbAddGeomProperty</emphasis>
1639  adds one property with the specified <emphasis>
1640 name</emphasis>
1641  and <emphasis>
1642 value</emphasis>
1643  to the keyboard geometry specified by geom.<emphasis>
1644  </emphasis>
1645 <emphasis>
1646 XkbAddGeomProperty</emphasis>
1647  returns <emphasis>
1648 NULL</emphasis>
1649  if any of the parameters is empty or if it was not able to allocate space for
1650 the property. To allocate space for an arbitrary number of properties, use the
1651 XkbAllocGeomProps function.
1652 </para>
1653
1654
1655 <para>
1656 To add one key alias to an existing keyboard geometry description, use
1657 <emphasis>
1658 XkbAddGeomKeyAlias</emphasis>
1659 .
1660 </para>
1661
1662
1663 <informaltable frame='none'>
1664 <?dbfo keep-together="always" ?>
1665 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1666 <colspec colname='c1' colwidth='1.0*'/>
1667 <tbody>
1668   <row>
1669     <entry role='functiondecl'>
1670 XkbKeyAliasPtr <emphasis>
1671 XkbAddGeomKeyAlias</emphasis>
1672 (<emphasis>
1673 geom</emphasis>
1674 ,<emphasis>
1675  alias, real</emphasis>
1676 )
1677     </entry>
1678   </row>
1679   <row>
1680     <entry role='functionargdecl'>
1681 XkbGeometryPtr      <emphasis>
1682       geom</emphasis>
1683 ;      /* geometry to be updated */
1684     </entry>
1685   </row>
1686   <row>
1687     <entry role='functionargdecl'>
1688 char *      <emphasis>
1689       alias</emphasis>
1690 ;      /* alias to be added */
1691     </entry>
1692   </row>
1693   <row>
1694     <entry role='functionargdecl'>
1695 char *      <emphasis>
1696       real</emphasis>
1697 ;      /* real name to be bound to the new alias */
1698     </entry>
1699 </row>
1700 </tbody>
1701 </tgroup>
1702 </informaltable>
1703
1704 <para>
1705 <emphasis>
1706 XkbAddGeomKeyAlias</emphasis>
1707  adds one key alias with the value alias to the geometry geom, and associates
1708 it with the key whose real name is real. <emphasis>
1709 XkbAddGeomKeyAlias</emphasis>
1710  returns <emphasis>
1711 NULL</emphasis>
1712  if any of the parameters is empty or if it was not able to allocate space for
1713 the alias. To allocate space for an arbitrary number of aliases, use the
1714 XkbAllocGeomKeyAliases function.
1715 </para>
1716
1717
1718 <para>
1719 To add one color name to an existing keyboard geometry description, use
1720 <emphasis>
1721 XkbAddGeomColor</emphasis>
1722 .
1723 </para>
1724
1725
1726 <informaltable frame='none'>
1727 <?dbfo keep-together="always" ?>
1728 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1729 <colspec colname='c1' colwidth='1.0*'/>
1730 <tbody>
1731   <row>
1732     <entry role='functiondecl'>
1733 XkbColorPtr <emphasis>
1734 XkbAddGeomColor</emphasis>
1735 (<emphasis>
1736 geom</emphasis>
1737 ,<emphasis>
1738  spec</emphasis>
1739 ,<emphasis>
1740  pixel</emphasis>
1741 )
1742     </entry>
1743   </row>
1744   <row>
1745     <entry role='functionargdecl'>
1746 XkbGeometryPtr      <emphasis>
1747       geom</emphasis>
1748 ;      /* geometry to be updated */
1749     </entry>
1750   </row>
1751   <row>
1752     <entry role='functionargdecl'>
1753 char *      <emphasis>
1754       spec</emphasis>
1755 ;      /* color to be added */
1756     </entry>
1757   </row>
1758   <row>
1759     <entry role='functionargdecl'>
1760 unsigned int      <emphasis>
1761       pixel</emphasis>
1762 ;      /* color to be added */
1763     </entry>
1764 </row>
1765 </tbody>
1766 </tgroup>
1767 </informaltable>
1768
1769 <para>
1770 <emphasis>
1771 XkbAddGeomColor</emphasis>
1772  adds the specified color <emphasis>
1773 name</emphasis>
1774  and <emphasis>
1775 pixel</emphasis>
1776  to the specified geometry <emphasis>
1777 geom</emphasis>
1778 . The top-level geometry description includes a list of up to <emphasis>
1779 MaxColors</emphasis>
1780  (32) <emphasis>
1781 color names</emphasis>
1782 . A color <emphasis>
1783 name</emphasis>
1784  is a string whose interpretation is not specified by Xkb and neither is the
1785 <emphasis>
1786 pixel</emphasis>
1787  value’s interpretation. All other geometry data structures refer to colors
1788 using their indices in this global list or pointers to colors in this list.
1789 <emphasis>
1790 XkbAddGeomColor</emphasis>
1791  returns <emphasis>
1792 NULL</emphasis>
1793  if any of the parameters is empty or if it was not able to allocate space for
1794 the color. To allocate space for an arbitrary number of colors to a geometry,
1795 use the <emphasis>
1796 XkbAllocGeomColors</emphasis>
1797  function.
1798 </para>
1799
1800 <para>
1801 To add one outline to an existing shape, use <emphasis>
1802 XkbAddGeomOutline</emphasis>.
1803 </para>
1804
1805 <informaltable frame='none'>
1806 <?dbfo keep-together="always" ?>
1807 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1808 <colspec colname='c1' colwidth='1.0*'/>
1809 <tbody>
1810   <row>
1811     <entry role='functiondecl'>
1812 XkbOutlinePtr <emphasis>
1813 XkbAddGeomOutline</emphasis>
1814 (<emphasis>
1815 shape</emphasis>
1816 ,<emphasis>
1817  sz_points</emphasis>
1818 )
1819     </entry>
1820   </row>
1821   <row>
1822     <entry role='functionargdecl'>
1823 XkbShapePtr      <emphasis>
1824       shape</emphasis>
1825 ;      /* shape to be updated */
1826     </entry>
1827   </row>
1828   <row>
1829     <entry role='functionargdecl'>
1830 int      <emphasis>
1831       sz_points</emphasis>
1832 ;      /* number of points to be reserved */
1833     </entry>
1834 </row>
1835 </tbody>
1836 </tgroup>
1837 </informaltable>
1838
1839 <para>
1840 An outline consists of an arbitrary number of points. <emphasis>
1841 XkbAddGeomOutline</emphasis>
1842  adds an outline to the specified <emphasis>
1843 shape</emphasis>
1844  by reserving <emphasis>
1845 sz_points</emphasis>
1846  points for it. The new outline is allocated and zeroed. <emphasis>
1847 XkbAddGeomOutline</emphasis>
1848  returns <emphasis>
1849 NULL</emphasis>
1850  if any of the parameters is empty or if it was not able to allocate space. To
1851 allocate space for an arbitrary number of outlines to a shape, use
1852 XkbAllocGeomOutlines.
1853 </para>
1854
1855
1856 <para>
1857 To add a shape to a keyboard geometry, use <emphasis>
1858 XkbAddGeomShape</emphasis>
1859 .
1860 </para>
1861
1862
1863 <informaltable frame='none'>
1864 <?dbfo keep-together="always" ?>
1865 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1866 <colspec colname='c1' colwidth='1.0*'/>
1867 <tbody>
1868   <row>
1869     <entry role='functiondecl'>
1870 XkbShapePtr <emphasis>
1871 XkbAddGeomShape</emphasis>
1872 (<emphasis>
1873 geom</emphasis>
1874 ,<emphasis>
1875  name</emphasis>
1876 ,<emphasis>
1877  sz_outlines</emphasis>
1878 )
1879     </entry>
1880   </row>
1881   <row>
1882     <entry role='functionargdecl'>
1883 XkbGeometryPtr      <emphasis>
1884       geom</emphasis>
1885 ;      /* geometry to be updated */
1886     </entry>
1887   </row>
1888   <row>
1889     <entry role='functionargdecl'>
1890 Atom      <emphasis>
1891       name</emphasis>
1892 ;      /* name of the new shape */
1893     </entry>
1894   </row>
1895   <row>
1896     <entry role='functionargdecl'>
1897 int      <emphasis>
1898       sz_outlines</emphasis>
1899 ;      /* number of outlines to be reserved */
1900     </entry>
1901 </row>
1902 </tbody>
1903 </tgroup>
1904 </informaltable>
1905
1906 <para>
1907 A geometry contains an arbitrary number of shapes, each of which is made up of
1908 an arbitrary number of outlines. <emphasis>
1909 XkbAddGeomShape</emphasis>
1910  adds a shape to a geometry <emphasis>
1911 geom</emphasis>
1912  by allocating space for <emphasis>
1913 sz_outlines</emphasis>
1914  outlines for it and giving it the name specified by name. If a shape with name
1915 <emphasis>
1916 name</emphasis>
1917  already exists in the geometry, a pointer to the existing shape is returned.
1918 <emphasis>
1919 XkbAddGeomShape</emphasis>
1920  returns <emphasis>
1921 NULL</emphasis>
1922  if any of the parameters is empty or if it was not able to allocate space. To
1923 allocate space for an arbitrary number of geometry shapes, use <emphasis>
1924 XkbAllocGeomShapes</emphasis>
1925 .
1926 </para>
1927
1928
1929 <para>
1930 To add one key at the end of an existing row of keys, use <emphasis>
1931 XkbAddGeomKey</emphasis>
1932 .
1933 </para>
1934
1935
1936 <informaltable frame='none'>
1937 <?dbfo keep-together="always" ?>
1938 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1939 <colspec colname='c1' colwidth='1.0*'/>
1940 <tbody>
1941   <row>
1942     <entry role='functiondecl'>
1943 XkbKeyPtr <emphasis>
1944 XkbAddGeomKey</emphasis>
1945 (<emphasis>
1946 row</emphasis>
1947 )
1948     </entry>
1949   </row>
1950   <row>
1951     <entry role='functionargdecl'>
1952 XkbRowPtr      <emphasis>
1953       row</emphasis>
1954 ;      /* row to be updated */
1955     </entry>
1956 </row>
1957 </tbody>
1958 </tgroup>
1959 </informaltable>
1960
1961 <para>
1962 Keys are grouped into rows. <emphasis>
1963 XkbAddGeomKey</emphasis>
1964  adds one key to the end of the specified <emphasis>
1965 row</emphasis>
1966 . The key is allocated and zeroed. <emphasis>
1967 XkbAddGeomKey</emphasis>
1968  returns <emphasis>
1969 NULL</emphasis>
1970  if <emphasis>
1971 row</emphasis>
1972  is empty or if it was not able to allocate space for the key. To allocate
1973 space for an arbitrary number of keys to a row, use XkbAllocGeomKeys.
1974 </para>
1975
1976
1977 <para>
1978 To add one section to an existing keyboard geometry, use <emphasis>
1979 XkbAddGeomSection</emphasis>
1980 .
1981 </para>
1982
1983
1984 <informaltable frame='none'>
1985 <?dbfo keep-together="always" ?>
1986 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1987 <colspec colname='c1' colwidth='1.0*'/>
1988 <tbody>
1989   <row>
1990     <entry role='functiondecl'>
1991 XkbSectionPtr <emphasis>
1992 XkbAddGeomSection</emphasis>
1993 (<emphasis>
1994 geom</emphasis>
1995 ,<emphasis>
1996  name</emphasis>
1997 ,<emphasis>
1998  sz_rows</emphasis>
1999 ,<emphasis>
2000  sz_doodads</emphasis>
2001 ,<emphasis>
2002  sz_overlays</emphasis>
2003 )
2004     </entry>
2005   </row>
2006   <row>
2007     <entry role='functionargdecl'>
2008 XkbGeometryPtr      <emphasis>
2009       geom</emphasis>
2010 ;      /* geometry to be updated */
2011     </entry>
2012   </row>
2013   <row>
2014     <entry role='functionargdecl'>
2015 Atom      <emphasis>
2016       name</emphasis>
2017 ;      /* name of the new section */
2018     </entry>
2019   </row>
2020   <row>
2021     <entry role='functionargdecl'>
2022 int      <emphasis>
2023       sz_rows</emphasis>
2024 ;      /* number of rows to reserve in the section */
2025     </entry>
2026   </row>
2027   <row>
2028     <entry role='functionargdecl'>
2029 int      <emphasis>
2030       sz_doodads</emphasis>
2031 ;      /* number of doodads to reserve in the section */
2032     </entry>
2033   </row>
2034   <row>
2035     <entry role='functionargdecl'>
2036 int      <emphasis>
2037       sz_overlays</emphasis>
2038 ;      /* number of overlays to reserve in the section */
2039     </entry>
2040 </row>
2041 </tbody>
2042 </tgroup>
2043 </informaltable>
2044
2045 <para>
2046 A keyboard geometry contains an arbitrary number of sections. <emphasis>
2047 XkbAddGeomSection</emphasis>
2048  adds one section to an existing keyboard geometry <emphasis>
2049 geom</emphasis>
2050 . The new section contains space for the number of rows, doodads, and overlays
2051 specified by <emphasis>
2052 sz_rows</emphasis>
2053 , <emphasis>
2054 sz_doodads</emphasis>
2055 , and <emphasis>
2056 sz_overlays</emphasis>
2057 . The new section is allocated and zeroed and given the name specified by
2058 <emphasis>
2059 name</emphasis>
2060 . If a section with name <emphasis>
2061 name</emphasis>
2062  already exists in the geometry, a pointer to the existing section is
2063 returned.<emphasis>
2064  XkbAddGeomSection</emphasis>
2065  returns <emphasis>
2066 NULL</emphasis>
2067  if any of the parameters is empty or if it was not able to allocate space for
2068 the section. To allocate space for an arbitrary number of sections to a
2069 geometry, use XkbAllocGeomSections.
2070 </para>
2071
2072
2073 <para>
2074 To add a row to a section, use <emphasis>
2075 XkbAddGeomRow</emphasis>
2076 .
2077 </para>
2078
2079
2080 <informaltable frame='none'>
2081 <?dbfo keep-together="always" ?>
2082 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2083 <colspec colname='c1' colwidth='1.0*'/>
2084 <tbody>
2085   <row>
2086     <entry role='functiondecl'>
2087 XkbRowPtr <emphasis>
2088 XkbAddGeomRow</emphasis>
2089 (<emphasis>
2090 section</emphasis>
2091 ,<emphasis>
2092  sz_keys</emphasis>
2093 )
2094     </entry>
2095   </row>
2096   <row>
2097     <entry role='functionargdecl'>
2098 XkbSectionPtr      <emphasis>
2099       section</emphasis>
2100 ;      /* section to be updated */
2101     </entry>
2102   </row>
2103   <row>
2104     <entry role='functionargdecl'>
2105 int            <emphasis>
2106 sz_keys</emphasis>
2107 ;      /* number of keys to be reserved */
2108     </entry>
2109 </row>
2110 </tbody>
2111 </tgroup>
2112 </informaltable>
2113
2114 <para>
2115 One of the components of a keyboard geometry section is one or more rows of
2116 keys. <emphasis>
2117 XkbAddGeomRow</emphasis>
2118  adds one row to the specified <emphasis>
2119 section</emphasis>
2120 . The newly created row contains space for the number of keys specified in
2121 <emphasis>
2122 sz_keys</emphasis>
2123 . They are allocated and zeroed, but otherwise uninitialized. <emphasis>
2124 XkbAddGeomRow</emphasis>
2125  returns <emphasis>
2126 NULL</emphasis>
2127  if any of the parameters is empty or if it was not able to allocate space for
2128 the row. To allocate space for an arbitrary number of rows to a section, use
2129 the XkbAllocGeomRows function.
2130 </para>
2131
2132
2133 <para>
2134 To add one doodad to a section of a keyboard geometry or to the top-level
2135 geometry, use <emphasis>
2136 XkbAddGeomDoodad</emphasis>
2137 .
2138 </para>
2139
2140
2141 <informaltable frame='none'>
2142 <?dbfo keep-together="always" ?>
2143 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2144 <colspec colname='c1' colwidth='1.0*'/>
2145 <tbody>
2146   <row>
2147     <entry role='functiondecl'>
2148 XkbDoodadPtr <emphasis>
2149 XkbAddGeomDoodad</emphasis>
2150 (<emphasis>
2151 geom</emphasis>
2152 ,<emphasis>
2153  section</emphasis>
2154 ,<emphasis>
2155  name</emphasis>
2156 )
2157     </entry>
2158   </row>
2159   <row>
2160     <entry role='functionargdecl'>
2161 XkbGeometryPtr      <emphasis>
2162       geom</emphasis>
2163 ;      /* geometry to which the doodad is added */
2164     </entry>
2165   </row>
2166   <row>
2167     <entry role='functionargdecl'>
2168 XkbSectionPtr      <emphasis>
2169       section</emphasis>
2170 ;      /* section, if any, to which the doodad is added */
2171     </entry>
2172   </row>
2173   <row>
2174     <entry role='functionargdecl'>
2175 Atom      <emphasis>
2176       name</emphasis>
2177 ;      /* name of the new doodad */
2178     </entry>
2179 </row>
2180 </tbody>
2181 </tgroup>
2182 </informaltable>
2183
2184 <para>
2185 A <emphasis>
2186 doodad</emphasis>
2187  describes some visible aspect of the keyboard that is not a key and is not a
2188 section. <emphasis>
2189 XkbAddGeomDoodad</emphasis>
2190  adds a doodad with name specified by name to the geometry <emphasis>
2191 geom</emphasis>
2192  if section is <emphasis>
2193 NULL</emphasis>
2194  or to the section of the geometry specified by section if <emphasis>
2195 section</emphasis>
2196  is not <emphasis>
2197 NULL</emphasis>
2198 . <emphasis>
2199 XkbAddGeomDoodad</emphasis>
2200  returns <emphasis>
2201 NULL</emphasis>
2202  if any of the parameters is empty or if it was not able to allocate space for
2203 the doodad. If there is already a doodad with the name <emphasis>
2204 name</emphasis>
2205  in the doodad array for the geometry (if <emphasis>
2206 section</emphasis>
2207  is <emphasis>
2208 NULL</emphasis>
2209 ) or the section (if <emphasis>
2210 section</emphasis>
2211  is non-<emphasis>
2212 NULL</emphasis>
2213 ), a pointer to that doodad is returned. To allocate space for an arbitrary
2214 number of doodads to a section, use the XkbAllocGeomSectionDoodads function. To
2215 allocate space for an arbitrary number of doodads to a keyboard geometry, use
2216 the XkbAllocGeomDoodads function.
2217 </para>
2218
2219
2220 <para>
2221 To add one overlay to a section, use <emphasis>
2222 XkbAddGeomOverlay</emphasis>
2223 .
2224 </para>
2225
2226
2227 <informaltable frame='none'>
2228 <?dbfo keep-together="always" ?>
2229 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2230 <colspec colname='c1' colwidth='1.0*'/>
2231 <tbody>
2232   <row>
2233     <entry role='functiondecl'>
2234 XkbOverlayPtr <emphasis>
2235 XkbAddGeomOverlay</emphasis>
2236 (<emphasis>
2237 section</emphasis>
2238 ,<emphasis>
2239  name</emphasis>
2240 ,<emphasis>
2241  sz_rows</emphasis>
2242 )
2243     </entry>
2244   </row>
2245   <row>
2246     <entry role='functionargdecl'>
2247 XkbSectionPtr      <emphasis>
2248       section</emphasis>
2249 ;      /* section to which an overlay will be added */
2250     </entry>
2251   </row>
2252   <row>
2253     <entry role='functionargdecl'>
2254 Atom      <emphasis>
2255       name</emphasis>
2256 ;      /* name of the overlay */
2257     </entry>
2258   </row>
2259   <row>
2260     <entry role='functionargdecl'>
2261 int      <emphasis>
2262       sz_rows</emphasis>
2263 ;      /* number of rows to reserve in the overlay */
2264     </entry>
2265 </row>
2266 </tbody>
2267 </tgroup>
2268 </informaltable>
2269
2270 <para>
2271 <emphasis>
2272 XkbAddGeomOverlay</emphasis>
2273  adds an overlay with the specified name to the specified <emphasis>
2274 section</emphasis>
2275 . The new overlay is created with space allocated for sz_rows rows. If an
2276 overlay with name <emphasis>
2277 name</emphasis>
2278  already exists in the section, a pointer to the existing overlay is
2279 returned.<emphasis>
2280  XkbAddGeomOverlay</emphasis>
2281  returns <emphasis>
2282 NULL</emphasis>
2283  if any of the parameters is empty or if it was not able to allocate space for
2284 the overlay. To allocate space for an arbitrary number of overlays to a
2285 section, use the XkbAllocGeomOverlay function.
2286 </para>
2287
2288
2289 <para>
2290 To add a row to an existing overlay, use <emphasis>
2291 XkbAddGeomOverlayRow</emphasis>
2292 .
2293 </para>
2294
2295
2296 <informaltable frame='none'>
2297 <?dbfo keep-together="always" ?>
2298 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2299 <colspec colname='c1' colwidth='1.0*'/>
2300 <tbody>
2301   <row>
2302     <entry role='functiondecl'>
2303 XkbOverlayRowPtr <emphasis>
2304 XkbAddGeomOverlayRow</emphasis>
2305 (<emphasis>
2306 overlay</emphasis>
2307 ,<emphasis>
2308  row_under, sz_keys</emphasis>
2309 )
2310     </entry>
2311   </row>
2312   <row>
2313     <entry role='functionargdecl'>
2314 XkbOverlayPtr      <emphasis>
2315       overlay</emphasis>
2316 ;      /* overlay to be updated */
2317     </entry>
2318   </row>
2319   <row>
2320     <entry role='functionargdecl'>
2321 XkbRowPtr      <emphasis>
2322       row_under</emphasis>
2323 ;      /* row to be overlayed in the section <emphasis>
2324 overlay</emphasis>
2325  overlays */
2326     </entry>
2327   </row>
2328   <row>
2329     <entry role='functionargdecl'>
2330 int      <emphasis>
2331       sz_keys</emphasis>
2332 ;      /* number of keys to reserve in the row */
2333     </entry>
2334 </row>
2335 </tbody>
2336 </tgroup>
2337 </informaltable>
2338
2339 <para>
2340 <emphasis>
2341 XkbAddGeomOverlayRow</emphasis>
2342  adds one row to the <emphasis>
2343 overlay</emphasis>
2344 . The new row contains space for <emphasis>
2345 sz_keys</emphasis>
2346  keys. If <emphasis>
2347 row_under</emphasis>
2348  specifies a row that doesn’t exist on the underlying section, <emphasis>
2349 XkbAddGeomOverlayRow</emphasis>
2350  returns <emphasis>
2351 NULL</emphasis>
2352  and doesn’t change the overlay.<emphasis>
2353  XkbAddGeomOverlayRow</emphasis>
2354  returns <emphasis>
2355 NULL</emphasis>
2356  if any of the parameters is empty or if it was not able to allocate space for
2357 the overlay.
2358 </para>
2359
2360
2361 <para>
2362 To add a key to an existing overlay row, use <emphasis>
2363 XkbAddGeomOverlayKey</emphasis>
2364 .
2365 </para>
2366
2367
2368 <informaltable frame='none'>
2369 <?dbfo keep-together="always" ?>
2370 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2371 <colspec colname='c1' colwidth='1.0*'/>
2372 <tbody>
2373   <row>
2374     <entry role='functiondecl'>
2375 XkbOverlayKeyPtr <emphasis>
2376 XkbAddGeomOverlayKey</emphasis>
2377 (<emphasis>
2378 overlay</emphasis>
2379 ,<emphasis>
2380  row, under</emphasis>
2381 )
2382     </entry>
2383   </row>
2384   <row>
2385     <entry role='functionargdecl'>
2386 XkbOverlayPtr      <emphasis>
2387       overlay</emphasis>
2388 ;      /* overlay to be updated */
2389     </entry>
2390   </row>
2391   <row>
2392     <entry role='functionargdecl'>
2393 XkbRowPtr      <emphasis>
2394       row</emphasis>
2395 ;      /* row in overlay to be updated */
2396     </entry>
2397   </row>
2398   <row>
2399     <entry role='functionargdecl'>
2400 char *      <emphasis>
2401       under</emphasis>
2402 ;      /* primary name of the key to be considered */
2403     </entry>
2404 </row>
2405 </tbody>
2406 </tgroup>
2407 </informaltable>
2408
2409 <para>
2410 <emphasis>
2411 XkbAddGeomOverlayKey</emphasis>
2412  adds one key to the <emphasis>
2413 row</emphasis>
2414  in the <emphasis>
2415 overlay</emphasis>
2416 . If there is no key named <emphasis>
2417 under</emphasis>
2418  in the row of the underlying section, <emphasis>
2419 XkbAddGeomOverlayKey</emphasis>
2420  returns <emphasis>
2421 NULL</emphasis>
2422 .
2423 </para>
2424
2425
2426 </sect1>
2427 <sect1 id='Allocating_and_Freeing_Geometry_Components'>
2428 <title>Allocating and Freeing Geometry Components</title>
2429
2430 <para>
2431 Xkb provides a number of functions to allocate and free subcomponents of a
2432 keyboard geometry. Use these functions to create or modify keyboard geometries.
2433 Note that these functions merely allocate space for the new element(s), and it
2434 is up to you to fill in the values explicitly in your code. These allocation
2435 functions increase <emphasis>
2436 sz_</emphasis>
2437 <emphasis>
2438 *</emphasis>
2439  but never touch <emphasis>
2440 num_</emphasis>
2441 <emphasis>
2442 *</emphasis>
2443  (unless there is an allocation failure, in which case they reset both
2444 <emphasis>
2445 sz_</emphasis>
2446 <emphasis>
2447 *</emphasis>
2448  and <emphasis>
2449 num_</emphasis>
2450 <emphasis>
2451 *</emphasis>
2452  to zero). These functions return <emphasis>
2453 Success</emphasis>
2454  if they succeed, <emphasis>
2455 BadAlloc</emphasis>
2456  if they are not able to allocate space, or <emphasis>
2457 BadValue</emphasis>
2458  if a parameter is not as expected.
2459 </para>
2460
2461
2462 <para>
2463 To allocate space for an arbitrary number of outlines to a shape, use
2464 XkbAllocGeomOutlines.
2465 </para>
2466
2467 <informaltable frame='none'>
2468 <?dbfo keep-together="always" ?>
2469 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2470 <colspec colname='c1' colwidth='1.0*'/>
2471 <tbody>
2472   <row>
2473     <entry role='functiondecl'>
2474 Status <emphasis>
2475 XkbAllocGeomOutlines</emphasis>
2476 (<emphasis>
2477 shape</emphasis>
2478 ,<emphasis>
2479  num_needed</emphasis>
2480 )
2481     </entry>
2482   </row>
2483   <row>
2484     <entry role='functionargdecl'>
2485 XkbShapePtr            <emphasis>
2486 shape</emphasis>
2487 ;      /* shape for which outlines should be allocated */
2488     </entry>
2489   </row>
2490   <row>
2491     <entry role='functionargdecl'>
2492 int      <emphasis>
2493       num_needed</emphasis>
2494 ;      /* number of new outlines required */
2495     </entry>
2496 </row>
2497 </tbody>
2498 </tgroup>
2499 </informaltable>
2500
2501 <para>
2502 <emphasis>
2503 XkbAllocGeomOutlines</emphasis>
2504  allocates space for <emphasis>
2505 num_needed</emphasis>
2506  outlines in the specified <emphasis>
2507 shape</emphasis>
2508 . The outlines are not initialized.
2509 </para>
2510
2511
2512 <para>
2513 To free geometry outlines, use <emphasis>
2514 XkbFreeGeomOutlines</emphasis>
2515 .
2516 </para>
2517
2518
2519 <informaltable frame='none'>
2520 <?dbfo keep-together="always" ?>
2521 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2522 <colspec colname='c1' colwidth='1.0*'/>
2523 <tbody>
2524   <row>
2525     <entry role='functiondecl'>
2526 void <emphasis>
2527 XkbFreeGeomOutlines</emphasis>
2528 (<emphasis>
2529 shape</emphasis>
2530 ,<emphasis>
2531  first</emphasis>
2532 ,<emphasis>
2533  count</emphasis>
2534 ,<emphasis>
2535  free_all</emphasis>
2536 )
2537     </entry>
2538   </row>
2539   <row>
2540     <entry role='functionargdecl'>
2541 XkbShapePtr      <emphasis>
2542       shape</emphasis>
2543 ;      /* shape in which outlines should be freed */
2544     </entry>
2545   </row>
2546   <row>
2547     <entry role='functionargdecl'>
2548 int      <emphasis>
2549       first</emphasis>
2550 ;      /* first outline to be freed */
2551     </entry>
2552   </row>
2553   <row>
2554     <entry role='functionargdecl'>
2555 int      <emphasis>
2556       count</emphasis>
2557 ;      /* number of outlines to be freed */
2558     </entry>
2559   </row>
2560   <row>
2561     <entry role='functionargdecl'>
2562 Bool      <emphasis>
2563       free_all;</emphasis>
2564       /* <emphasis>
2565 True</emphasis>
2566  =&gt; all outlines are freed */
2567     </entry>
2568 </row>
2569 </tbody>
2570 </tgroup>
2571 </informaltable>
2572
2573 <para>
2574 If free_all is <emphasis>
2575 True</emphasis>
2576 , all outlines are freed regardless of the value of first or count. Otherwise,
2577 count outlines are freed beginning with the one specified by first.
2578 </para>
2579
2580
2581 <para>
2582 To allocate space for an arbitrary number of keys to a row, use
2583 XkbAllocGeomKeys.
2584 </para>
2585
2586
2587 <informaltable frame='none'>
2588 <?dbfo keep-together="always" ?>
2589 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2590 <colspec colname='c1' colwidth='1.0*'/>
2591 <tbody>
2592   <row>
2593     <entry role='functiondecl'>
2594 Status <emphasis>
2595 XkbAllocGeomKeys</emphasis>
2596 (<emphasis>
2597 row</emphasis>
2598 ,<emphasis>
2599  num_needed</emphasis>
2600 )
2601     </entry>
2602   </row>
2603   <row>
2604     <entry role='functionargdecl'>
2605 XkbRowPtr      <emphasis>
2606       row</emphasis>
2607 ;      /* row to which keys should be allocated */
2608     </entry>
2609   </row>
2610   <row>
2611     <entry role='functionargdecl'>
2612 int      <emphasis>
2613       num_needed</emphasis>
2614 ;      /* number of new keys required */
2615     </entry>
2616 </row>
2617 </tbody>
2618 </tgroup>
2619 </informaltable>
2620
2621 <para>
2622 <emphasis>
2623 XkbAllocGeomKeys</emphasis>
2624  allocates num_needed keys and adds them to the row. No initialization of the
2625 keys is done.
2626 </para>
2627
2628
2629 <para>
2630 To free geometry keys, use <emphasis>
2631 XkbFreeGeomKeys</emphasis>
2632 .
2633 </para>
2634
2635
2636 <informaltable frame='none'>
2637 <?dbfo keep-together="always" ?>
2638 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2639 <colspec colname='c1' colwidth='1.0*'/>
2640 <tbody>
2641   <row>
2642     <entry role='functiondecl'>
2643 void <emphasis>
2644 XkbFreeGeomKeys</emphasis>
2645 (<emphasis>
2646 row</emphasis>
2647 ,<emphasis>
2648  first</emphasis>
2649 ,<emphasis>
2650  count</emphasis>
2651 ,<emphasis>
2652  free_all</emphasis>
2653 )
2654     </entry>
2655   </row>
2656   <row>
2657     <entry role='functionargdecl'>
2658 XkbRowPtr      <emphasis>
2659       row</emphasis>
2660 ;      /* row in which keys should be freed */
2661     </entry>
2662   </row>
2663   <row>
2664     <entry role='functionargdecl'>
2665 int      <emphasis>
2666       first</emphasis>
2667 ;      /* first key to be freed */
2668     </entry>
2669   </row>
2670   <row>
2671     <entry role='functionargdecl'>
2672 int      <emphasis>
2673       count</emphasis>
2674 ;      /* number of keys to be freed */
2675     </entry>
2676   </row>
2677   <row>
2678     <entry role='functionargdecl'>
2679 Bool      <emphasis>
2680       free_all;</emphasis>
2681       /* <emphasis>
2682 True</emphasis>
2683  =&gt; all keys are freed */
2684     </entry>
2685 </row>
2686 </tbody>
2687 </tgroup>
2688 </informaltable>
2689
2690 <para>
2691 If free_all is <emphasis>
2692 True</emphasis>
2693 , all keys are freed regardless of the value of first or count. Otherwise,
2694 count keys are freed beginning with the one specified by first.
2695 </para>
2696
2697
2698 <para>
2699 To allocate geometry properties, use <emphasis>
2700 XkbAllocGeomProps</emphasis>
2701 .
2702 </para>
2703
2704
2705 <informaltable frame='none'>
2706 <?dbfo keep-together="always" ?>
2707 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2708 <colspec colname='c1' colwidth='1.0*'/>
2709 <tbody>
2710   <row>
2711     <entry role='functiondecl'>
2712 Status <emphasis>
2713 XkbAllocGeomProps</emphasis>
2714 (<emphasis>
2715 geom</emphasis>
2716 ,<emphasis>
2717  num_needed</emphasis>
2718 )
2719     </entry>
2720   </row>
2721   <row>
2722     <entry role='functionargdecl'>
2723 XkbGeometryPtr      <emphasis>
2724       geom</emphasis>
2725 ;      /* geometry for which properties should be allocated */
2726     </entry>
2727   </row>
2728   <row>
2729     <entry role='functionargdecl'>
2730 int      <emphasis>
2731       num_needed</emphasis>
2732 ;      /* number of new properties required */
2733     </entry>
2734 </row>
2735 </tbody>
2736 </tgroup>
2737 </informaltable>
2738
2739 <para>
2740 <emphasis>
2741 XkbAllocGeomProps</emphasis>
2742  allocates space for num_needed properties and adds them to the specified
2743 geometry <emphasis>
2744 geom</emphasis>
2745 . No initialization of the properties is done. A geometry property associates
2746 an arbitrary string with an equally arbitrary name. Geometry properties can be
2747 used to provide hints to programs that display images of keyboards, but they
2748 are not interpreted by Xkb. No other geometry structures refer to geometry
2749 properties.
2750 </para>
2751
2752
2753 <para>
2754 To free geometry properties, use <emphasis>
2755 XkbFreeGeomProperties</emphasis>
2756 .
2757 </para>
2758
2759
2760 <informaltable frame='none'>
2761 <?dbfo keep-together="always" ?>
2762 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2763 <colspec colname='c1' colwidth='1.0*'/>
2764 <tbody>
2765   <row>
2766     <entry role='functiondecl'>
2767 void <emphasis>
2768 XkbFreeGeomProperties</emphasis>
2769 (<emphasis>
2770 geom</emphasis>
2771 ,<emphasis>
2772  first</emphasis>
2773 ,<emphasis>
2774  count</emphasis>
2775 ,<emphasis>
2776  free_all</emphasis>
2777 )
2778     </entry>
2779   </row>
2780   <row>
2781     <entry role='functionargdecl'>
2782 XkbGeometryPtr      <emphasis>
2783       geom</emphasis>
2784 ;      /* geometry in which properties should be freed */
2785     </entry>
2786   </row>
2787   <row>
2788     <entry role='functionargdecl'>
2789 int      <emphasis>
2790       first</emphasis>
2791 ;      /* first property to be freed */
2792     </entry>
2793   </row>
2794   <row>
2795     <entry role='functionargdecl'>
2796 int      <emphasis>
2797       count</emphasis>
2798 ;      /* number of properties to be freed */
2799     </entry>
2800   </row>
2801   <row>
2802     <entry role='functionargdecl'>
2803 Bool      <emphasis>
2804       free_all;</emphasis>
2805       /* <emphasis>
2806 True</emphasis>
2807  =&gt; all properties are freed */
2808     </entry>
2809 </row>
2810 </tbody>
2811 </tgroup>
2812 </informaltable>
2813
2814 <para>
2815 If free_all is <emphasis>
2816 True</emphasis>
2817 , all properties are freed regardless of the value of first or count.
2818 Otherwise, count properties are freed beginning with the one specified by first.
2819 </para>
2820
2821
2822 <para>
2823 To allocate geometry key aliases, use <emphasis>
2824 XkbAllocGeomKeyAliases</emphasis>
2825 .
2826 </para>
2827
2828
2829 <informaltable frame='none'>
2830 <?dbfo keep-together="always" ?>
2831 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2832 <colspec colname='c1' colwidth='1.0*'/>
2833 <tbody>
2834   <row>
2835     <entry role='functiondecl'>
2836 Status <emphasis>
2837 XkbAllocGeomKeyAliases</emphasis>
2838 (<emphasis>
2839 geom</emphasis>
2840 ,<emphasis>
2841  num_needed</emphasis>
2842 )
2843     </entry>
2844   </row>
2845   <row>
2846     <entry role='functionargdecl'>
2847 XkbGeometryPtr      <emphasis>
2848       geom</emphasis>
2849 ;      /* geometry for which key aliases should be allocated */
2850     </entry>
2851   </row>
2852   <row>
2853     <entry role='functionargdecl'>
2854 int      <emphasis>
2855       num_needed</emphasis>
2856 ;      /* number of new key aliases required */
2857     </entry>
2858 </row>
2859 </tbody>
2860 </tgroup>
2861 </informaltable>
2862
2863 <para>
2864 <emphasis>
2865 XkbAllocGeomKeyAliases</emphasis>
2866  allocates space for num_needed key aliases and adds them to the specified
2867 geometry <emphasis>
2868 geom</emphasis>
2869 . A key alias is a pair of strings that associates an alternate name for a key
2870 with the real name for that key.
2871 </para>
2872
2873
2874 <para>
2875 To free geometry key aliases, use <emphasis>
2876 XkbFreeGeomKeyAliases</emphasis>
2877 .
2878 </para>
2879
2880
2881 <informaltable frame='none'>
2882 <?dbfo keep-together="always" ?>
2883 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2884 <colspec colname='c1' colwidth='1.0*'/>
2885 <tbody>
2886   <row>
2887     <entry role='functiondecl'>
2888 void <emphasis>
2889 XkbFreeGeomKeyAliases</emphasis>
2890 (<emphasis>
2891 geom</emphasis>
2892 ,<emphasis>
2893  first</emphasis>
2894 , <emphasis>
2895 count</emphasis>
2896 , <emphasis>
2897 free_all</emphasis>
2898 )
2899     </entry>
2900   </row>
2901   <row>
2902     <entry role='functionargdecl'>
2903 XkbGeometryPtr      <emphasis>
2904       geom</emphasis>
2905 ;      /* geometry in which key aliases should be freed */
2906     </entry>
2907   </row>
2908   <row>
2909     <entry role='functionargdecl'>
2910 int      <emphasis>
2911       first</emphasis>
2912 ;      /* first key alias to be freed */
2913     </entry>
2914   </row>
2915   <row>
2916     <entry role='functionargdecl'>
2917 int      <emphasis>
2918       count</emphasis>
2919 ;      /* number of key aliases to be freed */
2920     </entry>
2921   </row>
2922   <row>
2923     <entry role='functionargdecl'>
2924 Bool      <emphasis>
2925       free_all;</emphasis>
2926       /* <emphasis>
2927 True</emphasis>
2928  =&gt; all key aliases are freed */
2929     </entry>
2930 </row>
2931 </tbody>
2932 </tgroup>
2933 </informaltable>
2934
2935 <para>
2936 If free_all is <emphasis>
2937 True</emphasis>
2938 , all aliases in the top level of the specified geometry <emphasis>
2939 geom</emphasis>
2940  are freed regardless of the value of first or count. Otherwise, count aliases
2941 in <emphasis>
2942 geom</emphasis>
2943  are freed beginning with the one specified by first.
2944 </para>
2945
2946
2947 <para>
2948 To allocate geometry colors, use <emphasis>
2949 XkbAllocGeomColors</emphasis>
2950 .
2951 </para>
2952
2953
2954 <informaltable frame='none'>
2955 <?dbfo keep-together="always" ?>
2956 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2957 <colspec colname='c1' colwidth='1.0*'/>
2958 <tbody>
2959   <row>
2960     <entry role='functiondecl'>
2961 Status <emphasis>
2962 XkbAllocGeomColors</emphasis>
2963 (<emphasis>
2964 geom</emphasis>
2965 ,<emphasis>
2966  num_needed</emphasis>
2967 )
2968     </entry>
2969   </row>
2970   <row>
2971     <entry role='functionargdecl'>
2972 XkbGeometryPtr      <emphasis>
2973       geom</emphasis>
2974 ;      /* geometry for which colors should be allocated */
2975     </entry>
2976   </row>
2977   <row>
2978     <entry role='functionargdecl'>
2979 int      <emphasis>
2980       num_needed</emphasis>
2981 ;      /* number of new colors required. */
2982     </entry>
2983 </row>
2984 </tbody>
2985 </tgroup>
2986 </informaltable>
2987
2988 <para>
2989 <emphasis>
2990 XkbAllocGeomColors</emphasis>
2991  allocates space for num_needed colors and adds them to the specified geometry
2992 <emphasis>
2993 geom</emphasis>
2994 . A color name is a string whose interpretation is not specified by Xkb. All
2995 other geometry data structures refer to colors using their indices in this
2996 global list or pointers to colors in this list.
2997 </para>
2998
2999
3000 <para>
3001 To free geometry colors, use <emphasis>
3002 XkbFreeGeomColors</emphasis>
3003 .
3004 </para>
3005
3006
3007 <informaltable frame='none'>
3008 <?dbfo keep-together="always" ?>
3009 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3010 <colspec colname='c1' colwidth='1.0*'/>
3011 <tbody>
3012   <row>
3013     <entry role='functiondecl'>
3014 void <emphasis>
3015 XkbFreeGeomColors</emphasis>
3016 (<emphasis>
3017 geom</emphasis>
3018 ,<emphasis>
3019  first</emphasis>
3020 ,<emphasis>
3021  count</emphasis>
3022 ,<emphasis>
3023  free_all</emphasis>
3024 )
3025     </entry>
3026   </row>
3027   <row>
3028     <entry role='functionargdecl'>
3029 XkbGeometryPtr      <emphasis>
3030       geom</emphasis>
3031 ;      /* geometry in which colors should be freed */
3032     </entry>
3033   </row>
3034   <row>
3035     <entry role='functionargdecl'>
3036 int      <emphasis>
3037       first</emphasis>
3038 ;      /* first color to be freed */
3039     </entry>
3040   </row>
3041   <row>
3042     <entry role='functionargdecl'>
3043 int      <emphasis>
3044       count</emphasis>
3045 ;      /* number of colors to be freed */
3046     </entry>
3047   </row>
3048   <row>
3049     <entry role='functionargdecl'>
3050 Bool      <emphasis>
3051       free_all;</emphasis>
3052       /* <emphasis>
3053 True</emphasis>
3054  =&gt; all colors are freed */
3055     </entry>
3056 </row>
3057 </tbody>
3058 </tgroup>
3059 </informaltable>
3060
3061 <para>
3062 If free_all is <emphasis>
3063 True</emphasis>
3064 , all colors are freed regardless of the value of first or count. Otherwise,
3065 count colors are freed beginning with the one specified by first.
3066 </para>
3067
3068
3069 <para>
3070 To allocate points in an outline, use <emphasis>
3071 XkbAllocGeomPoints</emphasis>
3072 .
3073 </para>
3074
3075
3076 <informaltable frame='none'>
3077 <?dbfo keep-together="always" ?>
3078 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3079 <colspec colname='c1' colwidth='1.0*'/>
3080 <tbody>
3081   <row>
3082     <entry role='functiondecl'>
3083 Status <emphasis>
3084 XkbAllocGeomPoints</emphasis>
3085 (<emphasis>
3086 outline</emphasis>
3087 ,<emphasis>
3088  num_needed</emphasis>
3089 )
3090     </entry>
3091   </row>
3092   <row>
3093     <entry role='functionargdecl'>
3094 XkbOutlinePtr      <emphasis>
3095       outline</emphasis>
3096 ;      /* outline for which points should be allocated */
3097     </entry>
3098   </row>
3099   <row>
3100     <entry role='functionargdecl'>
3101 int      <emphasis>
3102       num_needed</emphasis>
3103 ;      /* number of new points required */
3104     </entry>
3105 </row>
3106 </tbody>
3107 </tgroup>
3108 </informaltable>
3109
3110 <para>
3111 <emphasis>
3112 XkbAllocGeomPoints</emphasis>
3113  allocates space for <emphasis>
3114 num_needed</emphasis>
3115  points in the specified <emphasis>
3116 outline</emphasis>
3117 . The points are not initialized.
3118 </para>
3119
3120
3121 <para>
3122 To free points in a outline, use <emphasis>
3123 XkbFreeGeomPoints</emphasis>
3124 .
3125 </para>
3126
3127
3128 <informaltable frame='none'>
3129 <?dbfo keep-together="always" ?>
3130 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3131 <colspec colname='c1' colwidth='1.0*'/>
3132 <tbody>
3133   <row>
3134     <entry role='functiondecl'>
3135 void <emphasis>
3136 XkbFreeGeomPoints</emphasis>
3137 (<emphasis>
3138 outline</emphasis>
3139 ,<emphasis>
3140  first</emphasis>
3141 ,<emphasis>
3142  count</emphasis>
3143 ,<emphasis>
3144  free_all</emphasis>
3145 )
3146     </entry>
3147   </row>
3148   <row>
3149     <entry role='functionargdecl'>
3150 XkbOutlinePtr      <emphasis>
3151       outline</emphasis>
3152 ;      /* outline in which points should be freed */
3153     </entry>
3154   </row>
3155   <row>
3156     <entry role='functionargdecl'>
3157 int      <emphasis>
3158       first</emphasis>
3159 ;      /* first point to be freed. */
3160     </entry>
3161   </row>
3162   <row>
3163     <entry role='functionargdecl'>
3164 int      <emphasis>
3165       count</emphasis>
3166 ;      /* number of points to be freed */
3167     </entry>
3168   </row>
3169   <row>
3170     <entry role='functionargdecl'>
3171 Bool      <emphasis>
3172       free_all;</emphasis>
3173       /* <emphasis>
3174 True</emphasis>
3175  =&gt; all points are freed */
3176     </entry>
3177 </row>
3178 </tbody>
3179 </tgroup>
3180 </informaltable>
3181
3182 <para>
3183 If free_all is <emphasis>
3184 True</emphasis>
3185 , all points are freed regardless of the value of first and count. Otherwise,
3186 the number of points specified by count are freed, beginning with the point
3187 specified by first in the specified outline.
3188 </para>
3189
3190
3191 <para>
3192 To allocate space for an arbitrary number of geometry shapes, use <emphasis>
3193 XkbAllocGeomShapes</emphasis>
3194 .
3195 </para>
3196
3197
3198 <informaltable frame='none'>
3199 <?dbfo keep-together="always" ?>
3200 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3201 <colspec colname='c1' colwidth='1.0*'/>
3202 <tbody>
3203   <row>
3204     <entry role='functiondecl'>
3205 Status <emphasis>
3206 XkbAllocGeomShapes</emphasis>
3207 (<emphasis>
3208 geom</emphasis>
3209 ,<emphasis>
3210  num_needed</emphasis>
3211 )
3212     </entry>
3213   </row>
3214   <row>
3215     <entry role='functionargdecl'>
3216 XkbGeometryPtr      <emphasis>
3217       geom</emphasis>
3218 ;      /* geometry for which shapes should be allocated */
3219     </entry>
3220   </row>
3221   <row>
3222     <entry role='functionargdecl'>
3223 int      <emphasis>
3224       num_needed</emphasis>
3225 ;      /* number of new shapes required */
3226     </entry>
3227 </row>
3228 </tbody>
3229 </tgroup>
3230 </informaltable>
3231
3232 <para>
3233 <emphasis>
3234 XkbAllocGeomShapes</emphasis>
3235  allocates space for <emphasis>
3236 num_needed</emphasis>
3237  shapes in the specified geometry <emphasis>
3238 geom</emphasis>
3239 . The shapes are not initialized.
3240 </para>
3241
3242
3243 <para>
3244 To free geometry shapes, use <emphasis>
3245 XkbFreeGeomShapes</emphasis>
3246 .
3247 </para>
3248
3249
3250 <informaltable frame='none'>
3251 <?dbfo keep-together="always" ?>
3252 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3253 <colspec colname='c1' colwidth='1.0*'/>
3254 <tbody>
3255   <row>
3256     <entry role='functiondecl'>
3257 void <emphasis>
3258 XkbFreeGeomShapes</emphasis>
3259 (<emphasis>
3260 geom</emphasis>
3261 ,<emphasis>
3262  first</emphasis>
3263 ,<emphasis>
3264  count</emphasis>
3265 ,<emphasis>
3266  f ree_all</emphasis>
3267 )
3268     </entry>
3269   </row>
3270   <row>
3271     <entry role='functionargdecl'>
3272 XkbGeometryPtr      <emphasis>
3273       geom</emphasis>
3274 ;      /* geometry in which shapes should be freed */
3275     </entry>
3276   </row>
3277   <row>
3278     <entry role='functionargdecl'>
3279 int      <emphasis>
3280       first</emphasis>
3281 ;      /* first shape to be freed */
3282     </entry>
3283   </row>
3284   <row>
3285     <entry role='functionargdecl'>
3286 int      <emphasis>
3287       count</emphasis>
3288 ;      /* number of shapes to be freed */
3289     </entry>
3290   </row>
3291   <row>
3292     <entry role='functionargdecl'>
3293 Bool      <emphasis>
3294       free_all;</emphasis>
3295       /* <emphasis>
3296 True</emphasis>
3297  =&gt; all shapes are freed */
3298     </entry>
3299 </row>
3300 </tbody>
3301 </tgroup>
3302 </informaltable>
3303
3304 <para>
3305 If free_all is <emphasis>
3306 True</emphasis>
3307 , all shapes in the geometry are freed regardless of the values of first and
3308 count. Otherwise, count shapes are freed, beginning with the shape specified by
3309 first.
3310 </para>
3311
3312
3313 <para>
3314 To allocate geometry sections, use <emphasis>
3315 XkbAllocGeomSections</emphasis>
3316 .
3317 </para>
3318
3319
3320 <informaltable frame='none'>
3321 <?dbfo keep-together="always" ?>
3322 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3323 <colspec colname='c1' colwidth='1.0*'/>
3324 <tbody>
3325   <row>
3326     <entry role='functiondecl'>
3327 Status <emphasis>
3328 XkbAllocGeomSections</emphasis>
3329 (<emphasis>
3330 geom</emphasis>
3331 ,<emphasis>
3332  num_needed</emphasis>
3333 )
3334     </entry>
3335   </row>
3336   <row>
3337     <entry role='functionargdecl'>
3338 XkbGeometryPtr      <emphasis>
3339       geom</emphasis>
3340 ;      /*geometry for which sections should be allocated */
3341     </entry>
3342   </row>
3343   <row>
3344     <entry role='functionargdecl'>
3345 int      <emphasis>
3346       num_needed</emphasis>
3347 ;      /* number of new sections required */
3348     </entry>
3349 </row>
3350 </tbody>
3351 </tgroup>
3352 </informaltable>
3353
3354 <para>
3355 <emphasis>
3356 XkbAllocGeomSections</emphasis>
3357  allocates num_needed sections and adds them to the geometry geom. No
3358 initialization of the sections is done.
3359 </para>
3360
3361
3362 <para>
3363 To free geometry sections, use <emphasis>
3364 XkbFreeGeomSections</emphasis>
3365 .
3366 </para>
3367
3368
3369 <informaltable frame='none'>
3370 <?dbfo keep-together="always" ?>
3371 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3372 <colspec colname='c1' colwidth='1.0*'/>
3373 <tbody>
3374   <row>
3375     <entry role='functiondecl'>
3376 void <emphasis>
3377 XkbFreeGeomSections</emphasis>
3378 (<emphasis>
3379 geom</emphasis>
3380 ,<emphasis>
3381  first</emphasis>
3382 ,<emphasis>
3383  count</emphasis>
3384 ,<emphasis>
3385  free_all</emphasis>
3386 )
3387     </entry>
3388   </row>
3389   <row>
3390     <entry role='functionargdecl'>
3391 XkbGeometryPtr      <emphasis>
3392       geom</emphasis>
3393 ;      /* geometry in which sections should be freed */
3394     </entry>
3395   </row>
3396   <row>
3397     <entry role='functionargdecl'>
3398 int      <emphasis>
3399       first</emphasis>
3400 ;      /* first section to be freed. */
3401     </entry>
3402   </row>
3403   <row>
3404     <entry role='functionargdecl'>
3405 int      <emphasis>
3406       count</emphasis>
3407 ;      /* number of sections to be freed */
3408     </entry>
3409   </row>
3410   <row>
3411     <entry role='functionargdecl'>
3412 Bool      <emphasis>
3413       free_all;</emphasis>
3414       /* <emphasis>
3415 True</emphasis>
3416  =&gt; all sections are freed */
3417     </entry>
3418 </row>
3419 </tbody>
3420 </tgroup>
3421 </informaltable>
3422
3423 <para>
3424 If free_all is <emphasis>
3425 True</emphasis>
3426 , all sections are freed regardless of the value of first and count. Otherwise,
3427 the number of sections specified by count are freed, beginning with the section
3428 specified by first in the specified geometry.
3429 </para>
3430
3431
3432 <para>
3433 To allocate rows in a section, use <emphasis>
3434 XkbAllocGeomRows</emphasis>
3435 .
3436 </para>
3437
3438
3439 <informaltable frame='none'>
3440 <?dbfo keep-together="always" ?>
3441 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3442 <colspec colname='c1' colwidth='1.0*'/>
3443 <tbody>
3444   <row>
3445     <entry role='functiondecl'>
3446 Status <emphasis>
3447 XkbAllocGeomRows</emphasis>
3448 (<emphasis>
3449 section</emphasis>
3450 ,<emphasis>
3451  num_needed</emphasis>
3452 )
3453     </entry>
3454   </row>
3455   <row>
3456     <entry role='functionargdecl'>
3457 XkbSectionPtr            <emphasis>
3458 section</emphasis>
3459 ;      /* section for which rows should be allocated */
3460     </entry>
3461   </row>
3462   <row>
3463     <entry role='functionargdecl'>
3464 int      <emphasis>
3465       num_needed</emphasis>
3466 ;      /* number of new rows required */
3467     </entry>
3468 </row>
3469 </tbody>
3470 </tgroup>
3471 </informaltable>
3472
3473 <para>
3474 <emphasis>
3475 XkbAllocGeomRows</emphasis>
3476  allocates num_needed rows and adds them to the section. No initialization of
3477 the rows is done.
3478 </para>
3479
3480
3481 <para>
3482 To free rows in a section, use <emphasis>
3483 XkbFreeGeomRows</emphasis>
3484 .
3485 </para>
3486
3487
3488 <informaltable frame='none'>
3489 <?dbfo keep-together="always" ?>
3490 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3491 <colspec colname='c1' colwidth='1.0*'/>
3492 <tbody>
3493   <row>
3494     <entry role='functiondecl'>
3495 void <emphasis>
3496 XkbFreeGeomRows</emphasis>
3497 (<emphasis>
3498 section</emphasis>
3499 ,<emphasis>
3500  first</emphasis>
3501 ,<emphasis>
3502  count</emphasis>
3503 ,<emphasis>
3504  free_all</emphasis>
3505 )
3506     </entry>
3507   </row>
3508   <row>
3509     <entry role='functionargdecl'>
3510 XkbSectionPtr      <emphasis>
3511       section</emphasis>
3512 ;      /* section in which rows should be freed */
3513     </entry>
3514   </row>
3515   <row>
3516     <entry role='functionargdecl'>
3517 int      <emphasis>
3518       first</emphasis>
3519 ;      /* first row to be freed. */
3520     </entry>
3521   </row>
3522   <row>
3523     <entry role='functionargdecl'>
3524 int      <emphasis>
3525       count</emphasis>
3526 ;      /* number of rows to be freed */
3527     </entry>
3528   </row>
3529   <row>
3530     <entry role='functionargdecl'>
3531 Bool      <emphasis>
3532       free_all;</emphasis>
3533       /* <emphasis>
3534 True</emphasis>
3535  =&gt; all rows are freed */
3536     </entry>
3537 </row>
3538 </tbody>
3539 </tgroup>
3540 </informaltable>
3541
3542 <para>
3543 If free_all is <emphasis>
3544 True</emphasis>
3545 , all rows are freed regardless of the value of first and count. Otherwise, the
3546 number of rows specified by count are freed, beginning with the row specified
3547 by first in the specified section.
3548 </para>
3549
3550
3551 <para>
3552 To allocate overlays in a section, use <emphasis>
3553 XkbAllocGeomOverlays</emphasis>
3554 .
3555 </para>
3556
3557
3558 <informaltable frame='none'>
3559 <?dbfo keep-together="always" ?>
3560 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3561 <colspec colname='c1' colwidth='1.0*'/>
3562 <tbody>
3563   <row>
3564     <entry role='functiondecl'>
3565 Status <emphasis>
3566 XkbAllocGeomOverlays</emphasis>
3567 (<emphasis>
3568 section</emphasis>
3569 ,<emphasis>
3570  num_needed</emphasis>
3571 )
3572     </entry>
3573   </row>
3574   <row>
3575     <entry role='functionargdecl'>
3576 XkbSectionPtr            <emphasis>
3577 section</emphasis>
3578 ;      /* section for which overlays should be allocated */
3579     </entry>
3580   </row>
3581   <row>
3582     <entry role='functionargdecl'>
3583 int      <emphasis>
3584       num_needed</emphasis>
3585 ;      /* number of new overlays required */
3586     </entry>
3587 </row>
3588 </tbody>
3589 </tgroup>
3590 </informaltable>
3591
3592 <para>
3593 <emphasis>
3594 XkbAllocGeomRows</emphasis>
3595  allocates num_needed overlays and adds them to the section. No initialization
3596 of the overlays is done.
3597 </para>
3598
3599
3600 <para>
3601 To free rows in an section, use <emphasis>
3602 XkbFreeGeomOverlays</emphasis>
3603 .
3604 </para>
3605
3606
3607 <informaltable frame='none'>
3608 <?dbfo keep-together="always" ?>
3609 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3610 <colspec colname='c1' colwidth='1.0*'/>
3611 <tbody>
3612   <row>
3613     <entry role='functiondecl'>
3614 void <emphasis>
3615 XkbFreeGeomOverlays</emphasis>
3616 (<emphasis>
3617 section</emphasis>
3618 ,<emphasis>
3619  first</emphasis>
3620 ,<emphasis>
3621  count</emphasis>
3622 ,<emphasis>
3623  free_all</emphasis>
3624 )
3625     </entry>
3626   </row>
3627   <row>
3628     <entry role='functionargdecl'>
3629 XkbSectionPtr      <emphasis>
3630       section</emphasis>
3631 ;      /* section in which overlays should be freed */
3632     </entry>
3633   </row>
3634   <row>
3635     <entry role='functionargdecl'>
3636 int      <emphasis>
3637       first</emphasis>
3638 ;      /* first overlay to be freed. */
3639     </entry>
3640   </row>
3641   <row>
3642     <entry role='functionargdecl'>
3643 int      <emphasis>
3644       count</emphasis>
3645 ;      /* number of overlays to be freed */
3646     </entry>
3647   </row>
3648   <row>
3649     <entry role='functionargdecl'>
3650 Bool      <emphasis>
3651       free_all;</emphasis>
3652       /* <emphasis>
3653 True</emphasis>
3654  =&gt; all overlays are freed */
3655     </entry>
3656 </row>
3657 </tbody>
3658 </tgroup>
3659 </informaltable>
3660
3661 <para>
3662 If free_all is <emphasis>
3663 True</emphasis>
3664 , all overlays are freed regardless of the value of first and count. Otherwise,
3665 the number of overlays specified by count are freed, beginning with the overlay
3666 specified by first in the specified section.
3667 </para>
3668
3669
3670 <para>
3671 To allocate rows in a overlay, use <emphasis>
3672 XkbAllocGeomOverlayRows</emphasis>
3673 .
3674 </para>
3675
3676
3677 <informaltable frame='none'>
3678 <?dbfo keep-together="always" ?>
3679 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3680 <colspec colname='c1' colwidth='1.0*'/>
3681 <tbody>
3682   <row>
3683     <entry role='functiondecl'>
3684 Status <emphasis>
3685 XkbAllocGeomOverlayRows</emphasis>
3686 (<emphasis>
3687 overlay</emphasis>
3688 ,<emphasis>
3689  num_needed</emphasis>
3690 )
3691     </entry>
3692   </row>
3693   <row>
3694     <entry role='functionargdecl'>
3695 XkbSectionPtr            <emphasis>
3696 overlay</emphasis>
3697 ;      /* section for which rows should be allocated */
3698     </entry>
3699   </row>
3700   <row>
3701     <entry role='functionargdecl'>
3702 int      <emphasis>
3703       num_needed</emphasis>
3704 ;      /* number of new rows required */
3705     </entry>
3706 </row>
3707 </tbody>
3708 </tgroup>
3709 </informaltable>
3710
3711 <para>
3712 <emphasis>
3713 XkbAllocGeomOverlayRows</emphasis>
3714  allocates num_needed rows and adds them to the overlay. No initialization of
3715 the rows is done.
3716 </para>
3717
3718
3719 <para>
3720 To free rows in an overlay, use <emphasis>
3721 XkbFreeGeomOverlayRows</emphasis>
3722 .
3723 </para>
3724
3725
3726 <informaltable frame='none'>
3727 <?dbfo keep-together="always" ?>
3728 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3729 <colspec colname='c1' colwidth='1.0*'/>
3730 <tbody>
3731   <row>
3732     <entry role='functiondecl'>
3733 void <emphasis>
3734 XkbFreeGeomOverlayRows</emphasis>
3735 (<emphasis>
3736 overlay</emphasis>
3737 ,<emphasis>
3738  first</emphasis>
3739 ,<emphasis>
3740  count</emphasis>
3741 ,<emphasis>
3742  free_all</emphasis>
3743 )
3744     </entry>
3745   </row>
3746   <row>
3747     <entry role='functionargdecl'>
3748 XkbSectionPtr      <emphasis>
3749       overlay</emphasis>
3750 ;      /* section in which rows should be freed */
3751     </entry>
3752   </row>
3753   <row>
3754     <entry role='functionargdecl'>
3755 int      <emphasis>
3756       first</emphasis>
3757 ;      /* first row to be freed. */
3758     </entry>
3759   </row>
3760   <row>
3761     <entry role='functionargdecl'>
3762 int      <emphasis>
3763       count</emphasis>
3764 ;      /* number of rows to be freed */
3765     </entry>
3766   </row>
3767   <row>
3768     <entry role='functionargdecl'>
3769 Bool      <emphasis>
3770       free_all;</emphasis>
3771       /* <emphasis>
3772 True</emphasis>
3773  =&gt; all rows are freed */
3774     </entry>
3775 </row>
3776 </tbody>
3777 </tgroup>
3778 </informaltable>
3779
3780 <para>
3781 If free_all is <emphasis>
3782 True</emphasis>
3783 , all rows are freed regardless of the value of first and count. Otherwise, the
3784 number of rows specified by count are freed, beginning with the row specified
3785 by first in the specified overlay.
3786 </para>
3787
3788
3789 <para>
3790 To allocate keys in an overlay row, use <emphasis>
3791 XkbAllocGeomOverlayKeys</emphasis>
3792 .
3793 </para>
3794
3795
3796 <informaltable frame='none'>
3797 <?dbfo keep-together="always" ?>
3798 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3799 <colspec colname='c1' colwidth='1.0*'/>
3800 <tbody>
3801   <row>
3802     <entry role='functiondecl'>
3803 Status <emphasis>
3804 XkbAllocGeomOverlayKeys</emphasis>
3805 (<emphasis>
3806 row</emphasis>
3807 ,<emphasis>
3808  num_needed</emphasis>
3809 )
3810     </entry>
3811   </row>
3812   <row>
3813     <entry role='functionargdecl'>
3814 XkbRowPtr            <emphasis>
3815 row</emphasis>
3816 ;      /* section for which rows should be allocated */
3817     </entry>
3818   </row>
3819   <row>
3820     <entry role='functionargdecl'>
3821 int      <emphasis>
3822       num_needed</emphasis>
3823 ;      /* number of new rows required */
3824     </entry>
3825 </row>
3826 </tbody>
3827 </tgroup>
3828 </informaltable>
3829
3830 <para>
3831 <emphasis>
3832 XkbAllocGeomOverlayKeys</emphasis>
3833  allocates num_needed keys and adds them to the row. No initialization of the
3834 keys is done.
3835 </para>
3836
3837
3838 <para>
3839 To free keys in an overlay row, use <emphasis>
3840 XkbFreeGeomOverlayKeys</emphasis>
3841 .
3842 </para>
3843
3844
3845 <informaltable frame='none'>
3846 <?dbfo keep-together="always" ?>
3847 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3848 <colspec colname='c1' colwidth='1.0*'/>
3849 <tbody>
3850   <row>
3851     <entry role='functiondecl'>
3852 void <emphasis>
3853 XkbFreeGeomOverlayKeys</emphasis>
3854 (<emphasis>
3855 row</emphasis>
3856 ,<emphasis>
3857  first</emphasis>
3858 ,<emphasis>
3859  count</emphasis>
3860 ,<emphasis>
3861  free_all</emphasis>
3862 )
3863     </entry>
3864   </row>
3865   <row>
3866     <entry role='functionargdecl'>
3867 XkbRowPtr      <emphasis>
3868       row</emphasis>
3869 ;      /* row in which keys should be freed */
3870     </entry>
3871   </row>
3872   <row>
3873     <entry role='functionargdecl'>
3874 int      <emphasis>
3875       first</emphasis>
3876 ;      /* first key to be freed. */
3877     </entry>
3878   </row>
3879   <row>
3880     <entry role='functionargdecl'>
3881 int      <emphasis>
3882       count</emphasis>
3883 ;      /* number of keys to be freed */
3884     </entry>
3885   </row>
3886   <row>
3887     <entry role='functionargdecl'>
3888 Bool      <emphasis>
3889       free_all;</emphasis>
3890       /* <emphasis>
3891 True</emphasis>
3892  =&gt; all keys are freed */
3893     </entry>
3894 </row>
3895 </tbody>
3896 </tgroup>
3897 </informaltable>
3898
3899 <para>
3900 If free_all is <emphasis>
3901 True</emphasis>
3902 , all keys are freed regardless of the value of first and count. Otherwise, the
3903 number of keys specified by count are freed, beginning with the key specified
3904 by first in the specified row.
3905 </para>
3906
3907
3908 <para>
3909 To allocate doodads that are global to a keyboard geometry, use <emphasis>
3910 XkbAllocGeomDoodads</emphasis>
3911 .
3912 </para>
3913
3914
3915 <informaltable frame='none'>
3916 <?dbfo keep-together="always" ?>
3917 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3918 <colspec colname='c1' colwidth='1.0*'/>
3919 <tbody>
3920   <row>
3921     <entry role='functiondecl'>
3922 Status <emphasis>
3923 XkbAllocGeomDoodads</emphasis>
3924 (<emphasis>
3925 geom</emphasis>
3926 ,<emphasis>
3927  num_needed</emphasis>
3928 )
3929     </entry>
3930   </row>
3931   <row>
3932     <entry role='functionargdecl'>
3933 XkbGeometryPtr      <emphasis>
3934       geom</emphasis>
3935 ;      /* geometry for which doodads should be allocated */
3936     </entry>
3937   </row>
3938   <row>
3939     <entry role='functionargdecl'>
3940 int      <emphasis>
3941       num_needed</emphasis>
3942 ;      /* number of new doodads required */
3943     </entry>
3944 </row>
3945 </tbody>
3946 </tgroup>
3947 </informaltable>
3948
3949 <para>
3950 <emphasis>
3951 XkbAllocGeomDoodads</emphasis>
3952  allocates num_needed doodads and adds them to the specified geometry <emphasis>
3953 geom</emphasis>
3954 . No initialization of the doodads is done.
3955 </para>
3956
3957
3958 <para>
3959 To allocate doodads that are specific to a section, use <emphasis>
3960 XkbAllocGeomSectionDoodads</emphasis>
3961 .
3962 </para>
3963
3964
3965 <informaltable frame='none'>
3966 <?dbfo keep-together="always" ?>
3967 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3968 <colspec colname='c1' colwidth='1.0*'/>
3969 <tbody>
3970   <row>
3971     <entry role='functiondecl'>
3972 Status <emphasis>
3973 XkbAllocGeomSectionDoodads</emphasis>
3974 (<emphasis>
3975 section</emphasis>
3976 ,<emphasis>
3977  num_needed</emphasis>
3978 )
3979     </entry>
3980   </row>
3981   <row>
3982     <entry role='functionargdecl'>
3983 XkbSectionPtr      <emphasis>
3984       section</emphasis>
3985 ;      /* section for which doodads should be allocated */
3986     </entry>
3987   </row>
3988   <row>
3989     <entry role='functionargdecl'>
3990 int      <emphasis>
3991       num_needed</emphasis>
3992 ;      /* number of new doodads required */
3993     </entry>
3994 </row>
3995 </tbody>
3996 </tgroup>
3997 </informaltable>
3998
3999 <para>
4000 <emphasis>
4001 XkbAllocGeomSectionDoodads</emphasis>
4002  allocates num_needed doodads and adds them to the specified <emphasis>
4003 section</emphasis>
4004 . No initialization of the doodads is done.
4005 </para>
4006
4007
4008 <para>
4009 To free geometry doodads, use <emphasis>
4010 XkbFreeGeomDoodads</emphasis>
4011 .
4012 </para>
4013
4014
4015 <informaltable frame='none'>
4016 <?dbfo keep-together="always" ?>
4017 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
4018 <colspec colname='c1' colwidth='1.0*'/>
4019 <tbody>
4020   <row>
4021     <entry role='functiondecl'>
4022 void <emphasis>
4023 XkbFreeGeomDoodads</emphasis>
4024 (<emphasis>
4025 doodads</emphasis>
4026 ,<emphasis>
4027  count</emphasis>
4028 ,<emphasis>
4029  free_all</emphasis>
4030 )
4031     </entry>
4032   </row>
4033   <row>
4034     <entry role='functionargdecl'>
4035 XkbDoodadPtr      <emphasis>
4036       doodads</emphasis>
4037 ;      /* doodads to be freed */
4038     </entry>
4039   </row>
4040   <row>
4041     <entry role='functionargdecl'>
4042 int      <emphasis>
4043       count</emphasis>
4044 ;      /* number of doodads to be freed */
4045     </entry>
4046   </row>
4047   <row>
4048     <entry role='functionargdecl'>
4049 Bool      <emphasis>
4050       free_all;</emphasis>
4051       /* <emphasis>
4052 True</emphasis>
4053  =&gt; all doodads are freed */
4054     </entry>
4055 </row>
4056 </tbody>
4057 </tgroup>
4058 </informaltable>
4059
4060 <para>
4061 If <emphasis>
4062 free_all</emphasis>
4063  is <emphasis>
4064 True</emphasis>
4065 , all doodads in the array are freed, regardless of the value of count.
4066 Otherwise, count doodads are freed.
4067 </para>
4068
4069
4070 <para>
4071 To allocate an entire geometry, use <emphasis>
4072 XkbAllocGeometry</emphasis>
4073 .
4074 </para>
4075
4076
4077 <informaltable frame='none'>
4078 <?dbfo keep-together="always" ?>
4079 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
4080 <colspec colname='c1' colwidth='1.0*'/>
4081 <tbody>
4082   <row>
4083     <entry role='functiondecl'>
4084 Status <emphasis>
4085 XkbAllocGeometry</emphasis>
4086 (<emphasis>
4087 xkb</emphasis>
4088 ,<emphasis>
4089  sizes</emphasis>
4090 )
4091     </entry>
4092   </row>
4093   <row>
4094     <entry role='functionargdecl'>
4095 XkbDescPtr      <emphasis>
4096       xkb</emphasis>
4097 ;      /* keyboard description for which geometry is to be allocated */
4098     </entry>
4099   </row>
4100   <row>
4101     <entry role='functionargdecl'>
4102 XkbGeometrySizesPtr<emphasis>
4103             sizes</emphasis>
4104 ;      /* initial sizes for all geometry components */
4105     </entry>
4106 </row>
4107 </tbody>
4108 </tgroup>
4109 </informaltable>
4110
4111 <para>
4112 <emphasis>
4113 XkbAllocGeometry</emphasis>
4114  allocates a keyboard geometry and adds it to the keyboard description
4115 specified by xkb. The keyboard description should be obtained via the
4116 XkbGetKeyboard or XkbAllockeyboard functions. The sizes parameter specifies the
4117 number of elements to be reserved for the subcomponents of the keyboard
4118 geometry and can be zero or more. These subcomponents include the properties,
4119 colors, shapes, sections, and doodads.
4120 </para>
4121
4122
4123 <para>
4124 To free an entire geometry, use <emphasis>
4125 XkbFreeGeometry</emphasis>
4126 .
4127 </para>
4128
4129
4130 <informaltable frame='none'>
4131 <?dbfo keep-together="always" ?>
4132 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
4133 <colspec colname='c1' colwidth='1.0*'/>
4134 <tbody>
4135   <row>
4136     <entry role='functiondecl'>
4137 void <emphasis>
4138 XkbFreeGeometry</emphasis>
4139 (<emphasis>
4140 geom</emphasis>
4141 ,<emphasis>
4142  which</emphasis>
4143 ,<emphasis>
4144  free_all</emphasis>
4145 )
4146     </entry>
4147   </row>
4148   <row>
4149     <entry role='functionargdecl'>
4150 XkbGeometryPtr      <emphasis>
4151       geom</emphasis>
4152 ;      /* geometry to be freed */
4153     </entry>
4154   </row>
4155   <row>
4156     <entry role='functionargdecl'>
4157 unsigned int      <emphasis>
4158       which</emphasis>
4159 ;      /* mask of geometry components to be freed */
4160     </entry>
4161   </row>
4162   <row>
4163     <entry role='functionargdecl'>
4164 Bool      <emphasis>
4165       free_all;</emphasis>
4166       /* <emphasis>
4167 True</emphasis>
4168  =&gt; the entire geometry is freed. */
4169     </entry>
4170 </row>
4171 </tbody>
4172 </tgroup>
4173 </informaltable>
4174
4175 <para>
4176 The values of which and free_all determine how much of the specified geometry
4177 is freed. The valid values for which are:
4178 </para>
4179
4180 <para><programlisting>
4181 #define      XkbGeomPropertiesMask  (1&lt;&lt;0)
4182 #define      XkbGeomColorsMask      (1&lt;&lt;1)
4183 #define      XkbGeomShapesMask      (1&lt;&lt;2)
4184 #define      XkbGeomSectionsMask    (1&lt;&lt;3)
4185 #define      XkbGeomDoodadsMask     (1&lt;&lt;4)
4186 #define      XkbGeomAllMask         (0x1f)
4187 </programlisting></para>
4188
4189 <para>
4190 If free_all is <emphasis>
4191 True</emphasis>
4192 , the entire geometry is freed regardless of the value of which. Otherwise, the
4193 portions of the geometry specified by which are freed.
4194 </para>
4195
4196 </sect1>
4197 </chapter>