1 <chapter id='Keyboard_Geometry'>
2 <title>Keyboard Geometry</title>
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.
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.
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>
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.
35 <imageobject> <imagedata format="SVG" fileref="XKBlib-7.svg"/>
37 <caption>Rotated Keyboard Sections</caption>
41 <!-- <H5 CLASS="Figure">
42 Rotated Keyboard Sections</H5>
46 Some geometry components include a <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).
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:
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)
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
76 A list of the keyboard’s sections and nonkey doodads
82 The top-level geometry is described in more detail in the following.
87 The lists of items used by components of the keyboard geometry description is
94 The top-level keyboard geometry description includes a list of up to <emphasis>
97 color names</emphasis>
98 . A color name is a string whose interpretation is not specified by Xkb. The
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.
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
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
122 LBL_PAUS = "{Pause/top/black,Break/front/red}"
125 and use the property information to draw the key with a front label as well as
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.
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>
141 xkb->names</emphasis>
142 ). Therefore, consider the key aliases defined by the geometry before
143 considering key aliases supplied by the keycodes.</para></note>
147 The top-level keyboard geometry description includes a list of <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
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>
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.
173 XkbGeometryRec</emphasis>
174 top-level geometry description contains the following information that
175 pertains to the keyboard as a whole:
182 keyboard symbolic name</emphasis>
183 of type Atom to help users identify the keyboard.
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.
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.
207 label color</emphasis>
208 is the color used to draw the labels on most of the keyboard keys.
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.
223 The keyboard is subdivided into named <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>
232 describes some visible aspect of the keyboard that is not a key and is not a
237 <imageobject> <imagedata format="SVG" fileref="XKBlib-8.svg"/>
239 <caption>Keyboard with Four Sections</caption>
244 Keyboard with Four Sections</H5>
247 <sect1 id='Shapes_and_Outlines'>
248 <title>Shapes and Outlines</title>
253 , used to draw keyboard components and stored in a <emphasis>
254 XkbShapeRec</emphasis>
261 An arbitrary name of type Atom.
266 Bounds (two x and y coordinates) that describe the corners of a rectangle
267 containing the shape’s top surface outline.
272 A list of one or more outlines (described below).
277 Optional pointers to a primary and an approximation outline (described below).
278 If either of these pointers is <emphasis>
280 , the default primary/approximation outline is the first one in the list of
281 outlines for the shape.
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:
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.
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
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
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.
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.
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>
338 field of the <emphasis>
339 XkbShapeRec</emphasis>
340 structure is not <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.
351 <sect1 id='Sections'>
352 <title>Sections</title>
355 As previously noted, a keyboard is subdivided into <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>
368 An arbitrary name of type Atom.
373 A priority, to indicate drawing order. 0 is the highest priority, 255 the
379 Origin of the section, relative to the origin of the keyboard.
384 The width and height and the angle of rotation.
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.
402 <imageobject> <imagedata format="SVG" fileref="XKBlib-9.svg"/>
404 <caption>Rows in a Section</caption>
411 Rows in a Section</H5>
416 An optional list of <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.
426 An optional <emphasis>
428 with a name of type Atom and a list of overlay rows (described below).
433 Bounds (two x and y coordinates) that describe the corners of a rectangle
434 containing the entire section.
439 <sect1 id='Rows_and_Keys'>
440 <title>Rows and Keys</title>
443 A row description (<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
452 A key description (<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
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.
468 <title>Doodads</title>
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
479 Each doodad’s origin is stored in fields named <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
491 field, which specifies the type of doodad.
495 Xkb supports five types of doodads:
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>
506 ) and the indicator color when it is dark (<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.
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.
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.
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.
555 The structures these doodads are stored in and the values of the <emphasis>
557 fields are shown in Table 13.1.
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*'/>
569 <entry>Doodad</entry>
570 <entry>Structure</entry>
577 indicator doodad</emphasis>
580 XkbIndicatorDoodadRec</emphasis>
583 XkbIndicatorDoodad</emphasis>
588 outline doodad</emphasis>
591 XkbShapeDoodadRec</emphasis>
594 XkbOutlineDoodad</emphasis>
599 solid doodad</emphasis>
602 XkbShapeDoodadRec</emphasis>
605 XkbSolidDoodad</emphasis>
610 text doodad</emphasis>
613 XkbTextDoodadRec</emphasis>
616 XkbTextDoodad</emphasis>
621 logo doodad</emphasis>
624 XkbLogoDoodadRec</emphasis>
627 XkbLogoDoodad</emphasis>
635 <sect1 id='Overlay_Rows_and_Overlay_Keys'>
636 <title>Overlay Rows and Overlay Keys</title>
640 overlay row</emphasis>
642 XkbOverlayRowRec</emphasis>
643 ) contains a pointer to the row it overlays and a list of <emphasis>
644 overlay keys</emphasis>
650 Each overlay key definition (<emphasis>
651 XkbOverlayKeyRec</emphasis>
652 ) indicates a key that can yield multiple keycodes and consists of a field
655 , which specifies the primary name of the key and a field named <emphasis>
657 , which specifies the name for the key when the overlay keycode is selected.
658 The key specified in <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.
666 <sect1 id='Drawing_a_Keyboard_Representation'>
667 <title>Drawing a Keyboard Representation</title>
670 To draw a representation of the keyboard, draw in the following order:
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.
681 </programlisting></para>
684 <sect1 id='Geometry_Data_Structures'>
685 <title>Geometry Data Structures</title>
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.
694 <MAP NAME="XKBlib-10">
698 <imageobject> <imagedata format="SVG" fileref="XKBlib-10.svg"/>
700 <caption>Xkb Geometry Data Structures</caption>
705 Xkb Geometry Data Structures</H5>
706 <P CLASS="SmallBody">
708 <MAP NAME="XKBlib-11">
712 <imageobject> <imagedata format="SVG" fileref="XKBlib-11.svg"/>
714 <caption>Xkb Geometry Data Structures (Doodads)</caption>
719 Xkb Geometry Data Structures (Doodads)</H5>
723 <MAP NAME="XKBlib-12">
727 <imageobject> <imagedata format="SVG" fileref="XKBlib-12.svg"/>
729 <caption>Xkb Geometry Data Structures (Overlays)</caption>
734 Xkb Geometry Data Structures (Overlays)</H5>
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>
768 array is only for doodads not contained in any of the <emphasis>
770 that has its own <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.
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>
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>
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>
799 <para><programlisting>
800 typedef struct _XkbPoint { /* x,y coordinates */
803 } <emphasis>XkbPointRec</emphasis>, *XkbPointPtr;
804 </programlisting></para>
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>
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>
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>
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.
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>
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> =>vertical row,
863 <emphasis> False</emphasis> =>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>
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>
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>
904 is an index into the array of <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>
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>
921 <para><programlisting>
922 typedef struct _XkbSection {
923 Atom name; /* section name */
924 unsigned char priority; /* drawing priority, 0=>highest, 255=>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>
948 are the origin of the section, relative to the origin of the keyboard, in
962 <sect2 id='DoodadRec_Structures'>
963 <title>DoodadRec Structures</title>
966 The doodad arrays in the <emphasis>
967 XkbGeometryRec</emphasis>
969 XkbSectionRec</emphasis>
970 may contain any of the doodad structures and types shown in Table 13.1.
975 The doodad structures form a union:
978 <para><programlisting>
979 typedef union _XkbDoodad {
981 XkbShapeDoodadRec shape;
982 XkbTextDoodadRec text;
983 XkbIndicatorDoodadRec indicator;
984 XkbLogoDoodadRec logo;
985 } <emphasis>XkbDoodadRec</emphasis>, *XkbDoodadPtr;
986 </programlisting></para>
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
998 XkbSectionRec</emphasis>
999 doodad array. The <emphasis>
1000 color_ndx</emphasis>
1002 on_color_ndx</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
1009 shape_ndx</emphasis>
1010 fields are indices into the <emphasis>
1011 XkbGeometryRec</emphasis>
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=>highest, 255=>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>
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=>highest, 255=>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>
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=>highest, 255=>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>
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=>highest, 255=>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>
1077 <sect1 id='Getting_Keyboard_Geometry_From_the_Server'>
1078 <title>Getting Keyboard Geometry From the Server</title>
1081 You can load a keyboard geometry as part of the keyboard description returned
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.
1092 To load a keyboard geometry if you already have the keyboard description, use
1093 <emphasis>XkbGetGeometry</emphasis>.
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*'/>
1102 <entry role='functiondecl'>
1104 XkbGetGeometry</emphasis>
1113 <entry role='functionargdecl'>
1114 Display * <emphasis>
1116 ; /* connection to the X server */
1120 <entry role='functionargdecl'>
1121 XkbDescPtr <emphasis>
1123 ; /* keyboard description that contains the ID for the keyboard and into
1124 which the geometry should be loaded */
1133 XkbGetGeometry</emphasis>
1134 can return <emphasis>
1137 BadImplementation</emphasis>
1141 BadAlloc,</emphasis>
1143 BadLength</emphasis>
1144 errors or <emphasis>
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>.
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*'/>
1162 <entry role='functiondecl'>
1164 XkbGetNamedGeometry</emphasis>
1175 <entry role='functionargdecl'>
1176 Display * <emphasis>
1178 ; /* connection to the X server */
1182 <entry role='functionargdecl'>
1183 XkbDescPtr <emphasis>
1185 ; /* keyboard description into which the geometry should be loaded */
1189 <entry role='functionargdecl'>
1192 ; /* name of the geometry to be loaded */
1201 XkbGetNamedGeometry</emphasis>
1202 can return <emphasis>
1210 <sect1 id='Using_Keyboard_Geometry'>
1211 <title>Using Keyboard Geometry</title>
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.
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.
1226 <imageobject> <imagedata format="SVG" fileref="XKBlib-13.svg"/>
1228 <caption>Key Surface, Shape Outlines, and Bounding Box</caption>
1234 Key Surface, Shape Outlines, and Bounding Box</H5>
1238 To determine the bounding box of the top surface of a shape, use <emphasis>
1239 XkbComputeShapeTop</emphasis>.
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*'/>
1248 <entry role='functiondecl'>
1250 XkbComputeShapeTop</emphasis>
1254 bounds_rtrn</emphasis>
1259 <entry role='functionargdecl'>
1260 XkbShapePtr <emphasis>
1262 ; /* shape to be examined */
1266 <entry role='functionargdecl'>
1267 XkbBoundsPtr <emphasis>
1268 bounds_rtrn</emphasis>
1269 /* backfilled with the bounding box for the shape */
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
1294 , the top surface is defined as the last outline in the <emphasis>
1296 ’s array of outlines. <emphasis>
1297 XkbComputeShapeTop</emphasis>
1304 or if there are no outlines for the shape; otherwise, it returns
1305 <emphasis>True</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>.
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*'/>
1326 <entry role='functiondecl'>
1328 XkbComputeShapeBounds</emphasis>
1335 <entry role='functionargdecl'>
1336 XkbShapePtr <emphasis>
1338 ; /* shape to be examined */
1347 XkbComputeShapeBounds</emphasis>
1348 updates the <emphasis>
1349 BoundsRec</emphasis>
1350 contained in the <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>
1363 or if there are no outlines for the shape; otherwise, it returns <emphasis>
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>.
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*'/>
1380 <entry role='functiondecl'>
1382 XkbComputeRowBounds</emphasis>
1393 <entry role='functionargdecl'>
1394 XkbGeometryPtr <emphasis>
1396 ; /* geometry that contains the <emphasis>
1402 <entry role='functionargdecl'>
1403 XkbSectionPtr <emphasis>
1405 ; /* section that contains the row */
1409 <entry role='functionargdecl'>
1410 XkbRowPtr <emphasis>
1412 ; /* row to be examined and updated */
1421 XkbComputeRowBounds</emphasis>
1422 checks the bounds of all keys in the <emphasis>
1424 and updates the bounding box of the row if necessary. <emphasis>
1425 XkbComputeRowBounds</emphasis>
1428 if any of the arguments is <emphasis>
1430 ; otherwise, it returns <emphasis>
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>.
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*'/>
1448 <entry role='functiondecl'>
1450 XkbComputeSectionBounds</emphasis>
1459 <entry role='functionargdecl'>
1460 XkbGeometryPtr <emphasis>
1462 ; /* geometry that contains the <emphasis>
1468 <entry role='functionargdecl'>
1469 XkbSectionPtr <emphasis>
1471 ; /* section to be examined and updated */
1480 XkbComputeSectionBounds</emphasis>
1481 examines all the rows of the <emphasis>
1483 and updates the bounding box of that section so that it contains all rows.
1485 XkbComputeSectionBounds</emphasis>
1488 if any of the arguments is <emphasis>
1490 ; otherwise, it returns <emphasis>
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>.
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*'/>
1508 <entry role='functiondecl'>
1510 XkbFindOverlayForKey</emphasis>
1521 <entry role='functionargdecl'>
1522 XkbGeometryPtr <emphasis>
1524 ; /* geometry that contains the <emphasis>
1530 <entry role='functionargdecl'>
1531 XkbSectionPtr <emphasis>
1533 ; /* section to be searched for matching keys */
1537 <entry role='functionargdecl'>
1540 . /* primary name of the key to be considered */
1549 XkbFindOverlayForKey</emphasis>
1550 uses the primary name of the key, <emphasis>
1552 , to look up the alternate name, which it returns.
1557 <sect1 id='Adding_Elements_to_a_Keyboard_Geometry'>
1558 <title>Adding Elements to a Keyboard Geometry</title>
1561 Xkb provides functions to add a single new element to the top-level keyboard
1562 geometry. In each case the <emphasis>
1566 fields of the corresponding structure is incremented by 1. These functions do
1567 not change <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.
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.
1588 To add one property to an existing keyboard geometry description, use <emphasis>
1589 XkbAddGeomProperty</emphasis>
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*'/>
1599 <entry role='functiondecl'>
1600 XkbPropertyPtr <emphasis>
1601 XkbAddGeomProperty</emphasis>
1612 <entry role='functionargdecl'>
1613 XkbGeometryPtr <emphasis>
1615 ; /* geometry to be updated */
1619 <entry role='functionargdecl'>
1622 ; /* name of the new property */
1626 <entry role='functionargdecl'>
1629 ; /* value for the new property */
1638 XkbAddGeomProperty</emphasis>
1639 adds one property with the specified <emphasis>
1643 to the keyboard geometry specified by geom.<emphasis>
1646 XkbAddGeomProperty</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.
1656 To add one key alias to an existing keyboard geometry description, use
1658 XkbAddGeomKeyAlias</emphasis>
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*'/>
1669 <entry role='functiondecl'>
1670 XkbKeyAliasPtr <emphasis>
1671 XkbAddGeomKeyAlias</emphasis>
1675 alias, real</emphasis>
1680 <entry role='functionargdecl'>
1681 XkbGeometryPtr <emphasis>
1683 ; /* geometry to be updated */
1687 <entry role='functionargdecl'>
1690 ; /* alias to be added */
1694 <entry role='functionargdecl'>
1697 ; /* real name to be bound to the new alias */
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>
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.
1719 To add one color name to an existing keyboard geometry description, use
1721 XkbAddGeomColor</emphasis>
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*'/>
1732 <entry role='functiondecl'>
1733 XkbColorPtr <emphasis>
1734 XkbAddGeomColor</emphasis>
1745 <entry role='functionargdecl'>
1746 XkbGeometryPtr <emphasis>
1748 ; /* geometry to be updated */
1752 <entry role='functionargdecl'>
1755 ; /* color to be added */
1759 <entry role='functionargdecl'>
1760 unsigned int <emphasis>
1762 ; /* color to be added */
1771 XkbAddGeomColor</emphasis>
1772 adds the specified color <emphasis>
1776 to the specified geometry <emphasis>
1778 . The top-level geometry description includes a list of up to <emphasis>
1779 MaxColors</emphasis>
1781 color names</emphasis>
1782 . A color <emphasis>
1784 is a string whose interpretation is not specified by Xkb and neither is the
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.
1790 XkbAddGeomColor</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,
1796 XkbAllocGeomColors</emphasis>
1801 To add one outline to an existing shape, use <emphasis>
1802 XkbAddGeomOutline</emphasis>.
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*'/>
1811 <entry role='functiondecl'>
1812 XkbOutlinePtr <emphasis>
1813 XkbAddGeomOutline</emphasis>
1817 sz_points</emphasis>
1822 <entry role='functionargdecl'>
1823 XkbShapePtr <emphasis>
1825 ; /* shape to be updated */
1829 <entry role='functionargdecl'>
1831 sz_points</emphasis>
1832 ; /* number of points to be reserved */
1840 An outline consists of an arbitrary number of points. <emphasis>
1841 XkbAddGeomOutline</emphasis>
1842 adds an outline to the specified <emphasis>
1844 by reserving <emphasis>
1845 sz_points</emphasis>
1846 points for it. The new outline is allocated and zeroed. <emphasis>
1847 XkbAddGeomOutline</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.
1857 To add a shape to a keyboard geometry, use <emphasis>
1858 XkbAddGeomShape</emphasis>
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*'/>
1869 <entry role='functiondecl'>
1870 XkbShapePtr <emphasis>
1871 XkbAddGeomShape</emphasis>
1877 sz_outlines</emphasis>
1882 <entry role='functionargdecl'>
1883 XkbGeometryPtr <emphasis>
1885 ; /* geometry to be updated */
1889 <entry role='functionargdecl'>
1892 ; /* name of the new shape */
1896 <entry role='functionargdecl'>
1898 sz_outlines</emphasis>
1899 ; /* number of outlines to be reserved */
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>
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
1917 already exists in the geometry, a pointer to the existing shape is returned.
1919 XkbAddGeomShape</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>
1930 To add one key at the end of an existing row of keys, use <emphasis>
1931 XkbAddGeomKey</emphasis>
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*'/>
1942 <entry role='functiondecl'>
1943 XkbKeyPtr <emphasis>
1944 XkbAddGeomKey</emphasis>
1951 <entry role='functionargdecl'>
1952 XkbRowPtr <emphasis>
1954 ; /* row to be updated */
1962 Keys are grouped into rows. <emphasis>
1963 XkbAddGeomKey</emphasis>
1964 adds one key to the end of the specified <emphasis>
1966 . The key is allocated and zeroed. <emphasis>
1967 XkbAddGeomKey</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.
1978 To add one section to an existing keyboard geometry, use <emphasis>
1979 XkbAddGeomSection</emphasis>
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*'/>
1990 <entry role='functiondecl'>
1991 XkbSectionPtr <emphasis>
1992 XkbAddGeomSection</emphasis>
2000 sz_doodads</emphasis>
2002 sz_overlays</emphasis>
2007 <entry role='functionargdecl'>
2008 XkbGeometryPtr <emphasis>
2010 ; /* geometry to be updated */
2014 <entry role='functionargdecl'>
2017 ; /* name of the new section */
2021 <entry role='functionargdecl'>
2024 ; /* number of rows to reserve in the section */
2028 <entry role='functionargdecl'>
2030 sz_doodads</emphasis>
2031 ; /* number of doodads to reserve in the section */
2035 <entry role='functionargdecl'>
2037 sz_overlays</emphasis>
2038 ; /* number of overlays to reserve in the section */
2046 A keyboard geometry contains an arbitrary number of sections. <emphasis>
2047 XkbAddGeomSection</emphasis>
2048 adds one section to an existing keyboard geometry <emphasis>
2050 . The new section contains space for the number of rows, doodads, and overlays
2051 specified by <emphasis>
2054 sz_doodads</emphasis>
2056 sz_overlays</emphasis>
2057 . The new section is allocated and zeroed and given the name specified by
2060 . If a section with name <emphasis>
2062 already exists in the geometry, a pointer to the existing section is
2064 XkbAddGeomSection</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.
2074 To add a row to a section, use <emphasis>
2075 XkbAddGeomRow</emphasis>
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*'/>
2086 <entry role='functiondecl'>
2087 XkbRowPtr <emphasis>
2088 XkbAddGeomRow</emphasis>
2097 <entry role='functionargdecl'>
2098 XkbSectionPtr <emphasis>
2100 ; /* section to be updated */
2104 <entry role='functionargdecl'>
2107 ; /* number of keys to be reserved */
2115 One of the components of a keyboard geometry section is one or more rows of
2117 XkbAddGeomRow</emphasis>
2118 adds one row to the specified <emphasis>
2120 . The newly created row contains space for the number of keys specified in
2123 . They are allocated and zeroed, but otherwise uninitialized. <emphasis>
2124 XkbAddGeomRow</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.
2134 To add one doodad to a section of a keyboard geometry or to the top-level
2135 geometry, use <emphasis>
2136 XkbAddGeomDoodad</emphasis>
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*'/>
2147 <entry role='functiondecl'>
2148 XkbDoodadPtr <emphasis>
2149 XkbAddGeomDoodad</emphasis>
2160 <entry role='functionargdecl'>
2161 XkbGeometryPtr <emphasis>
2163 ; /* geometry to which the doodad is added */
2167 <entry role='functionargdecl'>
2168 XkbSectionPtr <emphasis>
2170 ; /* section, if any, to which the doodad is added */
2174 <entry role='functionargdecl'>
2177 ; /* name of the new doodad */
2187 describes some visible aspect of the keyboard that is not a key and is not a
2189 XkbAddGeomDoodad</emphasis>
2190 adds a doodad with name specified by name to the geometry <emphasis>
2192 if section is <emphasis>
2194 or to the section of the geometry specified by section if <emphasis>
2199 XkbAddGeomDoodad</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>
2205 in the doodad array for the geometry (if <emphasis>
2209 ) or the section (if <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.
2221 To add one overlay to a section, use <emphasis>
2222 XkbAddGeomOverlay</emphasis>
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*'/>
2233 <entry role='functiondecl'>
2234 XkbOverlayPtr <emphasis>
2235 XkbAddGeomOverlay</emphasis>
2246 <entry role='functionargdecl'>
2247 XkbSectionPtr <emphasis>
2249 ; /* section to which an overlay will be added */
2253 <entry role='functionargdecl'>
2256 ; /* name of the overlay */
2260 <entry role='functionargdecl'>
2263 ; /* number of rows to reserve in the overlay */
2272 XkbAddGeomOverlay</emphasis>
2273 adds an overlay with the specified name to the specified <emphasis>
2275 . The new overlay is created with space allocated for sz_rows rows. If an
2276 overlay with name <emphasis>
2278 already exists in the section, a pointer to the existing overlay is
2280 XkbAddGeomOverlay</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.
2290 To add a row to an existing overlay, use <emphasis>
2291 XkbAddGeomOverlayRow</emphasis>
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*'/>
2302 <entry role='functiondecl'>
2303 XkbOverlayRowPtr <emphasis>
2304 XkbAddGeomOverlayRow</emphasis>
2308 row_under, sz_keys</emphasis>
2313 <entry role='functionargdecl'>
2314 XkbOverlayPtr <emphasis>
2316 ; /* overlay to be updated */
2320 <entry role='functionargdecl'>
2321 XkbRowPtr <emphasis>
2322 row_under</emphasis>
2323 ; /* row to be overlayed in the section <emphasis>
2329 <entry role='functionargdecl'>
2332 ; /* number of keys to reserve in the row */
2341 XkbAddGeomOverlayRow</emphasis>
2342 adds one row to the <emphasis>
2344 . The new row contains space for <emphasis>
2347 row_under</emphasis>
2348 specifies a row that doesn’t exist on the underlying section, <emphasis>
2349 XkbAddGeomOverlayRow</emphasis>
2352 and doesn’t change the overlay.<emphasis>
2353 XkbAddGeomOverlayRow</emphasis>
2356 if any of the parameters is empty or if it was not able to allocate space for
2362 To add a key to an existing overlay row, use <emphasis>
2363 XkbAddGeomOverlayKey</emphasis>
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*'/>
2374 <entry role='functiondecl'>
2375 XkbOverlayKeyPtr <emphasis>
2376 XkbAddGeomOverlayKey</emphasis>
2380 row, under</emphasis>
2385 <entry role='functionargdecl'>
2386 XkbOverlayPtr <emphasis>
2388 ; /* overlay to be updated */
2392 <entry role='functionargdecl'>
2393 XkbRowPtr <emphasis>
2395 ; /* row in overlay to be updated */
2399 <entry role='functionargdecl'>
2402 ; /* primary name of the key to be considered */
2411 XkbAddGeomOverlayKey</emphasis>
2412 adds one key to the <emphasis>
2416 . If there is no key named <emphasis>
2418 in the row of the underlying section, <emphasis>
2419 XkbAddGeomOverlayKey</emphasis>
2427 <sect1 id='Allocating_and_Freeing_Geometry_Components'>
2428 <title>Allocating and Freeing Geometry Components</title>
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>
2439 but never touch <emphasis>
2443 (unless there is an allocation failure, in which case they reset both
2452 to zero). These functions return <emphasis>
2454 if they succeed, <emphasis>
2456 if they are not able to allocate space, or <emphasis>
2458 if a parameter is not as expected.
2463 To allocate space for an arbitrary number of outlines to a shape, use
2464 XkbAllocGeomOutlines.
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*'/>
2473 <entry role='functiondecl'>
2475 XkbAllocGeomOutlines</emphasis>
2479 num_needed</emphasis>
2484 <entry role='functionargdecl'>
2485 XkbShapePtr <emphasis>
2487 ; /* shape for which outlines should be allocated */
2491 <entry role='functionargdecl'>
2493 num_needed</emphasis>
2494 ; /* number of new outlines required */
2503 XkbAllocGeomOutlines</emphasis>
2504 allocates space for <emphasis>
2505 num_needed</emphasis>
2506 outlines in the specified <emphasis>
2508 . The outlines are not initialized.
2513 To free geometry outlines, use <emphasis>
2514 XkbFreeGeomOutlines</emphasis>
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*'/>
2525 <entry role='functiondecl'>
2527 XkbFreeGeomOutlines</emphasis>
2540 <entry role='functionargdecl'>
2541 XkbShapePtr <emphasis>
2543 ; /* shape in which outlines should be freed */
2547 <entry role='functionargdecl'>
2550 ; /* first outline to be freed */
2554 <entry role='functionargdecl'>
2557 ; /* number of outlines to be freed */
2561 <entry role='functionargdecl'>
2563 free_all;</emphasis>
2566 => all outlines are freed */
2574 If free_all is <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.
2582 To allocate space for an arbitrary number of keys to a row, use
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*'/>
2593 <entry role='functiondecl'>
2595 XkbAllocGeomKeys</emphasis>
2599 num_needed</emphasis>
2604 <entry role='functionargdecl'>
2605 XkbRowPtr <emphasis>
2607 ; /* row to which keys should be allocated */
2611 <entry role='functionargdecl'>
2613 num_needed</emphasis>
2614 ; /* number of new keys required */
2623 XkbAllocGeomKeys</emphasis>
2624 allocates num_needed keys and adds them to the row. No initialization of the
2630 To free geometry keys, use <emphasis>
2631 XkbFreeGeomKeys</emphasis>
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*'/>
2642 <entry role='functiondecl'>
2644 XkbFreeGeomKeys</emphasis>
2657 <entry role='functionargdecl'>
2658 XkbRowPtr <emphasis>
2660 ; /* row in which keys should be freed */
2664 <entry role='functionargdecl'>
2667 ; /* first key to be freed */
2671 <entry role='functionargdecl'>
2674 ; /* number of keys to be freed */
2678 <entry role='functionargdecl'>
2680 free_all;</emphasis>
2683 => all keys are freed */
2691 If free_all is <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.
2699 To allocate geometry properties, use <emphasis>
2700 XkbAllocGeomProps</emphasis>
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*'/>
2711 <entry role='functiondecl'>
2713 XkbAllocGeomProps</emphasis>
2717 num_needed</emphasis>
2722 <entry role='functionargdecl'>
2723 XkbGeometryPtr <emphasis>
2725 ; /* geometry for which properties should be allocated */
2729 <entry role='functionargdecl'>
2731 num_needed</emphasis>
2732 ; /* number of new properties required */
2741 XkbAllocGeomProps</emphasis>
2742 allocates space for num_needed properties and adds them to the specified
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
2754 To free geometry properties, use <emphasis>
2755 XkbFreeGeomProperties</emphasis>
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*'/>
2766 <entry role='functiondecl'>
2768 XkbFreeGeomProperties</emphasis>
2781 <entry role='functionargdecl'>
2782 XkbGeometryPtr <emphasis>
2784 ; /* geometry in which properties should be freed */
2788 <entry role='functionargdecl'>
2791 ; /* first property to be freed */
2795 <entry role='functionargdecl'>
2798 ; /* number of properties to be freed */
2802 <entry role='functionargdecl'>
2804 free_all;</emphasis>
2807 => all properties are freed */
2815 If free_all is <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.
2823 To allocate geometry key aliases, use <emphasis>
2824 XkbAllocGeomKeyAliases</emphasis>
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*'/>
2835 <entry role='functiondecl'>
2837 XkbAllocGeomKeyAliases</emphasis>
2841 num_needed</emphasis>
2846 <entry role='functionargdecl'>
2847 XkbGeometryPtr <emphasis>
2849 ; /* geometry for which key aliases should be allocated */
2853 <entry role='functionargdecl'>
2855 num_needed</emphasis>
2856 ; /* number of new key aliases required */
2865 XkbAllocGeomKeyAliases</emphasis>
2866 allocates space for num_needed key aliases and adds them to the specified
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.
2875 To free geometry key aliases, use <emphasis>
2876 XkbFreeGeomKeyAliases</emphasis>
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*'/>
2887 <entry role='functiondecl'>
2889 XkbFreeGeomKeyAliases</emphasis>
2902 <entry role='functionargdecl'>
2903 XkbGeometryPtr <emphasis>
2905 ; /* geometry in which key aliases should be freed */
2909 <entry role='functionargdecl'>
2912 ; /* first key alias to be freed */
2916 <entry role='functionargdecl'>
2919 ; /* number of key aliases to be freed */
2923 <entry role='functionargdecl'>
2925 free_all;</emphasis>
2928 => all key aliases are freed */
2936 If free_all is <emphasis>
2938 , all aliases in the top level of the specified geometry <emphasis>
2940 are freed regardless of the value of first or count. Otherwise, count aliases
2943 are freed beginning with the one specified by first.
2948 To allocate geometry colors, use <emphasis>
2949 XkbAllocGeomColors</emphasis>
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*'/>
2960 <entry role='functiondecl'>
2962 XkbAllocGeomColors</emphasis>
2966 num_needed</emphasis>
2971 <entry role='functionargdecl'>
2972 XkbGeometryPtr <emphasis>
2974 ; /* geometry for which colors should be allocated */
2978 <entry role='functionargdecl'>
2980 num_needed</emphasis>
2981 ; /* number of new colors required. */
2990 XkbAllocGeomColors</emphasis>
2991 allocates space for num_needed colors and adds them to the specified geometry
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.
3001 To free geometry colors, use <emphasis>
3002 XkbFreeGeomColors</emphasis>
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*'/>
3013 <entry role='functiondecl'>
3015 XkbFreeGeomColors</emphasis>
3028 <entry role='functionargdecl'>
3029 XkbGeometryPtr <emphasis>
3031 ; /* geometry in which colors should be freed */
3035 <entry role='functionargdecl'>
3038 ; /* first color to be freed */
3042 <entry role='functionargdecl'>
3045 ; /* number of colors to be freed */
3049 <entry role='functionargdecl'>
3051 free_all;</emphasis>
3054 => all colors are freed */
3062 If free_all is <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.
3070 To allocate points in an outline, use <emphasis>
3071 XkbAllocGeomPoints</emphasis>
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*'/>
3082 <entry role='functiondecl'>
3084 XkbAllocGeomPoints</emphasis>
3088 num_needed</emphasis>
3093 <entry role='functionargdecl'>
3094 XkbOutlinePtr <emphasis>
3096 ; /* outline for which points should be allocated */
3100 <entry role='functionargdecl'>
3102 num_needed</emphasis>
3103 ; /* number of new points required */
3112 XkbAllocGeomPoints</emphasis>
3113 allocates space for <emphasis>
3114 num_needed</emphasis>
3115 points in the specified <emphasis>
3117 . The points are not initialized.
3122 To free points in a outline, use <emphasis>
3123 XkbFreeGeomPoints</emphasis>
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*'/>
3134 <entry role='functiondecl'>
3136 XkbFreeGeomPoints</emphasis>
3149 <entry role='functionargdecl'>
3150 XkbOutlinePtr <emphasis>
3152 ; /* outline in which points should be freed */
3156 <entry role='functionargdecl'>
3159 ; /* first point to be freed. */
3163 <entry role='functionargdecl'>
3166 ; /* number of points to be freed */
3170 <entry role='functionargdecl'>
3172 free_all;</emphasis>
3175 => all points are freed */
3183 If free_all is <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.
3192 To allocate space for an arbitrary number of geometry shapes, use <emphasis>
3193 XkbAllocGeomShapes</emphasis>
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*'/>
3204 <entry role='functiondecl'>
3206 XkbAllocGeomShapes</emphasis>
3210 num_needed</emphasis>
3215 <entry role='functionargdecl'>
3216 XkbGeometryPtr <emphasis>
3218 ; /* geometry for which shapes should be allocated */
3222 <entry role='functionargdecl'>
3224 num_needed</emphasis>
3225 ; /* number of new shapes required */
3234 XkbAllocGeomShapes</emphasis>
3235 allocates space for <emphasis>
3236 num_needed</emphasis>
3237 shapes in the specified geometry <emphasis>
3239 . The shapes are not initialized.
3244 To free geometry shapes, use <emphasis>
3245 XkbFreeGeomShapes</emphasis>
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*'/>
3256 <entry role='functiondecl'>
3258 XkbFreeGeomShapes</emphasis>
3266 f ree_all</emphasis>
3271 <entry role='functionargdecl'>
3272 XkbGeometryPtr <emphasis>
3274 ; /* geometry in which shapes should be freed */
3278 <entry role='functionargdecl'>
3281 ; /* first shape to be freed */
3285 <entry role='functionargdecl'>
3288 ; /* number of shapes to be freed */
3292 <entry role='functionargdecl'>
3294 free_all;</emphasis>
3297 => all shapes are freed */
3305 If free_all is <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
3314 To allocate geometry sections, use <emphasis>
3315 XkbAllocGeomSections</emphasis>
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*'/>
3326 <entry role='functiondecl'>
3328 XkbAllocGeomSections</emphasis>
3332 num_needed</emphasis>
3337 <entry role='functionargdecl'>
3338 XkbGeometryPtr <emphasis>
3340 ; /*geometry for which sections should be allocated */
3344 <entry role='functionargdecl'>
3346 num_needed</emphasis>
3347 ; /* number of new sections required */
3356 XkbAllocGeomSections</emphasis>
3357 allocates num_needed sections and adds them to the geometry geom. No
3358 initialization of the sections is done.
3363 To free geometry sections, use <emphasis>
3364 XkbFreeGeomSections</emphasis>
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*'/>
3375 <entry role='functiondecl'>
3377 XkbFreeGeomSections</emphasis>
3390 <entry role='functionargdecl'>
3391 XkbGeometryPtr <emphasis>
3393 ; /* geometry in which sections should be freed */
3397 <entry role='functionargdecl'>
3400 ; /* first section to be freed. */
3404 <entry role='functionargdecl'>
3407 ; /* number of sections to be freed */
3411 <entry role='functionargdecl'>
3413 free_all;</emphasis>
3416 => all sections are freed */
3424 If free_all is <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.
3433 To allocate rows in a section, use <emphasis>
3434 XkbAllocGeomRows</emphasis>
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*'/>
3445 <entry role='functiondecl'>
3447 XkbAllocGeomRows</emphasis>
3451 num_needed</emphasis>
3456 <entry role='functionargdecl'>
3457 XkbSectionPtr <emphasis>
3459 ; /* section for which rows should be allocated */
3463 <entry role='functionargdecl'>
3465 num_needed</emphasis>
3466 ; /* number of new rows required */
3475 XkbAllocGeomRows</emphasis>
3476 allocates num_needed rows and adds them to the section. No initialization of
3482 To free rows in a section, use <emphasis>
3483 XkbFreeGeomRows</emphasis>
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*'/>
3494 <entry role='functiondecl'>
3496 XkbFreeGeomRows</emphasis>
3509 <entry role='functionargdecl'>
3510 XkbSectionPtr <emphasis>
3512 ; /* section in which rows should be freed */
3516 <entry role='functionargdecl'>
3519 ; /* first row to be freed. */
3523 <entry role='functionargdecl'>
3526 ; /* number of rows to be freed */
3530 <entry role='functionargdecl'>
3532 free_all;</emphasis>
3535 => all rows are freed */
3543 If free_all is <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.
3552 To allocate overlays in a section, use <emphasis>
3553 XkbAllocGeomOverlays</emphasis>
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*'/>
3564 <entry role='functiondecl'>
3566 XkbAllocGeomOverlays</emphasis>
3570 num_needed</emphasis>
3575 <entry role='functionargdecl'>
3576 XkbSectionPtr <emphasis>
3578 ; /* section for which overlays should be allocated */
3582 <entry role='functionargdecl'>
3584 num_needed</emphasis>
3585 ; /* number of new overlays required */
3594 XkbAllocGeomRows</emphasis>
3595 allocates num_needed overlays and adds them to the section. No initialization
3596 of the overlays is done.
3601 To free rows in an section, use <emphasis>
3602 XkbFreeGeomOverlays</emphasis>
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*'/>
3613 <entry role='functiondecl'>
3615 XkbFreeGeomOverlays</emphasis>
3628 <entry role='functionargdecl'>
3629 XkbSectionPtr <emphasis>
3631 ; /* section in which overlays should be freed */
3635 <entry role='functionargdecl'>
3638 ; /* first overlay to be freed. */
3642 <entry role='functionargdecl'>
3645 ; /* number of overlays to be freed */
3649 <entry role='functionargdecl'>
3651 free_all;</emphasis>
3654 => all overlays are freed */
3662 If free_all is <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.
3671 To allocate rows in a overlay, use <emphasis>
3672 XkbAllocGeomOverlayRows</emphasis>
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*'/>
3683 <entry role='functiondecl'>
3685 XkbAllocGeomOverlayRows</emphasis>
3689 num_needed</emphasis>
3694 <entry role='functionargdecl'>
3695 XkbSectionPtr <emphasis>
3697 ; /* section for which rows should be allocated */
3701 <entry role='functionargdecl'>
3703 num_needed</emphasis>
3704 ; /* number of new rows required */
3713 XkbAllocGeomOverlayRows</emphasis>
3714 allocates num_needed rows and adds them to the overlay. No initialization of
3720 To free rows in an overlay, use <emphasis>
3721 XkbFreeGeomOverlayRows</emphasis>
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*'/>
3732 <entry role='functiondecl'>
3734 XkbFreeGeomOverlayRows</emphasis>
3747 <entry role='functionargdecl'>
3748 XkbSectionPtr <emphasis>
3750 ; /* section in which rows should be freed */
3754 <entry role='functionargdecl'>
3757 ; /* first row to be freed. */
3761 <entry role='functionargdecl'>
3764 ; /* number of rows to be freed */
3768 <entry role='functionargdecl'>
3770 free_all;</emphasis>
3773 => all rows are freed */
3781 If free_all is <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.
3790 To allocate keys in an overlay row, use <emphasis>
3791 XkbAllocGeomOverlayKeys</emphasis>
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*'/>
3802 <entry role='functiondecl'>
3804 XkbAllocGeomOverlayKeys</emphasis>
3808 num_needed</emphasis>
3813 <entry role='functionargdecl'>
3814 XkbRowPtr <emphasis>
3816 ; /* section for which rows should be allocated */
3820 <entry role='functionargdecl'>
3822 num_needed</emphasis>
3823 ; /* number of new rows required */
3832 XkbAllocGeomOverlayKeys</emphasis>
3833 allocates num_needed keys and adds them to the row. No initialization of the
3839 To free keys in an overlay row, use <emphasis>
3840 XkbFreeGeomOverlayKeys</emphasis>
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*'/>
3851 <entry role='functiondecl'>
3853 XkbFreeGeomOverlayKeys</emphasis>
3866 <entry role='functionargdecl'>
3867 XkbRowPtr <emphasis>
3869 ; /* row in which keys should be freed */
3873 <entry role='functionargdecl'>
3876 ; /* first key to be freed. */
3880 <entry role='functionargdecl'>
3883 ; /* number of keys to be freed */
3887 <entry role='functionargdecl'>
3889 free_all;</emphasis>
3892 => all keys are freed */
3900 If free_all is <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.
3909 To allocate doodads that are global to a keyboard geometry, use <emphasis>
3910 XkbAllocGeomDoodads</emphasis>
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*'/>
3921 <entry role='functiondecl'>
3923 XkbAllocGeomDoodads</emphasis>
3927 num_needed</emphasis>
3932 <entry role='functionargdecl'>
3933 XkbGeometryPtr <emphasis>
3935 ; /* geometry for which doodads should be allocated */
3939 <entry role='functionargdecl'>
3941 num_needed</emphasis>
3942 ; /* number of new doodads required */
3951 XkbAllocGeomDoodads</emphasis>
3952 allocates num_needed doodads and adds them to the specified geometry <emphasis>
3954 . No initialization of the doodads is done.
3959 To allocate doodads that are specific to a section, use <emphasis>
3960 XkbAllocGeomSectionDoodads</emphasis>
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*'/>
3971 <entry role='functiondecl'>
3973 XkbAllocGeomSectionDoodads</emphasis>
3977 num_needed</emphasis>
3982 <entry role='functionargdecl'>
3983 XkbSectionPtr <emphasis>
3985 ; /* section for which doodads should be allocated */
3989 <entry role='functionargdecl'>
3991 num_needed</emphasis>
3992 ; /* number of new doodads required */
4001 XkbAllocGeomSectionDoodads</emphasis>
4002 allocates num_needed doodads and adds them to the specified <emphasis>
4004 . No initialization of the doodads is done.
4009 To free geometry doodads, use <emphasis>
4010 XkbFreeGeomDoodads</emphasis>
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*'/>
4021 <entry role='functiondecl'>
4023 XkbFreeGeomDoodads</emphasis>
4034 <entry role='functionargdecl'>
4035 XkbDoodadPtr <emphasis>
4037 ; /* doodads to be freed */
4041 <entry role='functionargdecl'>
4044 ; /* number of doodads to be freed */
4048 <entry role='functionargdecl'>
4050 free_all;</emphasis>
4053 => all doodads are freed */
4065 , all doodads in the array are freed, regardless of the value of count.
4066 Otherwise, count doodads are freed.
4071 To allocate an entire geometry, use <emphasis>
4072 XkbAllocGeometry</emphasis>
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*'/>
4083 <entry role='functiondecl'>
4085 XkbAllocGeometry</emphasis>
4094 <entry role='functionargdecl'>
4095 XkbDescPtr <emphasis>
4097 ; /* keyboard description for which geometry is to be allocated */
4101 <entry role='functionargdecl'>
4102 XkbGeometrySizesPtr<emphasis>
4104 ; /* initial sizes for all geometry components */
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.
4124 To free an entire geometry, use <emphasis>
4125 XkbFreeGeometry</emphasis>
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*'/>
4136 <entry role='functiondecl'>
4138 XkbFreeGeometry</emphasis>
4149 <entry role='functionargdecl'>
4150 XkbGeometryPtr <emphasis>
4152 ; /* geometry to be freed */
4156 <entry role='functionargdecl'>
4157 unsigned int <emphasis>
4159 ; /* mask of geometry components to be freed */
4163 <entry role='functionargdecl'>
4165 free_all;</emphasis>
4168 => the entire geometry is freed. */
4176 The values of which and free_all determine how much of the specified geometry
4177 is freed. The valid values for which are:
4180 <para><programlisting>
4181 #define XkbGeomPropertiesMask (1<<0)
4182 #define XkbGeomColorsMask (1<<1)
4183 #define XkbGeomShapesMask (1<<2)
4184 #define XkbGeomSectionsMask (1<<3)
4185 #define XkbGeomDoodadsMask (1<<4)
4186 #define XkbGeomAllMask (0x1f)
4187 </programlisting></para>
4190 If free_all is <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.