The XKB description of a keyboard includes an optional keyboard geometry which describes the physical appearance of the keyboard. Keyboard geometry describes the shape, location and color of all keyboard keys or other visible keyboard components such as indicators. The information contained in a keyboard geometry is sufficient to allow a client program to draw an accurate two-dimensional image of the keyboard. The components of the keyboard geometry include the following: A symbolic name to help users identify the keyboard. The width and height of the keyboard, in . For non-rectangular keyboards, the width and height describe the smallest bounding-box that encloses the outline of the keyboard. A list of up to MaxColors ( 32 ) color names . A color name is a string whose interpretation is not specified by XKB. Other geometry components refer to colors using their indices in this list. The base color of the keyboard is the predominant color on the keyboard and is used as the default color for any components whose color is not explicitly specified. The label color is the color used to draw the labels on most of the keyboard keys. The label font is a string which describes the font used to draw labels on most keys; XKB does not specify a format or name space for font names. A list of geometry properties . A geometry property associates an arbitrary string with an equally arbitrary name. Geometry properties can be used to provide hints to programs that display images of keyboards, but they are not interpreted by XKB. No other geometry structures refer to geometry properties. A list of key aliases , as described in Symbolic Names. A list of shapes ; other keyboard components refer to shapes by their index in this list. A shape consists of a name and one or more closed-polygons called outlines . Shapes and outlines are described in detail in Shapes and Outlines. Unless otherwise specified, geometry measurements are in units. The origin (0,0) is in the top left corner of the keyboard image. Some geometry components can be drawn rotated; all such objects rotate about their origin in increments. All geometry components include a priority , which indicates the order in which overlapping objects should be drawn. Objects are drawn in order from highest priority ( 0 ) to lowest ( 255 ). The description of the actual appearance of the keyboard is subdivided into named sections of related keys and doodads . A a doodad describes some visible aspect of the keyboard that is not a key. A section is a collection of keys and doodads that are physically close together and logically related. An outline is a list of one or more points which describes a single closed-polygon, as follows: A list with a single point describes a rectangle with one corner at the origin of the shape ( 0 , 0 ) and the opposite corner at the specified point. A list of two points describes a rectangle with one corner at the position specified by the first point and the opposite corner at the position specified by the second point. A list of three or more points describes an arbitrary polygon. If necessary, the polygon is automatically closed by connecting the last point in the list with the first. A non-zero value for the cornerRadius field specifies that the corners of the polygon should be drawn as circles with the specified radius. All points in an outline are specified relative to the origin of the enclosing shape. Points in an outline may have negative values for the X and Y coordinate. One outline (usually the first) is the primary outline; a keyboard display application can generate a simpler but still accurate keyboard image by displaying only the primary outlines for each shape. Non-rectangular keys must include a rectangular approximation as one of the outlines associated with the shape; the approximation is not normally displayed but can be used by very simple keyboard display applications to generate a recognizable but degraded image of the keyboard. Each section has its own coordinate system — if a section is rotated, the coordinates of any components within the section are interpreted relative to the edges that were on the top and left before rotation. The components that make up a section include: A list of rows . A row is a list of horizontally or vertically adjacent keys. Horizontal rows parallel the (pre-rotation) top of the section and vertical rows parallel the (pre-rotation) left of the section. All keys in a horizontal row share a common top coordinate; all keys in a vertical row share a left coordinate. A key description consists of a key name , a shape , a key color , and a gap . The key name should correspond to one of the keys named in the keyboard names description, the shape specifies the appearance of the key, and the key color specifies the color of the key (not the label on the key). Keys are normally drawn immediately adjacent to one another from left-to-right (or top-to-bottom) within a row. The gap field specifies the distance between a key and its predecessor. An optional list of doodads; any type of doodad can be enclosed within a section. Position and angle of rotation are relative to the origin and angle of rotation of the sections that contain them. Priority is relative to the other components of the section, not to the keyboard as a whole. An optional list of overlay keys . Each overlay key definition indicates a key that can yield multiple scan codes and consists of a field named under , which specifies the primary name of the key and a field named over , which specifies the name for the key when the overlay keycode is selected. The key specified in under must be a member of the section that contains the overlay key definition, while the key specified in over must not. Doodads can be global to the keyboard or part of a section. Doodads have symbolic names of arbitrary length. The only doodad name whose interpretation is specified by XKB is "Edges", which describes the outline of the entire keyboard, if present. All doodads report their origin in fields named left and top . XKB supports five kinds of doodads: An indicator doodad describes one of the physical keyboard indicators. Indicator doodads specify the shape of the indicator, the indicator color when it is lit ( on_color ) and the indicator color when it is dark ( off_color ). An outline doodad describes some aspect of the keyboard to be drawn as one or more hollow, closed polygons. Outline doodads specify the shape, color, and angle of rotation about the doodad origin at which they should be drawn. A solid doodad describes some aspect of the keyboard to be drawn as one or more filled polygons. Solid doodads specify the shape, color and angle of rotation about the doodad origin at which they should be drawn. A text doodad describes a text label somewhere on the keyboard. Text doodads specify the label string, the font and color to use when drawing the label, and the angle of rotation of the doodad about its origin. A logo doodad is a catch-all, which describes some other visible element of the keyboard. A logo doodad is essentially an outline doodad with an additional symbolic name that describes the element to be drawn. If a keyboard display program recognizes the symbolic name, it can draw something appropriate within the bounding region of the shape specified in the doodad. If the symbolic name does not describe a recognizable image, it should draw an outline using the specified shape, outline, and angle of rotation. The XKB extension does not specify the interpretation of logo names. Consider the following example keyboard: This keyboard has six sections: The left and right function sections (at the very top) each have one horizontal row with eight keys. The left and right alphanumeric sections (the large sections in the middle) each have six vertical rows, with four or five keys in each row. The left and right editing sections each have three vertical rows with one to three keys per row; the left editing section is rotated 20° clockwise about its origin while the right editing section is rotated 20° counterclockwise. This keyboard has four global doodads: Three small, round indicators and a rectangular logo. The program which generated this image did not recognize the logo, so it displays an outline with an appropriate shape in its place. This keyboard has seven shapes: All of the keys in the two function sections use the "FKEY" shape. Most of the keys in the alphanumeric sections, as well as four of the keys in each of the editing sections use the "NORM" shape. The keys in the first column of the left alphanumeric section and the last column of the right alphanumeric section all use the "WIDE" shape. Two keys in each of the editing sections use the "TALL" shape. The "LED" shape describes the three small, round indicators between the function and alphabetic sections. The "LOGO" shape describes the keyboard logo, and the "EDGE" shape describes the outline of the keyboard as a whole. The keyboard itself is white, as are all of the keys except for the eight keys that make up the home row, which use the "grey20" color. It isn’t really visible in this picture, but the three indicators have an "on" color of "green" and are "green30" when they are turned off. The keys in the alphanumeric and editing sections all have a (vertical) gap of 0.5mm; the keys in the two function sections have a (horizontal) gap of 3mm. Many of the keys in the right alphanumeric section, and the rightmost key in the right editing section are drawn with two names in this image. Those are overlay keys; the bottom key name is the normal name while the overlay name is printed at the top. For example, the right editing section has a single overlay key entry, which specifies an under name of <SPCE> and an over name of <KP0> , which indicates that the key in question is usually the shift key, but can behave like the 0 key on the numeric keypad when an overlay is active.