From 16b53769eba7d5d8249a217aa29287d72b7713c2 Mon Sep 17 00:00:00 2001 From: marha Date: Wed, 14 Sep 2011 14:23:18 +0200 Subject: libX11 git update 14 sep 2011 --- libX11/specs/XKB/ch13.xml | 4146 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 4146 insertions(+) create mode 100644 libX11/specs/XKB/ch13.xml (limited to 'libX11/specs/XKB/ch13.xml') diff --git a/libX11/specs/XKB/ch13.xml b/libX11/specs/XKB/ch13.xml new file mode 100644 index 000000000..6f8fce033 --- /dev/null +++ b/libX11/specs/XKB/ch13.xml @@ -0,0 +1,4146 @@ + +Keyboard Geometry + + +The Xkb description of a keyboard includes an optional keyboard geometry that +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. + + + + +You can retrieve a keyboard geometry from an X server that supports Xkb, or you +can allocate it from scratch and initialize it in a client program. The +keyboard geometry need not have any correspondence with the physical keyboard +that is connected to the X server. + + + + +Geometry measurements are specified in mm/10 units. The origin (0,0) is in the +top left corner of the keyboard image. A component’s own origin is also its +upper left corner. In some cases a component needs to be drawn rotated. For +example, a special keyboard may have a section of keys arranged in rows in a +rectangular area, but the entire rectangle may not be in alignment with the +rest of the keyboard, and instead, it is rotated from horizontal by 30 +o +. Rotation for a geometry object is specified in 1/10 o increments about its +origin. An example of a keyboard with rotated sections is shown in Figure 13.1. + + + + + +Rotated Keyboard Sections + + + + + + +Some geometry components include a +priority +, which indicates the order in which overlapping objects should be drawn. +Objects should be drawn in order from highest priority (0) to lowest (255). + + + + +The keyboard geometry’s top-level description is stored in a +XkbGeometryRec + structure. This structure contains three types of information: + + + + + +Lists of items, not used to draw the basic keyboard, but indexed by the +geometry descriptions that comprise the entire keyboard geometry (colors, +geometry properties, key aliases, shapes) + + + + +A number of singleton items that describe the keyboard as a whole (keyboard +name, width and height, a color for the keyboard as a whole, and a color for +keyboard key labels) + + + + +A list of the keyboard’s sections and nonkey doodads + + + + + +The top-level geometry is described in more detail in the following. + + + + +The lists of items used by components of the keyboard geometry description is +as follows: + + + + + +The top-level keyboard geometry description includes a list of up to +MaxColors + (32) +color names +. A color name is a string whose interpretation is not specified by Xkb. The + +XkbColorRec + structure provides a field for this name as well as a pixel field. The pixel +field is a convenient place for an application to store a pixel value or color +definition, if it needs to. All other geometry data structures refer to colors +using their indices in this global list. + + + + +The top-level keyboard geometry description includes 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. As an example of a possible use of + +properties +, consider the pause/break key on most PC keyboards: the "break" symbol is +usually on the front of the key and is often a different color. A program might +set a property to: + + +LBL_PAUS = "{Pause/top/black,Break/front/red}" + + +and use the property information to draw the key with a front label as well as +a top label. + + + + +The top-level keyboard geometry description includes a list of +key aliases + (see Chapter 18). Key aliases allow the keyboard layout designer to assign +multiple key names to a single key. + +Key aliases defined in the geometry component of a keyboard mapping +override those defined in the keycodes component of the server database, which +are stored in the +XkbNamesRec + ( +xkb->names +). Therefore, consider the key aliases defined by the geometry before +considering key aliases supplied by the keycodes. + + + +The top-level keyboard geometry description includes a list of +shapes +; other keyboard components refer to shapes by their index in this list. A +shape consists of an arbitrary name of type Atom and one or more closed-polygon + +outlines +. All points in an outline are specified relative to the origin of its +enclosing shape, that is, whichever shape that contains this outline in its +list of outlines. One outline is the primary outline. The primary outline is by +default the first outline, or it can be optionally specified by the +primary + field in the +XkbShapeRec + structure. A keyboard display application can generate a simpler but still +accurate keyboard image by displaying only the primary outlines for each shape. +Nonrectangular 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. + + + + + +The +XkbGeometryRec + top-level geometry description contains the following information that +pertains to the keyboard as a whole: + + + + + +A +keyboard symbolic name + of type Atom to help users identify the keyboard. + + + + +The +width + and +height + of the keyboard, in mm/10. For nonrectangular keyboards, the width and height +describe the smallest bounding box that encloses the outline of the keyboard. + + + + +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 that describes the font used to draw labels on most keys; label +fonts are arbitrary strings, because Xkb does not specify the format or name +space for font names. + + + + + +The keyboard is subdivided into named +sections + of related keys and doodads. The sections and doodads on the keyboard are +listed in the +XkbGeometryRec + top-level keyboard geometry description. A section is composed of keys that +are physically together and logically related. Figure 13.2 shows a keyboard +that is divided into four sections. A +doodad + describes some visible aspect of the keyboard that is not a key and is not a +section. + + + + + +Keyboard with Four Sections + + + + + +Shapes and Outlines + + +A +shape +, used to draw keyboard components and stored in a +XkbShapeRec + structure, has: + + + + + +An arbitrary name of type Atom. + + + + +Bounds (two x and y coordinates) that describe the corners of a rectangle +containing the shape’s top surface outline. + + + + +A list of one or more outlines (described below). + + + + +Optional pointers to a primary and an approximation outline (described below). +If either of these pointers is +NULL +, the default primary/approximation outline is the first one in the list of +outlines for the shape. + + + + + +An +outline +, stored in a +XkbOutlineRec + structure, is a list of one or more points that 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 nonzero value for the +corner_radius + 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 is the primary outline; a keyboard display application can generate +a simple but still accurate keyboard image by displaying only the primary +outlines for each shape. The default primary outline is the first in a +shape’s list of outlines. If the +primary + field of the +XkbShapeRec + structure is not +NULL +, it points to the primary outline. A rectangular +approximation + must be included for nonrectangular keys 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. + + + + +Sections + + +As previously noted, a keyboard is subdivided into +sections + of related keys. 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, stored in a +XkbSectionRec +, include: + + + + + +An arbitrary name of type Atom. + + + + +A priority, to indicate drawing order. 0 is the highest priority, 255 the +lowest. + + + + +Origin of the section, relative to the origin of the keyboard. + + + + +The width and height and the angle of rotation. + + + + +A list of +rows +. A row is a list of horizontally or vertically adjacent keys. Horizontal rows +parallel the (prerotation) top of the section, and vertical rows parallel the +(prerotation) 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. Figure 13.3 +shows the alpha section from the keyboard shown in Figure 13.2, divided into +rows. Rows and keys are defined below. + + + + + + + + Rows in a Section + + + + + + + + +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 for doodads in a section is relative to the other +components of the section, not to the keyboard as a whole. + + + + +An optional +overlay + with a name of type Atom and a list of overlay rows (described below). + + + + +Bounds (two x and y coordinates) that describe the corners of a rectangle +containing the entire section. + + + + + +Rows and Keys + + +A row description ( +XkbRowRec +) consists of the coordinates of its origin relative to its enclosing section, +a flag indicating whether the row is horizontal or vertical, and a list of keys +in the row. + + + + +A key description ( +XkbKeyRec +) 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; the label color is stored in the + +XkbGeometryRec +). 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. + + + + + +Doodads + + +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, if present, describes the outline of the +entire keyboard. + + + + +Each doodad’s origin is stored in fields named +left + and +top +, which are the coordinates of the doodad’s origin relative to its enclosing +object, whether it be a section or the top-level keyboard. The priority for +doodads that are listed in the top-level geometry is relative to the other +doodads listed in the top-level geometry and the sections listed in the +top-level geometry. The priority for doodads listed in a section are relative +to the other components of the section. Each doodad is stored in a structure +with a +type + field, which specifies the type of doodad. + + + +Xkb supports five types 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. + + + + + +The structures these doodads are stored in and the values of the +type + fields are shown in Table 13.1. + + + +Doodad Types + + + + + Doodad + Structure + Type + + + + + +indicator doodad + + +XkbIndicatorDoodadRec + + +XkbIndicatorDoodad + + + + +outline doodad + + +XkbShapeDoodadRec + + +XkbOutlineDoodad + + + + +solid doodad + + +XkbShapeDoodadRec + + +XkbSolidDoodad + + + + +text doodad + + +XkbTextDoodadRec + + +XkbTextDoodad + + + + +logo doodad + + +XkbLogoDoodadRec + + +XkbLogoDoodad + + + + +
+ + + +Overlay Rows and Overlay Keys + + +An +overlay row + ( +XkbOverlayRowRec +) contains a pointer to the row it overlays and a list of +overlay keys +. + + + + +Each overlay key definition ( +XkbOverlayKeyRec +) indicates a key that can yield multiple keycodes 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 be. + + + + + +Drawing a Keyboard Representation + + +To draw a representation of the keyboard, draw in the following order: + + + + Draw the top-level keyboard as a rectangle, using its width and height. + For each component (section or doodad) of the top-level geometry, in priority order: + If component is a section + For each row, in the order it appears in the section + Draw keys in the order they appear in the row + Draw doodads within the section in priority order. + Else draw doodad + + + + +Geometry Data Structures + + +In the following figures, a solid arrow denotes a pointer to an array of +structures or a singleton structure. A dotted arrow denotes an index or a +pointer into the array. + + + + + + +Xkb Geometry Data Structures + + + + + + +Xkb Geometry Data Structures (Doodads) + + + + + + + + +Xkb Geometry Data Structures (Overlays) + + + + +typedef struct _XkbGeometry { /* top-level keyboard geometry structure */ + Atom name; /* keyboard name */ + unsigned short width_mm; /* keyboard width in mm / 10 */ + unsigned short height_mm; /* keyboard height in mm / 10 */ + char * label_font; /* font for key labels */ + XkbColorPtr label_color; /* color for key labels - pointer into colors array */ + XkbColorPtr base_color; /* color for basic keyboard - pointer into colors array */ + unsigned short sz_properties; /* size of properties array */ + unsigned short sz_colors; /* size of colors array */ + unsigned short sz_shapes; /* size of shapes array */ + unsigned short sz_sections; /* size of sections array */ + unsigned short sz_doodads; /* size of doodads array */ + unsigned short sz_key_aliases; /* size of key aliases array */ + unsigned short num_properties; /* number of properties in the properties array */ + unsigned short num_colors; /* number of colors in the colors array */ + unsigned short num_shapes; /* number of shapes in the shapes array */ + unsigned short num_sections; /* number of sections in the sections array */ + unsigned short num_doodads; /* number of doodads in the doodads array */ + unsigned short num_key_aliases; /* number of key aliases in the key */ + XkbPropertyPtr properties; /* properties array */ + XkbColorPtr colors; /* colors array */ + XkbShapePtr shapes; /* shapes array */ + XkbSectionPtr sections; /* sections array */ + XkbDoodadPtr doodads; /* doodads array */ + XkbKeyAliasPtr key_aliases; /* key aliases array */ +} XkbGeometryRec*XkbGeometryPtr; + + + +The +doodads + array is only for doodads not contained in any of the +sections + that has its own +doodads +. The key aliases contained in the +key_aliases + array take precedence over any defined in the keycodes component of the +keyboard description. + + + +typedef struct _XkbProperty { + char * name; /* property name */ + char * value; /* property value */ +} XkbPropertyRec,*XkbPropertyPtr; + + + +typedef struct _XkbColor { + unsigned int pixel; /* color */ + char * spec; /* color name */ +} XkbColorRec,*XkbColorPtr; + + + +typedef struct _XkbKeyAliasRec { + char real[XkbKeyNameLength]; /* real name of the key */ + char alias[XkbKeyNameLength]; /* alias for the key */ +} XkbKeyAliasRec,*XkbKeyAliasPtr; + + + +typedef struct _XkbPoint { /* x,y coordinates */ + short x; + short y; +} XkbPointRec, *XkbPointPtr; + + + +typedef struct _XkbOutline { + unsigned short num_points; /* number of points in the outline */ + unsigned short sz_points; /* size of the points array */ + unsigned short corner_radius; /* draw corners as circles with this radius */ + XkbPointPtr points; /* array of points defining the outline */ +} XkbOutlineRec, *XkbOutlinePtr; + + + +typedef struct _XkbBounds { + short x1,y1; /* upper left corner of the bounds, + in mm/10 */ + short x2,y2; /* lower right corner of the bounds, in + mm/10 */ +} XkbBoundsRec, *XkbBoundsPtr; + + + +typedef struct _XkbShape { + Atom name; /* shape’s name */ + unsigned short num_outlines; /* number of outlines for the shape */ + unsigned short sz_outlines; /* size of the outlines array */ + XkbOutlinePtr outlines; /* array of outlines for the shape */ + XkbOutlinePtr approx; /* pointer into the array to the approximating outline */ + XkbOutlinePtr primary; /* pointer into the array to the primary outline */ + XkbBoundsRec bounds; /* bounding box for the shape; encompasses all outlines */ +} XkbShapeRec, *XkbShapePtr; + + + +If +approx + and/or +primary + is +NULL +, the default value is used. The default primary outline is the first element +in the outlines array, as is the default approximating outline. + + + +typedef struct _XkbKey { /* key in a row */ + XkbKeyNameRec name; /* key name */ + short gap; /* gap in mm/10 from previous key in row */ + unsigned char shape_ndx; /* index of shape for key */ + unsigned char color_ndx; /* index of color for key body */ +} XkbKeyRec, *XkbKeyPtr; + + + +typedef struct _XkbRow { /* row in a section */ + short top; /* top coordinate of row origin, relative to section’s origin */ + short left; /* left coordinate of row origin, relative to section’s origin */ + unsigned short num_keys; /* number of keys in the keys array */ + unsigned short sz_keys; /* size of the keys array */ + int vertical; /* True =>vertical row, + False =>horizontal row */ + XkbKeyPtr keys; /* array of keys in the row*/ + XkbBoundsRec bounds; /* bounding box for the row */ +} XkbRowRec, *XkbRowPtr; + + + + +top + and +left + are in +mm +/ +10 +. + + + +typedef struct _XkbOverlayRec { + Atom name; /* overlay name */ + XkbSectionPtr section_under; /* the section under this overlay */ + unsigned short num_rows; /* number of rows in the rows array */ + unsigned short sz_rows; /* size of the rows array */ + XkbOverlayRowPtr rows; /* array of rows in the overlay */ + XkbBoundsPtr bounds; /* bounding box for the overlay */ +} XkbOverlayRec,*XkbOverlayPtr; + + + +typedef struct _XkbOverlayRow { + unsigned short row_under; /* index into the row under this overlay row */ + unsigned short num_keys; /* number of keys in the keys array */ + unsigned short sz_keys; /* size of the keys array */ + XkbOverlayKeyPtr keys; /* array of keys in the overlay row */ +} XkbOverlayRowRec,*XkbOverlayRowPtr; + + + + +row_under + is an index into the array of +rows + in the section under this overlay. The section under this overlay row is the +one pointed to by +section_under + in this overlay row’s +XkbOverlayRec +. + + + +typedef struct _XkbOverlayKey { + XkbKeyNameRec over; /* name of this overlay key */ + XkbKeyNameRec under; /* name of the key under this overlay key */ +} XkbOverlayKeyRec,*XkbOverlayKeyPtr; + + + +typedef struct _XkbSection { + Atom name; /* section name */ + unsigned char priority; /* drawing priority, 0=>highest, 255=>lowest */ + short top; /* top coordinate of section origin */ + short left; /* left coordinate of row origin */ + unsigned short width; /* section width, in mm/10 */ + unsigned short height; /* section height, in mm/10 */ + short angle; /* angle of section rotation, counterclockwise */ + unsigned short num_rows; /* number of rows in the rows array */ + unsigned short num_doodads; /* number of doodads in the doodads array */ + unsigned short num_overlays; /* number of overlays in the overlays array */ + unsigned short sz_rows; /* size of the rows array */ + unsigned short sz_doodads; /* size of the doodads array */ + unsigned short sz_overlays; /* size of the overlays array */ + XkbRowPtr rows; /* section rows array */ + XkbDoodadPtr doodads; /* section doodads array */ + XkbBoundsRec bounds; /* bounding box for the section, before rotation*/ + XkbOverlayPtr overlays; /* section overlays array */ +} XkbSectionRec, *XkbSectionPtr; + + + + +top + and +left + are the origin of the section, relative to the origin of the keyboard, in + +mm +/ +10 +. +angle + is in +1 +/ +10 + degrees. + + + +DoodadRec Structures + + +The doodad arrays in the +XkbGeometryRec + and the +XkbSectionRec + may contain any of the doodad structures and types shown in Table 13.1. + + + + +The doodad structures form a union: + + + +typedef union _XkbDoodad { + XkbAnyDoodadRec any; + XkbShapeDoodadRec shape; + XkbTextDoodadRec text; + XkbIndicatorDoodadRec indicator; + XkbLogoDoodadRec logo; +} XkbDoodadRec, *XkbDoodadPtr; + + + +The +top + and +left + coordinates of each doodad are the coordinates of the origin of the doodad +relative to the keyboard’s origin if the doodad is in the +XkbGeometryRec + doodad array, and with respect to the section’s origin if the doodad is in a + +XkbSectionRec + doodad array. The +color_ndx + or +on_color_ndx + and +off_color_ndx + fields are color indices into the +XkbGeometryRec +’s color array and are the colors to draw the doodads with. Similarly, the + +shape_ndx + fields are indices into the +XkbGeometryRec +’s shape array. + + + +typedef struct _XkbShapeDoodad { + Atom name; /* doodad name */ + unsigned char type; /* XkbOutlineDoodad + or XkbSolidDoodad */ + unsigned char priority; /* drawing priority, + 0=>highest, 255=>lowest */ + short top; /* top coordinate, in mm/10 */ + short left; /* left coordinate, in mm/10 */ + short angle; /* angle of rotation, clockwise, in 1/10 degrees */ + unsigned short color_ndx; /* doodad color */ + unsigned short shape_ndx; /* doodad shape */ +} XkbShapeDoodadRec, *XkbShapeDoodadPtr; + + + +typedef struct _XkbTextDoodad { + Atom name; /* doodad name */ + unsigned char type; /* XkbTextDoodad */ + unsigned char priority; /* drawing priority, + 0=>highest, 255=>lowest */ + short top; /* top coordinate, in mm/10 */ + short left; /* left coordinate, in mm/10 */ + short angle; /* angle of rotation, clockwise, in 1/10 degrees */ + short width; /* width in mm/10 */ + short height; /* height in mm/10 */ + unsigned short color_ndx; /* doodad color */ + char * text; /* doodad text */ + char * font; /* arbitrary font name for doodad text */ +} XkbTextDoodadRec, *XkbTextDoodadPtr; + + + +typedef struct _XkbIndicatorDoodad { + Atom name; /* doodad name */ + unsigned char type; /* XkbIndicatorDoodad */ + unsigned char priority; /* drawing priority, 0=>highest, 255=>lowest */ + short top; /* top coordinate, in mm/10 */ + short left; /* left coordinate, in mm/10 */ + short angle; /* angle of rotation, clockwise, in 1/10 degrees */ + unsigned short shape_ndx; /* doodad shape */ + unsigned short on_color_ndx; /* color for doodad if indicator is on */ + unsigned short off_color_ndx; /* color for doodad if indicator is off */ +} XkbIndicatorDoodadRec, *XkbIndicatorDoodadPtr; + + + +typedef struct _XkbLogoDoodad { + Atom name; /* doodad name */ + unsigned char type; /* XkbLogoDoodad */ + unsigned char priority; /* drawing priority, 0=>highest, 255=>lowest */ + short top; /* top coordinate, in mm/10 */ + short left; /* left coordinate, in mm/10 */ + short angle; /* angle of rotation, clockwise, in 1/10 degrees */ + unsigned short color_ndx; /* doodad color */ + unsigned short shape_ndx; /* doodad shape */ + char * logo_name; /* text for logo */ +} XkbLogoDoodadRec, *XkbLogoDoodadPtr + + + + + +Getting Keyboard Geometry From the Server + + +You can load a keyboard geometry as part of the keyboard description returned +by +XkbGetKeyboard +. However, if a keyboard description has been previously loaded, you can +instead obtain the geometry by calling the +XkbGetGeometry +. In this case, the geometry returned is the one associated with the keyboard +whose device ID is contained in the keyboard description. + + + +To load a keyboard geometry if you already have the keyboard description, use +XkbGetGeometry. + + + + + + + + +Status +XkbGetGeometry +( +dpy +, + xkb +) + + + + +Display * +dpy +; /* connection to the X server */ + + + + +XkbDescPtr + xkb +; /* keyboard description that contains the ID for the keyboard and into +which the geometry should be loaded */ + + + + + + + + +XkbGetGeometry + can return +BadValue +, +BadImplementation +, +BadName +, +BadAlloc, + or +BadLength + errors or +Success + if it succeeds. + + + +It is also possible to load a keyboard geometry by name. The X server maintains +a database of keyboard components (see Chapter 20). To load a keyboard geometry +description from this database by name, use +XkbGetNamedGeometry. + + + + + + + + +Status +XkbGetNamedGeometry +( +dpy +, + xkb +, + name +) + + + + +Display * +dpy +; /* connection to the X server */ + + + + +XkbDescPtr +xkb +; /* keyboard description into which the geometry should be loaded */ + + + + +Atom +name +; /* name of the geometry to be loaded */ + + + + + + + + +XkbGetNamedGeometry + can return +BadName + if the +name + cannot be found. + + + + +Using Keyboard Geometry + + +Xkb provides a number of convenience functions to help use a keyboard geometry. +These include functions to return the bounding box of a shape’s top surface +and to update the bounding box of a shape row or section. + + + +A shape is made up of a number of outlines. Each outline is a polygon made up +of a number of points. The bounding box of a shape is a rectangle that contains +all the outlines of that shape. + + + + + +Key Surface, Shape Outlines, and Bounding Box + + + + + + +To determine the bounding box of the top surface of a shape, use +XkbComputeShapeTop. + + + + + + + + +Bool +XkbComputeShapeTop +( +shape +, + bounds_rtrn +) + + + + +XkbShapePtr + shape +; /* shape to be examined */ + + + + +XkbBoundsPtr + bounds_rtrn + /* backfilled with the bounding box for the shape */ + + + + + + + + +XkbComputeShapeTop + returns a +BoundsRec + that contains two x and y coordinates. These coordinates describe the corners +of a rectangle that contains the outline that describes the top surface of the +shape. The top surface is defined to be the approximating outline if the + +approx + field of +shape + is not +NULL +. If +approx + is +NULL +, the top surface is defined as the last outline in the +shape +’s array of outlines. +XkbComputeShapeTop + returns +False + if +shape + is +NULL + or if there are no outlines for the shape; otherwise, it returns +True. + + + + +A +ShapeRec + contains a +BoundsRec + that describes the bounds of the shape. If you add or delete an outline to or +from a shape, the bounding box must be updated. To update the bounding box of a +shape, use XkbComputeShapeBounds. + + + + + + + + + +Bool +XkbComputeShapeBounds +( +shape +) + + + + +XkbShapePtr + shape +; /* shape to be examined */ + + + + + + + + +XkbComputeShapeBounds + updates the +BoundsRec + contained in the +shape + by examining all the outlines of the shape and setting the +BoundsRec + to the minimum x and minimum y, and maximum x and maximum y values found in +those outlines. +XkbComputeShapeBounds + returns +False + if +shape + is +NULL + or if there are no outlines for the shape; otherwise, it returns +True +. + + + + If you add or delete a key to or from a row, or if you update the shape of one +of the keys in that row, you may need to update the bounding box of that row. +To update the bounding box of a row, use XkbComputeRowBounds. + + + + + + + + +Bool +XkbComputeRowBounds +( +geom +, + section +, + row +) + + + + +XkbGeometryPtr + geom +; /* geometry that contains the +section + */ + + + + +XkbSectionPtr + section +; /* section that contains the row */ + + + + +XkbRowPtr +row +; /* row to be examined and updated */ + + + + + + + + +XkbComputeRowBounds + checks the bounds of all keys in the +row +and updates the bounding box of the row if necessary. +XkbComputeRowBounds + returns +False + if any of the arguments is +NULL +; otherwise, it returns +True +. + + + + If you add or delete a row to or from a section, or if you change the geometry +of any of the rows in that section, you may need to update the bounding box for +that section. To update the bounding box of a section, use +XkbComputeSectionBounds. + + + + + + + + +Bool +XkbComputeSectionBounds +( +geom +, + section +) + + + + +XkbGeometryPtr + geom +; /* geometry that contains the +section + */ + + + + +XkbSectionPtr + section +; /* section to be examined and updated */ + + + + + + + + +XkbComputeSectionBounds + examines all the rows of the +section + and updates the bounding box of that section so that it contains all rows. + +XkbComputeSectionBounds + returns +False + if any of the arguments is +NULL +; otherwise, it returns +True +. + + + +Keys that can generate multiple keycodes may be associated with multiple names. +Such keys have a primary name and an alternate name. To find the alternate name +by using the primary name for a key that is part of an overlay, use +XkbFindOverlayForKey. + + + + + + + + +char * +XkbFindOverlayForKey +( +geom +, + section +, + under +) + + + + +XkbGeometryPtr + geom +; /* geometry that contains the +section + */ + + + + +XkbSectionPtr + section +; /* section to be searched for matching keys */ + + + + +char * + under +. /* primary name of the key to be considered */ + + + + + + + + +XkbFindOverlayForKey + uses the primary name of the key, +under +, to look up the alternate name, which it returns. + + + + + +Adding Elements to a Keyboard Geometry + + +Xkb provides functions to add a single new element to the top-level keyboard +geometry. In each case the +num_ + +* + fields of the corresponding structure is incremented by 1. These functions do +not change +sz_ + +* + unless there is no more room in the array. Some of these functions fill in the +values of the element’s structure from the arguments. For other functions, +you must explicitly write code to fill the structure’s elements. + + + + +The top-level geometry description includes a list of +geometry properties +. A geometry property associates an arbitrary string with an equally arbitrary +name. Programs that display images of keyboards can use geometry properties as +hints, but they are not interpreted by Xkb. No other geometry structures refer +to geometry properties. + + + + +To add one property to an existing keyboard geometry description, use +XkbAddGeomProperty +. + + + + + + + + +XkbPropertyPtr +XkbAddGeomProperty +( +geom +, + name +, + value +) + + + + +XkbGeometryPtr + geom +; /* geometry to be updated */ + + + + +char * + name +; /* name of the new property */ + + + + +char * + value +; /* value for the new property */ + + + + + + + + +XkbAddGeomProperty + adds one property with the specified +name + and +value + to the keyboard geometry specified by geom. + + +XkbAddGeomProperty + returns +NULL + if any of the parameters is empty or if it was not able to allocate space for +the property. To allocate space for an arbitrary number of properties, use the +XkbAllocGeomProps function. + + + + +To add one key alias to an existing keyboard geometry description, use + +XkbAddGeomKeyAlias +. + + + + + + + + + +XkbKeyAliasPtr +XkbAddGeomKeyAlias +( +geom +, + alias, real +) + + + + +XkbGeometryPtr + geom +; /* geometry to be updated */ + + + + +char * + alias +; /* alias to be added */ + + + + +char * + real +; /* real name to be bound to the new alias */ + + + + + + + + +XkbAddGeomKeyAlias + adds one key alias with the value alias to the geometry geom, and associates +it with the key whose real name is real. +XkbAddGeomKeyAlias + returns +NULL + if any of the parameters is empty or if it was not able to allocate space for +the alias. To allocate space for an arbitrary number of aliases, use the +XkbAllocGeomKeyAliases function. + + + + +To add one color name to an existing keyboard geometry description, use + +XkbAddGeomColor +. + + + + + + + + + +XkbColorPtr +XkbAddGeomColor +( +geom +, + spec +, + pixel +) + + + + +XkbGeometryPtr + geom +; /* geometry to be updated */ + + + + +char * + spec +; /* color to be added */ + + + + +unsigned int + pixel +; /* color to be added */ + + + + + + + + +XkbAddGeomColor + adds the specified color +name + and +pixel + to the specified geometry +geom +. The top-level geometry description includes a list of up to +MaxColors + (32) +color names +. A color +name + is a string whose interpretation is not specified by Xkb and neither is the + +pixel + value’s interpretation. All other geometry data structures refer to colors +using their indices in this global list or pointers to colors in this list. + +XkbAddGeomColor + returns +NULL + if any of the parameters is empty or if it was not able to allocate space for +the color. To allocate space for an arbitrary number of colors to a geometry, +use the +XkbAllocGeomColors + function. + + + +To add one outline to an existing shape, use +XkbAddGeomOutline. + + + + + + + + +XkbOutlinePtr +XkbAddGeomOutline +( +shape +, + sz_points +) + + + + +XkbShapePtr + shape +; /* shape to be updated */ + + + + +int + sz_points +; /* number of points to be reserved */ + + + + + + + +An outline consists of an arbitrary number of points. +XkbAddGeomOutline + adds an outline to the specified +shape + by reserving +sz_points + points for it. The new outline is allocated and zeroed. +XkbAddGeomOutline + returns +NULL + if any of the parameters is empty or if it was not able to allocate space. To +allocate space for an arbitrary number of outlines to a shape, use +XkbAllocGeomOutlines. + + + + +To add a shape to a keyboard geometry, use +XkbAddGeomShape +. + + + + + + + + + +XkbShapePtr +XkbAddGeomShape +( +geom +, + name +, + sz_outlines +) + + + + +XkbGeometryPtr + geom +; /* geometry to be updated */ + + + + +Atom + name +; /* name of the new shape */ + + + + +int + sz_outlines +; /* number of outlines to be reserved */ + + + + + + + +A geometry contains an arbitrary number of shapes, each of which is made up of +an arbitrary number of outlines. +XkbAddGeomShape + adds a shape to a geometry +geom + by allocating space for +sz_outlines + outlines for it and giving it the name specified by name. If a shape with name + +name + already exists in the geometry, a pointer to the existing shape is returned. + +XkbAddGeomShape + returns +NULL + if any of the parameters is empty or if it was not able to allocate space. To +allocate space for an arbitrary number of geometry shapes, use +XkbAllocGeomShapes +. + + + + +To add one key at the end of an existing row of keys, use +XkbAddGeomKey +. + + + + + + + + + +XkbKeyPtr +XkbAddGeomKey +( +row +) + + + + +XkbRowPtr + row +; /* row to be updated */ + + + + + + + +Keys are grouped into rows. +XkbAddGeomKey + adds one key to the end of the specified +row +. The key is allocated and zeroed. +XkbAddGeomKey + returns +NULL + if +row + is empty or if it was not able to allocate space for the key. To allocate +space for an arbitrary number of keys to a row, use XkbAllocGeomKeys. + + + + +To add one section to an existing keyboard geometry, use +XkbAddGeomSection +. + + + + + + + + + +XkbSectionPtr +XkbAddGeomSection +( +geom +, + name +, + sz_rows +, + sz_doodads +, + sz_overlays +) + + + + +XkbGeometryPtr + geom +; /* geometry to be updated */ + + + + +Atom + name +; /* name of the new section */ + + + + +int + sz_rows +; /* number of rows to reserve in the section */ + + + + +int + sz_doodads +; /* number of doodads to reserve in the section */ + + + + +int + sz_overlays +; /* number of overlays to reserve in the section */ + + + + + + + +A keyboard geometry contains an arbitrary number of sections. +XkbAddGeomSection + adds one section to an existing keyboard geometry +geom +. The new section contains space for the number of rows, doodads, and overlays +specified by +sz_rows +, +sz_doodads +, and +sz_overlays +. The new section is allocated and zeroed and given the name specified by + +name +. If a section with name +name + already exists in the geometry, a pointer to the existing section is +returned. + XkbAddGeomSection + returns +NULL + if any of the parameters is empty or if it was not able to allocate space for +the section. To allocate space for an arbitrary number of sections to a +geometry, use XkbAllocGeomSections. + + + + +To add a row to a section, use +XkbAddGeomRow +. + + + + + + + + + +XkbRowPtr +XkbAddGeomRow +( +section +, + sz_keys +) + + + + +XkbSectionPtr + section +; /* section to be updated */ + + + + +int +sz_keys +; /* number of keys to be reserved */ + + + + + + + +One of the components of a keyboard geometry section is one or more rows of +keys. +XkbAddGeomRow + adds one row to the specified +section +. The newly created row contains space for the number of keys specified in + +sz_keys +. They are allocated and zeroed, but otherwise uninitialized. +XkbAddGeomRow + returns +NULL + if any of the parameters is empty or if it was not able to allocate space for +the row. To allocate space for an arbitrary number of rows to a section, use +the XkbAllocGeomRows function. + + + + +To add one doodad to a section of a keyboard geometry or to the top-level +geometry, use +XkbAddGeomDoodad +. + + + + + + + + + +XkbDoodadPtr +XkbAddGeomDoodad +( +geom +, + section +, + name +) + + + + +XkbGeometryPtr + geom +; /* geometry to which the doodad is added */ + + + + +XkbSectionPtr + section +; /* section, if any, to which the doodad is added */ + + + + +Atom + name +; /* name of the new doodad */ + + + + + + + +A +doodad + describes some visible aspect of the keyboard that is not a key and is not a +section. +XkbAddGeomDoodad + adds a doodad with name specified by name to the geometry +geom + if section is +NULL + or to the section of the geometry specified by section if +section + is not +NULL +. +XkbAddGeomDoodad + returns +NULL + if any of the parameters is empty or if it was not able to allocate space for +the doodad. If there is already a doodad with the name +name + in the doodad array for the geometry (if +section + is +NULL +) or the section (if +section + is non- +NULL +), a pointer to that doodad is returned. To allocate space for an arbitrary +number of doodads to a section, use the XkbAllocGeomSectionDoodads function. To +allocate space for an arbitrary number of doodads to a keyboard geometry, use +the XkbAllocGeomDoodads function. + + + + +To add one overlay to a section, use +XkbAddGeomOverlay +. + + + + + + + + + +XkbOverlayPtr +XkbAddGeomOverlay +( +section +, + name +, + sz_rows +) + + + + +XkbSectionPtr + section +; /* section to which an overlay will be added */ + + + + +Atom + name +; /* name of the overlay */ + + + + +int + sz_rows +; /* number of rows to reserve in the overlay */ + + + + + + + + +XkbAddGeomOverlay + adds an overlay with the specified name to the specified +section +. The new overlay is created with space allocated for sz_rows rows. If an +overlay with name +name + already exists in the section, a pointer to the existing overlay is +returned. + XkbAddGeomOverlay + returns +NULL + if any of the parameters is empty or if it was not able to allocate space for +the overlay. To allocate space for an arbitrary number of overlays to a +section, use the XkbAllocGeomOverlay function. + + + + +To add a row to an existing overlay, use +XkbAddGeomOverlayRow +. + + + + + + + + + +XkbOverlayRowPtr +XkbAddGeomOverlayRow +( +overlay +, + row_under, sz_keys +) + + + + +XkbOverlayPtr + overlay +; /* overlay to be updated */ + + + + +XkbRowPtr + row_under +; /* row to be overlayed in the section +overlay + overlays */ + + + + +int + sz_keys +; /* number of keys to reserve in the row */ + + + + + + + + +XkbAddGeomOverlayRow + adds one row to the +overlay +. The new row contains space for +sz_keys + keys. If +row_under + specifies a row that doesn’t exist on the underlying section, +XkbAddGeomOverlayRow + returns +NULL + and doesn’t change the overlay. + XkbAddGeomOverlayRow + returns +NULL + if any of the parameters is empty or if it was not able to allocate space for +the overlay. + + + + +To add a key to an existing overlay row, use +XkbAddGeomOverlayKey +. + + + + + + + + + +XkbOverlayKeyPtr +XkbAddGeomOverlayKey +( +overlay +, + row, under +) + + + + +XkbOverlayPtr + overlay +; /* overlay to be updated */ + + + + +XkbRowPtr + row +; /* row in overlay to be updated */ + + + + +char * + under +; /* primary name of the key to be considered */ + + + + + + + + +XkbAddGeomOverlayKey + adds one key to the +row + in the +overlay +. If there is no key named +under + in the row of the underlying section, +XkbAddGeomOverlayKey + returns +NULL +. + + + + + +Allocating and Freeing Geometry Components + + +Xkb provides a number of functions to allocate and free subcomponents of a +keyboard geometry. Use these functions to create or modify keyboard geometries. +Note that these functions merely allocate space for the new element(s), and it +is up to you to fill in the values explicitly in your code. These allocation +functions increase +sz_ + +* + but never touch +num_ + +* + (unless there is an allocation failure, in which case they reset both + +sz_ + +* + and +num_ + +* + to zero). These functions return +Success + if they succeed, +BadAlloc + if they are not able to allocate space, or +BadValue + if a parameter is not as expected. + + + + +To allocate space for an arbitrary number of outlines to a shape, use +XkbAllocGeomOutlines. + + + + + + + + +Status +XkbAllocGeomOutlines +( +shape +, + num_needed +) + + + + +XkbShapePtr +shape +; /* shape for which outlines should be allocated */ + + + + +int + num_needed +; /* number of new outlines required */ + + + + + + + + +XkbAllocGeomOutlines + allocates space for +num_needed + outlines in the specified +shape +. The outlines are not initialized. + + + + +To free geometry outlines, use +XkbFreeGeomOutlines +. + + + + + + + + + +void +XkbFreeGeomOutlines +( +shape +, + first +, + count +, + free_all +) + + + + +XkbShapePtr + shape +; /* shape in which outlines should be freed */ + + + + +int + first +; /* first outline to be freed */ + + + + +int + count +; /* number of outlines to be freed */ + + + + +Bool + free_all; + /* +True + => all outlines are freed */ + + + + + + + +If free_all is +True +, all outlines are freed regardless of the value of first or count. Otherwise, +count outlines are freed beginning with the one specified by first. + + + + +To allocate space for an arbitrary number of keys to a row, use +XkbAllocGeomKeys. + + + + + + + + + +Status +XkbAllocGeomKeys +( +row +, + num_needed +) + + + + +XkbRowPtr + row +; /* row to which keys should be allocated */ + + + + +int + num_needed +; /* number of new keys required */ + + + + + + + + +XkbAllocGeomKeys + allocates num_needed keys and adds them to the row. No initialization of the +keys is done. + + + + +To free geometry keys, use +XkbFreeGeomKeys +. + + + + + + + + + +void +XkbFreeGeomKeys +( +row +, + first +, + count +, + free_all +) + + + + +XkbRowPtr + row +; /* row in which keys should be freed */ + + + + +int + first +; /* first key to be freed */ + + + + +int + count +; /* number of keys to be freed */ + + + + +Bool + free_all; + /* +True + => all keys are freed */ + + + + + + + +If free_all is +True +, all keys are freed regardless of the value of first or count. Otherwise, +count keys are freed beginning with the one specified by first. + + + + +To allocate geometry properties, use +XkbAllocGeomProps +. + + + + + + + + + +Status +XkbAllocGeomProps +( +geom +, + num_needed +) + + + + +XkbGeometryPtr + geom +; /* geometry for which properties should be allocated */ + + + + +int + num_needed +; /* number of new properties required */ + + + + + + + + +XkbAllocGeomProps + allocates space for num_needed properties and adds them to the specified +geometry +geom +. No initialization of the properties is done. 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. + + + + +To free geometry properties, use +XkbFreeGeomProperties +. + + + + + + + + + +void +XkbFreeGeomProperties +( +geom +, + first +, + count +, + free_all +) + + + + +XkbGeometryPtr + geom +; /* geometry in which properties should be freed */ + + + + +int + first +; /* first property to be freed */ + + + + +int + count +; /* number of properties to be freed */ + + + + +Bool + free_all; + /* +True + => all properties are freed */ + + + + + + + +If free_all is +True +, all properties are freed regardless of the value of first or count. +Otherwise, count properties are freed beginning with the one specified by first. + + + + +To allocate geometry key aliases, use +XkbAllocGeomKeyAliases +. + + + + + + + + + +Status +XkbAllocGeomKeyAliases +( +geom +, + num_needed +) + + + + +XkbGeometryPtr + geom +; /* geometry for which key aliases should be allocated */ + + + + +int + num_needed +; /* number of new key aliases required */ + + + + + + + + +XkbAllocGeomKeyAliases + allocates space for num_needed key aliases and adds them to the specified +geometry +geom +. A key alias is a pair of strings that associates an alternate name for a key +with the real name for that key. + + + + +To free geometry key aliases, use +XkbFreeGeomKeyAliases +. + + + + + + + + + +void +XkbFreeGeomKeyAliases +( +geom +, + first +, +count +, +free_all +) + + + + +XkbGeometryPtr + geom +; /* geometry in which key aliases should be freed */ + + + + +int + first +; /* first key alias to be freed */ + + + + +int + count +; /* number of key aliases to be freed */ + + + + +Bool + free_all; + /* +True + => all key aliases are freed */ + + + + + + + +If free_all is +True +, all aliases in the top level of the specified geometry +geom + are freed regardless of the value of first or count. Otherwise, count aliases +in +geom + are freed beginning with the one specified by first. + + + + +To allocate geometry colors, use +XkbAllocGeomColors +. + + + + + + + + + +Status +XkbAllocGeomColors +( +geom +, + num_needed +) + + + + +XkbGeometryPtr + geom +; /* geometry for which colors should be allocated */ + + + + +int + num_needed +; /* number of new colors required. */ + + + + + + + + +XkbAllocGeomColors + allocates space for num_needed colors and adds them to the specified geometry + +geom +. A color name is a string whose interpretation is not specified by Xkb. All +other geometry data structures refer to colors using their indices in this +global list or pointers to colors in this list. + + + + +To free geometry colors, use +XkbFreeGeomColors +. + + + + + + + + + +void +XkbFreeGeomColors +( +geom +, + first +, + count +, + free_all +) + + + + +XkbGeometryPtr + geom +; /* geometry in which colors should be freed */ + + + + +int + first +; /* first color to be freed */ + + + + +int + count +; /* number of colors to be freed */ + + + + +Bool + free_all; + /* +True + => all colors are freed */ + + + + + + + +If free_all is +True +, all colors are freed regardless of the value of first or count. Otherwise, +count colors are freed beginning with the one specified by first. + + + + +To allocate points in an outline, use +XkbAllocGeomPoints +. + + + + + + + + + +Status +XkbAllocGeomPoints +( +outline +, + num_needed +) + + + + +XkbOutlinePtr + outline +; /* outline for which points should be allocated */ + + + + +int + num_needed +; /* number of new points required */ + + + + + + + + +XkbAllocGeomPoints + allocates space for +num_needed + points in the specified +outline +. The points are not initialized. + + + + +To free points in a outline, use +XkbFreeGeomPoints +. + + + + + + + + + +void +XkbFreeGeomPoints +( +outline +, + first +, + count +, + free_all +) + + + + +XkbOutlinePtr + outline +; /* outline in which points should be freed */ + + + + +int + first +; /* first point to be freed. */ + + + + +int + count +; /* number of points to be freed */ + + + + +Bool + free_all; + /* +True + => all points are freed */ + + + + + + + +If free_all is +True +, all points are freed regardless of the value of first and count. Otherwise, +the number of points specified by count are freed, beginning with the point +specified by first in the specified outline. + + + + +To allocate space for an arbitrary number of geometry shapes, use +XkbAllocGeomShapes +. + + + + + + + + + +Status +XkbAllocGeomShapes +( +geom +, + num_needed +) + + + + +XkbGeometryPtr + geom +; /* geometry for which shapes should be allocated */ + + + + +int + num_needed +; /* number of new shapes required */ + + + + + + + + +XkbAllocGeomShapes + allocates space for +num_needed + shapes in the specified geometry +geom +. The shapes are not initialized. + + + + +To free geometry shapes, use +XkbFreeGeomShapes +. + + + + + + + + + +void +XkbFreeGeomShapes +( +geom +, + first +, + count +, + f ree_all +) + + + + +XkbGeometryPtr + geom +; /* geometry in which shapes should be freed */ + + + + +int + first +; /* first shape to be freed */ + + + + +int + count +; /* number of shapes to be freed */ + + + + +Bool + free_all; + /* +True + => all shapes are freed */ + + + + + + + +If free_all is +True +, all shapes in the geometry are freed regardless of the values of first and +count. Otherwise, count shapes are freed, beginning with the shape specified by +first. + + + + +To allocate geometry sections, use +XkbAllocGeomSections +. + + + + + + + + + +Status +XkbAllocGeomSections +( +geom +, + num_needed +) + + + + +XkbGeometryPtr + geom +; /*geometry for which sections should be allocated */ + + + + +int + num_needed +; /* number of new sections required */ + + + + + + + + +XkbAllocGeomSections + allocates num_needed sections and adds them to the geometry geom. No +initialization of the sections is done. + + + + +To free geometry sections, use +XkbFreeGeomSections +. + + + + + + + + + +void +XkbFreeGeomSections +( +geom +, + first +, + count +, + free_all +) + + + + +XkbGeometryPtr + geom +; /* geometry in which sections should be freed */ + + + + +int + first +; /* first section to be freed. */ + + + + +int + count +; /* number of sections to be freed */ + + + + +Bool + free_all; + /* +True + => all sections are freed */ + + + + + + + +If free_all is +True +, all sections are freed regardless of the value of first and count. Otherwise, +the number of sections specified by count are freed, beginning with the section +specified by first in the specified geometry. + + + + +To allocate rows in a section, use +XkbAllocGeomRows +. + + + + + + + + + +Status +XkbAllocGeomRows +( +section +, + num_needed +) + + + + +XkbSectionPtr +section +; /* section for which rows should be allocated */ + + + + +int + num_needed +; /* number of new rows required */ + + + + + + + + +XkbAllocGeomRows + allocates num_needed rows and adds them to the section. No initialization of +the rows is done. + + + + +To free rows in a section, use +XkbFreeGeomRows +. + + + + + + + + + +void +XkbFreeGeomRows +( +section +, + first +, + count +, + free_all +) + + + + +XkbSectionPtr + section +; /* section in which rows should be freed */ + + + + +int + first +; /* first row to be freed. */ + + + + +int + count +; /* number of rows to be freed */ + + + + +Bool + free_all; + /* +True + => all rows are freed */ + + + + + + + +If free_all is +True +, all rows are freed regardless of the value of first and count. Otherwise, the +number of rows specified by count are freed, beginning with the row specified +by first in the specified section. + + + + +To allocate overlays in a section, use +XkbAllocGeomOverlays +. + + + + + + + + + +Status +XkbAllocGeomOverlays +( +section +, + num_needed +) + + + + +XkbSectionPtr +section +; /* section for which overlays should be allocated */ + + + + +int + num_needed +; /* number of new overlays required */ + + + + + + + + +XkbAllocGeomRows + allocates num_needed overlays and adds them to the section. No initialization +of the overlays is done. + + + + +To free rows in an section, use +XkbFreeGeomOverlays +. + + + + + + + + + +void +XkbFreeGeomOverlays +( +section +, + first +, + count +, + free_all +) + + + + +XkbSectionPtr + section +; /* section in which overlays should be freed */ + + + + +int + first +; /* first overlay to be freed. */ + + + + +int + count +; /* number of overlays to be freed */ + + + + +Bool + free_all; + /* +True + => all overlays are freed */ + + + + + + + +If free_all is +True +, all overlays are freed regardless of the value of first and count. Otherwise, +the number of overlays specified by count are freed, beginning with the overlay +specified by first in the specified section. + + + + +To allocate rows in a overlay, use +XkbAllocGeomOverlayRows +. + + + + + + + + + +Status +XkbAllocGeomOverlayRows +( +overlay +, + num_needed +) + + + + +XkbSectionPtr +overlay +; /* section for which rows should be allocated */ + + + + +int + num_needed +; /* number of new rows required */ + + + + + + + + +XkbAllocGeomOverlayRows + allocates num_needed rows and adds them to the overlay. No initialization of +the rows is done. + + + + +To free rows in an overlay, use +XkbFreeGeomOverlayRows +. + + + + + + + + + +void +XkbFreeGeomOverlayRows +( +overlay +, + first +, + count +, + free_all +) + + + + +XkbSectionPtr + overlay +; /* section in which rows should be freed */ + + + + +int + first +; /* first row to be freed. */ + + + + +int + count +; /* number of rows to be freed */ + + + + +Bool + free_all; + /* +True + => all rows are freed */ + + + + + + + +If free_all is +True +, all rows are freed regardless of the value of first and count. Otherwise, the +number of rows specified by count are freed, beginning with the row specified +by first in the specified overlay. + + + + +To allocate keys in an overlay row, use +XkbAllocGeomOverlayKeys +. + + + + + + + + + +Status +XkbAllocGeomOverlayKeys +( +row +, + num_needed +) + + + + +XkbRowPtr +row +; /* section for which rows should be allocated */ + + + + +int + num_needed +; /* number of new rows required */ + + + + + + + + +XkbAllocGeomOverlayKeys + allocates num_needed keys and adds them to the row. No initialization of the +keys is done. + + + + +To free keys in an overlay row, use +XkbFreeGeomOverlayKeys +. + + + + + + + + + +void +XkbFreeGeomOverlayKeys +( +row +, + first +, + count +, + free_all +) + + + + +XkbRowPtr + row +; /* row in which keys should be freed */ + + + + +int + first +; /* first key to be freed. */ + + + + +int + count +; /* number of keys to be freed */ + + + + +Bool + free_all; + /* +True + => all keys are freed */ + + + + + + + +If free_all is +True +, all keys are freed regardless of the value of first and count. Otherwise, the +number of keys specified by count are freed, beginning with the key specified +by first in the specified row. + + + + +To allocate doodads that are global to a keyboard geometry, use +XkbAllocGeomDoodads +. + + + + + + + + + +Status +XkbAllocGeomDoodads +( +geom +, + num_needed +) + + + + +XkbGeometryPtr + geom +; /* geometry for which doodads should be allocated */ + + + + +int + num_needed +; /* number of new doodads required */ + + + + + + + + +XkbAllocGeomDoodads + allocates num_needed doodads and adds them to the specified geometry +geom +. No initialization of the doodads is done. + + + + +To allocate doodads that are specific to a section, use +XkbAllocGeomSectionDoodads +. + + + + + + + + + +Status +XkbAllocGeomSectionDoodads +( +section +, + num_needed +) + + + + +XkbSectionPtr + section +; /* section for which doodads should be allocated */ + + + + +int + num_needed +; /* number of new doodads required */ + + + + + + + + +XkbAllocGeomSectionDoodads + allocates num_needed doodads and adds them to the specified +section +. No initialization of the doodads is done. + + + + +To free geometry doodads, use +XkbFreeGeomDoodads +. + + + + + + + + + +void +XkbFreeGeomDoodads +( +doodads +, + count +, + free_all +) + + + + +XkbDoodadPtr + doodads +; /* doodads to be freed */ + + + + +int + count +; /* number of doodads to be freed */ + + + + +Bool + free_all; + /* +True + => all doodads are freed */ + + + + + + + +If +free_all + is +True +, all doodads in the array are freed, regardless of the value of count. +Otherwise, count doodads are freed. + + + + +To allocate an entire geometry, use +XkbAllocGeometry +. + + + + + + + + + +Status +XkbAllocGeometry +( +xkb +, + sizes +) + + + + +XkbDescPtr + xkb +; /* keyboard description for which geometry is to be allocated */ + + + + +XkbGeometrySizesPtr + sizes +; /* initial sizes for all geometry components */ + + + + + + + + +XkbAllocGeometry + allocates a keyboard geometry and adds it to the keyboard description +specified by xkb. The keyboard description should be obtained via the +XkbGetKeyboard or XkbAllockeyboard functions. The sizes parameter specifies the +number of elements to be reserved for the subcomponents of the keyboard +geometry and can be zero or more. These subcomponents include the properties, +colors, shapes, sections, and doodads. + + + + +To free an entire geometry, use +XkbFreeGeometry +. + + + + + + + + + +void +XkbFreeGeometry +( +geom +, + which +, + free_all +) + + + + +XkbGeometryPtr + geom +; /* geometry to be freed */ + + + + +unsigned int + which +; /* mask of geometry components to be freed */ + + + + +Bool + free_all; + /* +True + => the entire geometry is freed. */ + + + + + + + +The values of which and free_all determine how much of the specified geometry +is freed. The valid values for which are: + + + +#define XkbGeomPropertiesMask (1<<0) +#define XkbGeomColorsMask (1<<1) +#define XkbGeomShapesMask (1<<2) +#define XkbGeomSectionsMask (1<<3) +#define XkbGeomDoodadsMask (1<<4) +#define XkbGeomAllMask (0x1f) + + + +If free_all is +True +, the entire geometry is freed regardless of the value of which. Otherwise, the +portions of the geometry specified by which are freed. + + + + -- cgit v1.2.3