4147 lines
100 KiB
XML
4147 lines
100 KiB
XML
<chapter id='keyboard_geometry'>
|
||
<title>Keyboard Geometry</title>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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<emphasis>
|
||
o</emphasis>
|
||
. 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.
|
||
</para>
|
||
|
||
<mediaobject>
|
||
<imageobject> <imagedata format="SVG" fileref="XKBlib-7.svg"/>
|
||
</imageobject>
|
||
<caption>Rotated Keyboard Sections</caption>
|
||
</mediaobject>
|
||
|
||
|
||
<!-- <H5 CLASS="Figure">
|
||
Rotated Keyboard Sections</H5>
|
||
-->
|
||
|
||
<para>
|
||
Some geometry components include a <emphasis>
|
||
priority</emphasis>
|
||
, which indicates the order in which overlapping objects should be drawn.
|
||
Objects should be drawn in order from highest priority (0) to lowest (255).
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The keyboard geometry’s top-level description is stored in a <emphasis>
|
||
XkbGeometryRec</emphasis>
|
||
structure. This structure contains three types of information:
|
||
</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
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)
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
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)
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A list of the keyboard’s sections and nonkey doodads
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<para>
|
||
The top-level geometry is described in more detail in the following.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The lists of items used by components of the keyboard geometry description is
|
||
as follows:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
The top-level keyboard geometry description includes a list of up to <emphasis>
|
||
MaxColors</emphasis>
|
||
(32) <emphasis>
|
||
color names</emphasis>
|
||
. A color name is a string whose interpretation is not specified by Xkb. The
|
||
<emphasis>
|
||
XkbColorRec</emphasis>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The top-level keyboard geometry description includes a list of <emphasis>
|
||
geometry properties</emphasis>
|
||
. 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
|
||
<emphasis>
|
||
properties</emphasis>
|
||
, 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:
|
||
</para>
|
||
<para>
|
||
LBL_PAUS = "{Pause/top/black,Break/front/red}"
|
||
</para>
|
||
<para>
|
||
and use the property information to draw the key with a front label as well as
|
||
a top label.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The top-level keyboard geometry description includes a list of <emphasis>
|
||
key aliases</emphasis>
|
||
(see Chapter 18). Key aliases allow the keyboard layout designer to assign
|
||
multiple key names to a single key.
|
||
</para>
|
||
<note><para>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 <emphasis>
|
||
XkbNamesRec</emphasis>
|
||
(<emphasis>
|
||
xkb->names</emphasis>
|
||
). Therefore, consider the key aliases defined by the geometry before
|
||
considering key aliases supplied by the keycodes.</para></note>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The top-level keyboard geometry description includes a list of <emphasis>
|
||
shapes</emphasis>
|
||
; 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
|
||
<emphasis>
|
||
outlines</emphasis>
|
||
. 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 <emphasis>
|
||
primary</emphasis>
|
||
field in the <emphasis>
|
||
XkbShapeRec</emphasis>
|
||
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 <emphasis>
|
||
approximation</emphasis>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
The <emphasis>
|
||
XkbGeometryRec</emphasis>
|
||
top-level geometry description contains the following information that
|
||
pertains to the keyboard as a whole:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
A <emphasis>
|
||
keyboard symbolic name</emphasis>
|
||
of type Atom to help users identify the keyboard.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The <emphasis>
|
||
width</emphasis>
|
||
and <emphasis>
|
||
height</emphasis>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The<emphasis>
|
||
base color</emphasis>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The <emphasis>
|
||
label color</emphasis>
|
||
is the color used to draw the labels on most of the keyboard keys.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The <emphasis>
|
||
label font</emphasis>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
The keyboard is subdivided into named <emphasis>
|
||
sections</emphasis>
|
||
of related keys and doodads. The sections and doodads on the keyboard are
|
||
listed in the <emphasis>
|
||
XkbGeometryRec</emphasis>
|
||
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 <emphasis>
|
||
doodad</emphasis>
|
||
describes some visible aspect of the keyboard that is not a key and is not a
|
||
section.
|
||
</para>
|
||
|
||
<mediaobject>
|
||
<imageobject> <imagedata format="SVG" fileref="XKBlib-8.svg"/>
|
||
</imageobject>
|
||
<caption>Keyboard with Four Sections</caption>
|
||
</mediaobject>
|
||
|
||
<!--
|
||
<H5 CLASS="Figure">
|
||
Keyboard with Four Sections</H5>
|
||
-->
|
||
|
||
<sect1 id='shapes_and_outlines'>
|
||
<title>Shapes and Outlines</title>
|
||
|
||
<para>
|
||
A <emphasis>
|
||
shape</emphasis>
|
||
, used to draw keyboard components and stored in a <emphasis>
|
||
XkbShapeRec</emphasis>
|
||
structure, has:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
An arbitrary name of type Atom.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Bounds (two x and y coordinates) that describe the corners of a rectangle
|
||
containing the shape’s top surface outline.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A list of one or more outlines (described below).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Optional pointers to a primary and an approximation outline (described below).
|
||
If either of these pointers is <emphasis>
|
||
NULL</emphasis>
|
||
, the default primary/approximation outline is the first one in the list of
|
||
outlines for the shape.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
An <emphasis>
|
||
outline</emphasis>
|
||
, stored in a <emphasis>
|
||
XkbOutlineRec</emphasis>
|
||
structure, is a list of one or more points that describes a single
|
||
closed-polygon, as follows:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A nonzero value for the <emphasis>
|
||
corner_radius</emphasis>
|
||
field specifies that the corners of the polygon should be drawn as circles
|
||
with the specified radius.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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 <emphasis>
|
||
primary</emphasis>
|
||
field of the <emphasis>
|
||
XkbShapeRec</emphasis>
|
||
structure is not <emphasis>
|
||
NULL</emphasis>
|
||
, it points to the primary outline. A rectangular <emphasis>
|
||
approximation</emphasis>
|
||
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.
|
||
</para>
|
||
|
||
</sect1>
|
||
<sect1 id='sections'>
|
||
<title>Sections</title>
|
||
|
||
<para>
|
||
As previously noted, a keyboard is subdivided into <emphasis>
|
||
sections</emphasis>
|
||
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 <emphasis>
|
||
XkbSectionRec</emphasis>
|
||
, include:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
An arbitrary name of type Atom.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A priority, to indicate drawing order. 0 is the highest priority, 255 the
|
||
lowest.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Origin of the section, relative to the origin of the keyboard.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The width and height and the angle of rotation.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A list of <emphasis>
|
||
rows</emphasis>
|
||
. 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.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<mediaobject>
|
||
<imageobject> <imagedata format="SVG" fileref="XKBlib-9.svg"/>
|
||
</imageobject>
|
||
<caption>Rows in a Section</caption>
|
||
</mediaobject>
|
||
|
||
|
||
|
||
<!--
|
||
<H5 CLASS="Figure">
|
||
Rows in a Section</H5>
|
||
-->
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
An optional list of <emphasis>
|
||
doodads</emphasis>
|
||
; 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.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
An optional <emphasis>
|
||
overlay</emphasis>
|
||
with a name of type Atom and a list of overlay rows (described below).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Bounds (two x and y coordinates) that describe the corners of a rectangle
|
||
containing the entire section.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</sect1>
|
||
<sect1 id='rows_and_keys'>
|
||
<title>Rows and Keys</title>
|
||
|
||
<para>
|
||
A row description (<emphasis>
|
||
XkbRowRec</emphasis>
|
||
) 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
A key description (<emphasis>
|
||
XkbKeyRec</emphasis>
|
||
) 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
|
||
<emphasis>
|
||
XkbGeometryRec</emphasis>
|
||
). 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.
|
||
</para>
|
||
|
||
|
||
</sect1>
|
||
<sect1 id='doodads'>
|
||
<title>Doodads</title>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Each doodad’s origin is stored in fields named <emphasis>
|
||
left</emphasis>
|
||
and <emphasis>
|
||
top</emphasis>
|
||
, 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 <emphasis>
|
||
type</emphasis>
|
||
field, which specifies the type of doodad.
|
||
</para>
|
||
|
||
<para>
|
||
Xkb supports five types of doodads:
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
An <emphasis>
|
||
indicator doodad</emphasis>
|
||
describes one of the physical keyboard indicators. Indicator doodads specify
|
||
the shape of the indicator, the indicator color when it is lit (<emphasis>
|
||
on_color</emphasis>
|
||
) and the indicator color when it is dark (<emphasis>
|
||
off_color</emphasis>
|
||
).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
An <emphasis>
|
||
outline doodad</emphasis>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A <emphasis>
|
||
solid doodad</emphasis>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A <emphasis>
|
||
text doodad</emphasis>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A <emphasis>
|
||
logo doodad </emphasis>
|
||
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.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
The structures these doodads are stored in and the values of the <emphasis>
|
||
type</emphasis>
|
||
fields are shown in Table 13.1.
|
||
</para>
|
||
|
||
<table frame='none'>
|
||
<title>Doodad Types</title>
|
||
<tgroup cols='3'>
|
||
<colspec colsep='0'/>
|
||
<thead>
|
||
<row rowsep='0'>
|
||
<entry>Doodad</entry>
|
||
<entry>Structure</entry>
|
||
<entry>Type</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry><emphasis>
|
||
indicator doodad</emphasis>
|
||
</entry>
|
||
<entry><emphasis>
|
||
XkbIndicatorDoodadRec</emphasis>
|
||
</entry>
|
||
<entry><emphasis>
|
||
XkbIndicatorDoodad</emphasis>
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry><emphasis>
|
||
outline doodad</emphasis>
|
||
</entry>
|
||
<entry><emphasis>
|
||
XkbShapeDoodadRec</emphasis>
|
||
</entry>
|
||
<entry><emphasis>
|
||
XkbOutlineDoodad</emphasis>
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry><emphasis>
|
||
solid doodad</emphasis>
|
||
</entry>
|
||
<entry><emphasis>
|
||
XkbShapeDoodadRec</emphasis>
|
||
</entry>
|
||
<entry><emphasis>
|
||
XkbSolidDoodad</emphasis>
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry><emphasis>
|
||
text doodad</emphasis>
|
||
</entry>
|
||
<entry><emphasis>
|
||
XkbTextDoodadRec</emphasis>
|
||
</entry>
|
||
<entry><emphasis>
|
||
XkbTextDoodad</emphasis>
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry><emphasis>
|
||
logo doodad</emphasis>
|
||
</entry>
|
||
<entry><emphasis>
|
||
XkbLogoDoodadRec</emphasis>
|
||
</entry>
|
||
<entry><emphasis>
|
||
XkbLogoDoodad</emphasis>
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
</sect1>
|
||
<sect1 id='overlay_rows_and_overlay_keys'>
|
||
<title>Overlay Rows and Overlay Keys</title>
|
||
|
||
<para>
|
||
An <emphasis>
|
||
overlay row</emphasis>
|
||
(<emphasis>
|
||
XkbOverlayRowRec</emphasis>
|
||
) contains a pointer to the row it overlays and a list of <emphasis>
|
||
overlay keys</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Each overlay key definition (<emphasis>
|
||
XkbOverlayKeyRec</emphasis>
|
||
) indicates a key that can yield multiple keycodes and consists of a field
|
||
named <emphasis>
|
||
under</emphasis>
|
||
, which specifies the primary name of the key and a field named <emphasis>
|
||
over</emphasis>
|
||
, which specifies the name for the key when the overlay keycode is selected.
|
||
The key specified in <emphasis>
|
||
under</emphasis>
|
||
must be a member of the section that contains the overlay key definition,
|
||
while the key specified in over must not be.
|
||
</para>
|
||
|
||
|
||
</sect1>
|
||
<sect1 id='drawing_a_keyboard_representation'>
|
||
<title>Drawing a Keyboard Representation</title>
|
||
|
||
<para>
|
||
To draw a representation of the keyboard, draw in the following order:
|
||
</para>
|
||
|
||
<para><programlisting>
|
||
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
|
||
</programlisting></para>
|
||
|
||
</sect1>
|
||
<sect1 id='geometry_data_structures'>
|
||
<title>Geometry Data Structures</title>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
<!--
|
||
<MAP NAME="XKBlib-10">
|
||
</MAP>
|
||
-->
|
||
<mediaobject>
|
||
<imageobject> <imagedata format="SVG" fileref="XKBlib-10.svg"/>
|
||
</imageobject>
|
||
<caption>Xkb Geometry Data Structures</caption>
|
||
</mediaobject>
|
||
|
||
<!--
|
||
<H5 CLASS="Figure">
|
||
Xkb Geometry Data Structures</H5>
|
||
<P CLASS="SmallBody">
|
||
</P>
|
||
<MAP NAME="XKBlib-11">
|
||
</MAP>
|
||
-->
|
||
<mediaobject>
|
||
<imageobject> <imagedata format="SVG" fileref="XKBlib-11.svg"/>
|
||
</imageobject>
|
||
<caption>Xkb Geometry Data Structures (Doodads)</caption>
|
||
</mediaobject>
|
||
|
||
<!--
|
||
<H5 CLASS="Figure">
|
||
Xkb Geometry Data Structures (Doodads)</H5>
|
||
-->
|
||
|
||
<!--
|
||
<MAP NAME="XKBlib-12">
|
||
</MAP>
|
||
-->
|
||
<mediaobject>
|
||
<imageobject> <imagedata format="SVG" fileref="XKBlib-12.svg"/>
|
||
</imageobject>
|
||
<caption>Xkb Geometry Data Structures (Overlays)</caption>
|
||
</mediaobject>
|
||
|
||
<!--
|
||
<H5 CLASS="Figure">
|
||
Xkb Geometry Data Structures (Overlays)</H5>
|
||
-->
|
||
<para><programlisting>
|
||
typedef struct _XkbGeometry { /* top-level keyboard geometry structure */
|
||
Atom name; /* keyboard name */
|
||
unsigned short width_mm; /* keyboard width in <emphasis> mm</emphasis> /<emphasis> 10</emphasis> */
|
||
unsigned short height_mm; /* keyboard height in <emphasis> mm</emphasis> /<emphasis> 10</emphasis> */
|
||
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 */
|
||
} <emphasis>XkbGeometryRec</emphasis>*XkbGeometryPtr;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
The <emphasis>
|
||
doodads</emphasis>
|
||
array is only for doodads not contained in any of the <emphasis>
|
||
sections</emphasis>
|
||
that has its own <emphasis>
|
||
doodads</emphasis>
|
||
. The key aliases contained in the <emphasis>
|
||
key_aliases</emphasis>
|
||
array take precedence over any defined in the keycodes component of the
|
||
keyboard description.
|
||
</para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbProperty {
|
||
char * name; /* property name */
|
||
char * value; /* property value */
|
||
} <emphasis>XkbPropertyRec</emphasis>,*XkbPropertyPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbColor {
|
||
unsigned int pixel; /* color */
|
||
char * spec; /* color name */
|
||
} <emphasis>XkbColorRec</emphasis>,*XkbColorPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbKeyAliasRec {
|
||
char real[XkbKeyNameLength]; /* real name of the key */
|
||
char alias[XkbKeyNameLength]; /* alias for the key */
|
||
} <emphasis>XkbKeyAliasRec</emphasis>,*XkbKeyAliasPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbPoint { /* x,y coordinates */
|
||
short x;
|
||
short y;
|
||
} <emphasis>XkbPointRec</emphasis>, *XkbPointPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
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 */
|
||
} <emphasis>XkbOutlineRec</emphasis>, *XkbOutlinePtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbBounds {
|
||
short x1,y1; /* upper left corner of the bounds,
|
||
in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
short x2,y2; /* lower right corner of the bounds, in
|
||
<emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
} <emphasis>XkbBoundsRec</emphasis>, *XkbBoundsPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
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 */
|
||
} <emphasis>XkbShapeRec</emphasis>, *XkbShapePtr;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
If <emphasis>
|
||
approx</emphasis>
|
||
and/or <emphasis>
|
||
primary</emphasis>
|
||
is <emphasis>
|
||
NULL</emphasis>
|
||
, the default value is used. The default primary outline is the first element
|
||
in the outlines array, as is the default approximating outline.
|
||
</para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbKey { /* key in a row */
|
||
XkbKeyNameRec name; /* key name */
|
||
short gap; /* gap in <emphasis>mm</emphasis>/<emphasis>10</emphasis> from previous key in row */
|
||
unsigned char shape_ndx; /* index of shape for key */
|
||
unsigned char color_ndx; /* index of color for key body */
|
||
} <emphasis>XkbKeyRec</emphasis>, *XkbKeyPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
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; /* <emphasis>True</emphasis> =>vertical row,
|
||
<emphasis> False</emphasis> =>horizontal row */
|
||
XkbKeyPtr keys; /* array of keys in the row*/
|
||
XkbBoundsRec bounds; /* bounding box for the row */
|
||
} <emphasis>XkbRowRec</emphasis>, *XkbRowPtr;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
<emphasis>
|
||
top</emphasis>
|
||
and <emphasis>
|
||
left</emphasis>
|
||
are in <emphasis>
|
||
mm</emphasis>
|
||
/<emphasis>
|
||
10</emphasis>
|
||
.
|
||
</para>
|
||
|
||
<para><programlisting>
|
||
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 */
|
||
} <emphasis>XkbOverlayRec</emphasis>,*XkbOverlayPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
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 */
|
||
} <emphasis>XkbOverlayRowRec</emphasis>,*XkbOverlayRowPtr;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
<emphasis>
|
||
row_under</emphasis>
|
||
is an index into the array of <emphasis>
|
||
rows</emphasis>
|
||
in the section under this overlay. The section under this overlay row is the
|
||
one pointed to by <emphasis>
|
||
section_under</emphasis>
|
||
in this overlay row’s <emphasis>
|
||
XkbOverlayRec</emphasis>
|
||
.
|
||
</para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbOverlayKey {
|
||
XkbKeyNameRec over; /* name of this overlay key */
|
||
XkbKeyNameRec under; /* name of the key under this overlay key */
|
||
} <emphasis>XkbOverlayKeyRec</emphasis>,*XkbOverlayKeyPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
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 <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
unsigned short height; /* section height, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
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 */
|
||
} <emphasis>XkbSectionRec</emphasis>, *XkbSectionPtr;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
<emphasis>
|
||
top</emphasis>
|
||
and <emphasis>
|
||
left</emphasis>
|
||
are the origin of the section, relative to the origin of the keyboard, in
|
||
<emphasis>
|
||
mm</emphasis>
|
||
/<emphasis>
|
||
10</emphasis>
|
||
. <emphasis>
|
||
angle</emphasis>
|
||
is in <emphasis>
|
||
1</emphasis>
|
||
/<emphasis>
|
||
10</emphasis>
|
||
degrees.
|
||
</para>
|
||
|
||
<sect2 id='doodadrec_structures'>
|
||
<title>DoodadRec Structures</title>
|
||
|
||
<para>
|
||
The doodad arrays in the <emphasis>
|
||
XkbGeometryRec</emphasis>
|
||
and the <emphasis>
|
||
XkbSectionRec</emphasis>
|
||
may contain any of the doodad structures and types shown in Table 13.1.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The doodad structures form a union:
|
||
</para>
|
||
|
||
<para><programlisting>
|
||
typedef union _XkbDoodad {
|
||
XkbAnyDoodadRec any;
|
||
XkbShapeDoodadRec shape;
|
||
XkbTextDoodadRec text;
|
||
XkbIndicatorDoodadRec indicator;
|
||
XkbLogoDoodadRec logo;
|
||
} <emphasis>XkbDoodadRec</emphasis>, *XkbDoodadPtr;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
The <emphasis>
|
||
top</emphasis>
|
||
and <emphasis>
|
||
left</emphasis>
|
||
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 <emphasis>
|
||
XkbGeometryRec</emphasis>
|
||
doodad array, and with respect to the section’s origin if the doodad is in a
|
||
<emphasis>
|
||
XkbSectionRec</emphasis>
|
||
doodad array. The <emphasis>
|
||
color_ndx</emphasis>
|
||
or <emphasis>
|
||
on_color_ndx</emphasis>
|
||
and <emphasis>
|
||
off_color_ndx</emphasis>
|
||
fields are color indices into the <emphasis>
|
||
XkbGeometryRec</emphasis>
|
||
’s color array and are the colors to draw the doodads with. Similarly, the
|
||
<emphasis>
|
||
shape_ndx</emphasis>
|
||
fields are indices into the <emphasis>
|
||
XkbGeometryRec</emphasis>
|
||
’s shape array.
|
||
</para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbShapeDoodad {
|
||
Atom name; /* doodad name */
|
||
unsigned char type; /* <emphasis>XkbOutlineDoodad</emphasis>
|
||
or <emphasis>XkbSolidDoodad</emphasis> */
|
||
unsigned char priority; /* drawing priority,
|
||
0=>highest, 255=>lowest */
|
||
short top; /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
short left; /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
short angle; /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */
|
||
unsigned short color_ndx; /* doodad color */
|
||
unsigned short shape_ndx; /* doodad shape */
|
||
} <emphasis>XkbShapeDoodadRec</emphasis>, *XkbShapeDoodadPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbTextDoodad {
|
||
Atom name; /* doodad name */
|
||
unsigned char type; /* <emphasis> XkbTextDoodad</emphasis> */
|
||
unsigned char priority; /* drawing priority,
|
||
0=>highest, 255=>lowest */
|
||
short top; /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
short left; /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
short angle; /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */
|
||
short width; /* width in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
short height; /* height in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
unsigned short color_ndx; /* doodad color */
|
||
char * text; /* doodad text */
|
||
char * font; /* arbitrary font name for doodad text */
|
||
} <emphasis>XkbTextDoodadRec</emphasis>, *XkbTextDoodadPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbIndicatorDoodad {
|
||
Atom name; /* doodad name */
|
||
unsigned char type; /* <emphasis>XkbIndicatorDoodad</emphasis> */
|
||
unsigned char priority; /* drawing priority, 0=>highest, 255=>lowest */
|
||
short top; /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
short left; /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
short angle; /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> 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 */
|
||
} <emphasis>XkbIndicatorDoodadRec</emphasis>, *XkbIndicatorDoodadPtr;
|
||
</programlisting></para>
|
||
|
||
<para><programlisting>
|
||
typedef struct _XkbLogoDoodad {
|
||
Atom name; /* doodad name */
|
||
unsigned char type; /* <emphasis> XkbLogoDoodad</emphasis> */
|
||
unsigned char priority; /* drawing priority, 0=>highest, 255=>lowest */
|
||
short top; /* top coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
short left; /* left coordinate, in <emphasis>mm</emphasis>/<emphasis>10</emphasis> */
|
||
short angle; /* angle of rotation, clockwise, in <emphasis>1</emphasis>/<emphasis>10</emphasis> degrees */
|
||
unsigned short color_ndx; /* doodad color */
|
||
unsigned short shape_ndx; /* doodad shape */
|
||
char * logo_name; /* text for logo */
|
||
} <emphasis>XkbLogoDoodadRec</emphasis>, *XkbLogoDoodadPtr
|
||
</programlisting></para>
|
||
|
||
</sect2>
|
||
</sect1>
|
||
<sect1 id='getting_keyboard_geometry_from_the_server'>
|
||
<title>Getting Keyboard Geometry From the Server</title>
|
||
|
||
<para>
|
||
You can load a keyboard geometry as part of the keyboard description returned
|
||
by <emphasis>
|
||
XkbGetKeyboard</emphasis>
|
||
. However, if a keyboard description has been previously loaded, you can
|
||
instead obtain the geometry by calling the <emphasis>
|
||
XkbGetGeometry</emphasis>
|
||
. In this case, the geometry returned is the one associated with the keyboard
|
||
whose device ID is contained in the keyboard description.
|
||
</para>
|
||
|
||
<para>
|
||
To load a keyboard geometry if you already have the keyboard description, use
|
||
<emphasis>XkbGetGeometry</emphasis>.
|
||
</para>
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbGetGeometry</emphasis>
|
||
(<emphasis>
|
||
dpy</emphasis>
|
||
,<emphasis>
|
||
xkb</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Display * <emphasis>
|
||
dpy</emphasis>
|
||
; /* connection to the X server */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbDescPtr <emphasis>
|
||
xkb</emphasis>
|
||
; /* keyboard description that contains the ID for the keyboard and into
|
||
which the geometry should be loaded */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbGetGeometry</emphasis>
|
||
can return <emphasis>
|
||
BadValue</emphasis>
|
||
, <emphasis>
|
||
BadImplementation</emphasis>
|
||
, <emphasis>
|
||
BadName</emphasis>
|
||
, <emphasis>
|
||
BadAlloc,</emphasis>
|
||
or <emphasis>
|
||
BadLength</emphasis>
|
||
errors or <emphasis>
|
||
Success</emphasis>
|
||
if it succeeds.
|
||
</para>
|
||
|
||
<para>
|
||
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 <emphasis>
|
||
XkbGetNamedGeometry</emphasis>.
|
||
</para>
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbGetNamedGeometry</emphasis>
|
||
(<emphasis>
|
||
dpy</emphasis>
|
||
,<emphasis>
|
||
xkb</emphasis>
|
||
,<emphasis>
|
||
name</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Display * <emphasis>
|
||
dpy</emphasis>
|
||
; /* connection to the X server */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbDescPtr <emphasis>
|
||
xkb</emphasis>
|
||
; /* keyboard description into which the geometry should be loaded */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Atom <emphasis>
|
||
name</emphasis>
|
||
; /* name of the geometry to be loaded */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbGetNamedGeometry</emphasis>
|
||
can return <emphasis>
|
||
BadName</emphasis>
|
||
if the <emphasis>
|
||
name</emphasis>
|
||
cannot be found.
|
||
</para>
|
||
|
||
</sect1>
|
||
<sect1 id='using_keyboard_geometry'>
|
||
<title>Using Keyboard Geometry</title>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
<mediaobject>
|
||
<imageobject> <imagedata format="SVG" fileref="XKBlib-13.svg"/>
|
||
</imageobject>
|
||
<caption>Key Surface, Shape Outlines, and Bounding Box</caption>
|
||
</mediaobject>
|
||
|
||
|
||
<!--
|
||
<H5 CLASS="Figure">
|
||
Key Surface, Shape Outlines, and Bounding Box</H5>
|
||
-->
|
||
|
||
<para>
|
||
To determine the bounding box of the top surface of a shape, use <emphasis>
|
||
XkbComputeShapeTop</emphasis>.
|
||
</para>
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Bool <emphasis>
|
||
XkbComputeShapeTop</emphasis>
|
||
(<emphasis>
|
||
shape</emphasis>
|
||
,<emphasis>
|
||
bounds_rtrn</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbShapePtr <emphasis>
|
||
shape</emphasis>
|
||
; /* shape to be examined */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbBoundsPtr <emphasis>
|
||
bounds_rtrn</emphasis>
|
||
/* backfilled with the bounding box for the shape */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbComputeShapeTop</emphasis>
|
||
returns a <emphasis>
|
||
BoundsRec</emphasis>
|
||
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
|
||
<emphasis>
|
||
approx</emphasis>
|
||
field of <emphasis>
|
||
shape</emphasis>
|
||
is not <emphasis>
|
||
NULL</emphasis>
|
||
. If <emphasis>
|
||
approx</emphasis>
|
||
is <emphasis>
|
||
NULL</emphasis>
|
||
, the top surface is defined as the last outline in the <emphasis>
|
||
shape</emphasis>
|
||
’s array of outlines. <emphasis>
|
||
XkbComputeShapeTop</emphasis>
|
||
returns <emphasis>
|
||
False</emphasis>
|
||
if <emphasis>
|
||
shape</emphasis>
|
||
is <emphasis>
|
||
NULL</emphasis>
|
||
or if there are no outlines for the shape; otherwise, it returns
|
||
<emphasis>True</emphasis>.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
A <emphasis>
|
||
ShapeRec</emphasis>
|
||
contains a <emphasis>
|
||
BoundsRec</emphasis>
|
||
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 <emphasis>XkbComputeShapeBounds</emphasis>.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Bool <emphasis>
|
||
XkbComputeShapeBounds</emphasis>
|
||
(<emphasis>
|
||
shape</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbShapePtr <emphasis>
|
||
shape</emphasis>
|
||
; /* shape to be examined */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbComputeShapeBounds</emphasis>
|
||
updates the <emphasis>
|
||
BoundsRec</emphasis>
|
||
contained in the <emphasis>
|
||
shape</emphasis>
|
||
by examining all the outlines of the shape and setting the <emphasis>
|
||
BoundsRec</emphasis>
|
||
to the minimum x and minimum y, and maximum x and maximum y values found in
|
||
those outlines. <emphasis>
|
||
XkbComputeShapeBounds</emphasis>
|
||
returns <emphasis>
|
||
False</emphasis>
|
||
if <emphasis>
|
||
shape</emphasis>
|
||
is <emphasis>
|
||
NULL</emphasis>
|
||
or if there are no outlines for the shape; otherwise, it returns <emphasis>
|
||
True</emphasis>
|
||
.
|
||
</para>
|
||
|
||
<para>
|
||
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 <emphasis>XkbComputeRowBounds</emphasis>.
|
||
</para>
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Bool <emphasis>
|
||
XkbComputeRowBounds</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
section</emphasis>
|
||
,<emphasis>
|
||
row</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry that contains the <emphasis>
|
||
section</emphasis>
|
||
*/
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section that contains the row */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbRowPtr <emphasis>
|
||
row</emphasis>
|
||
; /* row to be examined and updated */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbComputeRowBounds</emphasis>
|
||
checks the bounds of all keys in the <emphasis>
|
||
row </emphasis>
|
||
and updates the bounding box of the row if necessary. <emphasis>
|
||
XkbComputeRowBounds</emphasis>
|
||
returns <emphasis>
|
||
False</emphasis>
|
||
if any of the arguments is <emphasis>
|
||
NULL</emphasis>
|
||
; otherwise, it returns <emphasis>
|
||
True</emphasis>
|
||
.
|
||
</para>
|
||
|
||
<para>
|
||
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
|
||
<emphasis>XkbComputeSectionBounds</emphasis>.
|
||
</para>
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Bool <emphasis>
|
||
XkbComputeSectionBounds</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
section</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry that contains the <emphasis>
|
||
section</emphasis>
|
||
*/
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section to be examined and updated */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbComputeSectionBounds</emphasis>
|
||
examines all the rows of the <emphasis>
|
||
section</emphasis>
|
||
and updates the bounding box of that section so that it contains all rows.
|
||
<emphasis>
|
||
XkbComputeSectionBounds</emphasis>
|
||
returns <emphasis>
|
||
False</emphasis>
|
||
if any of the arguments is <emphasis>
|
||
NULL</emphasis>
|
||
; otherwise, it returns <emphasis>
|
||
True</emphasis>
|
||
.
|
||
</para>
|
||
|
||
<para>
|
||
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 <emphasis>
|
||
XkbFindOverlayForKey</emphasis>.
|
||
</para>
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
char * <emphasis>
|
||
XkbFindOverlayForKey</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
section</emphasis>
|
||
,<emphasis>
|
||
under</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry that contains the <emphasis>
|
||
section</emphasis>
|
||
*/
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section to be searched for matching keys */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
char * <emphasis>
|
||
under</emphasis>
|
||
. /* primary name of the key to be considered */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbFindOverlayForKey</emphasis>
|
||
uses the primary name of the key, <emphasis>
|
||
under</emphasis>
|
||
, to look up the alternate name, which it returns.
|
||
</para>
|
||
|
||
|
||
</sect1>
|
||
<sect1 id='adding_elements_to_a_keyboard_geometry'>
|
||
<title>Adding Elements to a Keyboard Geometry</title>
|
||
|
||
<para>
|
||
Xkb provides functions to add a single new element to the top-level keyboard
|
||
geometry. In each case the <emphasis>
|
||
num_ </emphasis>
|
||
<emphasis>
|
||
*</emphasis>
|
||
fields of the corresponding structure is incremented by 1. These functions do
|
||
not change <emphasis>
|
||
sz_</emphasis>
|
||
<emphasis>
|
||
*</emphasis>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The top-level geometry description includes a list of <emphasis>
|
||
geometry properties</emphasis>
|
||
. 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add one property to an existing keyboard geometry description, use <emphasis>
|
||
XkbAddGeomProperty</emphasis>
|
||
.
|
||
</para>
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbPropertyPtr <emphasis>
|
||
XkbAddGeomProperty</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
name</emphasis>
|
||
,<emphasis>
|
||
value</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry to be updated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
char * <emphasis>
|
||
name</emphasis>
|
||
; /* name of the new property */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
char * <emphasis>
|
||
value</emphasis>
|
||
; /* value for the new property */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAddGeomProperty</emphasis>
|
||
adds one property with the specified <emphasis>
|
||
name</emphasis>
|
||
and <emphasis>
|
||
value</emphasis>
|
||
to the keyboard geometry specified by geom.<emphasis>
|
||
</emphasis>
|
||
<emphasis>
|
||
XkbAddGeomProperty</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add one key alias to an existing keyboard geometry description, use
|
||
<emphasis>
|
||
XkbAddGeomKeyAlias</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbKeyAliasPtr <emphasis>
|
||
XkbAddGeomKeyAlias</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
alias, real</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry to be updated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
char * <emphasis>
|
||
alias</emphasis>
|
||
; /* alias to be added */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
char * <emphasis>
|
||
real</emphasis>
|
||
; /* real name to be bound to the new alias */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAddGeomKeyAlias</emphasis>
|
||
adds one key alias with the value alias to the geometry geom, and associates
|
||
it with the key whose real name is real. <emphasis>
|
||
XkbAddGeomKeyAlias</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add one color name to an existing keyboard geometry description, use
|
||
<emphasis>
|
||
XkbAddGeomColor</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbColorPtr <emphasis>
|
||
XkbAddGeomColor</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
spec</emphasis>
|
||
,<emphasis>
|
||
pixel</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry to be updated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
char * <emphasis>
|
||
spec</emphasis>
|
||
; /* color to be added */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
unsigned int <emphasis>
|
||
pixel</emphasis>
|
||
; /* color to be added */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAddGeomColor</emphasis>
|
||
adds the specified color <emphasis>
|
||
name</emphasis>
|
||
and <emphasis>
|
||
pixel</emphasis>
|
||
to the specified geometry <emphasis>
|
||
geom</emphasis>
|
||
. The top-level geometry description includes a list of up to <emphasis>
|
||
MaxColors</emphasis>
|
||
(32) <emphasis>
|
||
color names</emphasis>
|
||
. A color <emphasis>
|
||
name</emphasis>
|
||
is a string whose interpretation is not specified by Xkb and neither is the
|
||
<emphasis>
|
||
pixel</emphasis>
|
||
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.
|
||
<emphasis>
|
||
XkbAddGeomColor</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
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 <emphasis>
|
||
XkbAllocGeomColors</emphasis>
|
||
function.
|
||
</para>
|
||
|
||
<para>
|
||
To add one outline to an existing shape, use <emphasis>
|
||
XkbAddGeomOutline</emphasis>.
|
||
</para>
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbOutlinePtr <emphasis>
|
||
XkbAddGeomOutline</emphasis>
|
||
(<emphasis>
|
||
shape</emphasis>
|
||
,<emphasis>
|
||
sz_points</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbShapePtr <emphasis>
|
||
shape</emphasis>
|
||
; /* shape to be updated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
sz_points</emphasis>
|
||
; /* number of points to be reserved */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
An outline consists of an arbitrary number of points. <emphasis>
|
||
XkbAddGeomOutline</emphasis>
|
||
adds an outline to the specified <emphasis>
|
||
shape</emphasis>
|
||
by reserving <emphasis>
|
||
sz_points</emphasis>
|
||
points for it. The new outline is allocated and zeroed. <emphasis>
|
||
XkbAddGeomOutline</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add a shape to a keyboard geometry, use <emphasis>
|
||
XkbAddGeomShape</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbShapePtr <emphasis>
|
||
XkbAddGeomShape</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
name</emphasis>
|
||
,<emphasis>
|
||
sz_outlines</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry to be updated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Atom <emphasis>
|
||
name</emphasis>
|
||
; /* name of the new shape */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
sz_outlines</emphasis>
|
||
; /* number of outlines to be reserved */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
A geometry contains an arbitrary number of shapes, each of which is made up of
|
||
an arbitrary number of outlines. <emphasis>
|
||
XkbAddGeomShape</emphasis>
|
||
adds a shape to a geometry <emphasis>
|
||
geom</emphasis>
|
||
by allocating space for <emphasis>
|
||
sz_outlines</emphasis>
|
||
outlines for it and giving it the name specified by name. If a shape with name
|
||
<emphasis>
|
||
name</emphasis>
|
||
already exists in the geometry, a pointer to the existing shape is returned.
|
||
<emphasis>
|
||
XkbAddGeomShape</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
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 <emphasis>
|
||
XkbAllocGeomShapes</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add one key at the end of an existing row of keys, use <emphasis>
|
||
XkbAddGeomKey</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbKeyPtr <emphasis>
|
||
XkbAddGeomKey</emphasis>
|
||
(<emphasis>
|
||
row</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbRowPtr <emphasis>
|
||
row</emphasis>
|
||
; /* row to be updated */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
Keys are grouped into rows. <emphasis>
|
||
XkbAddGeomKey</emphasis>
|
||
adds one key to the end of the specified <emphasis>
|
||
row</emphasis>
|
||
. The key is allocated and zeroed. <emphasis>
|
||
XkbAddGeomKey</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
if <emphasis>
|
||
row</emphasis>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add one section to an existing keyboard geometry, use <emphasis>
|
||
XkbAddGeomSection</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbSectionPtr <emphasis>
|
||
XkbAddGeomSection</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
name</emphasis>
|
||
,<emphasis>
|
||
sz_rows</emphasis>
|
||
,<emphasis>
|
||
sz_doodads</emphasis>
|
||
,<emphasis>
|
||
sz_overlays</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry to be updated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Atom <emphasis>
|
||
name</emphasis>
|
||
; /* name of the new section */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
sz_rows</emphasis>
|
||
; /* number of rows to reserve in the section */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
sz_doodads</emphasis>
|
||
; /* number of doodads to reserve in the section */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
sz_overlays</emphasis>
|
||
; /* number of overlays to reserve in the section */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
A keyboard geometry contains an arbitrary number of sections. <emphasis>
|
||
XkbAddGeomSection</emphasis>
|
||
adds one section to an existing keyboard geometry <emphasis>
|
||
geom</emphasis>
|
||
. The new section contains space for the number of rows, doodads, and overlays
|
||
specified by <emphasis>
|
||
sz_rows</emphasis>
|
||
, <emphasis>
|
||
sz_doodads</emphasis>
|
||
, and <emphasis>
|
||
sz_overlays</emphasis>
|
||
. The new section is allocated and zeroed and given the name specified by
|
||
<emphasis>
|
||
name</emphasis>
|
||
. If a section with name <emphasis>
|
||
name</emphasis>
|
||
already exists in the geometry, a pointer to the existing section is
|
||
returned.<emphasis>
|
||
XkbAddGeomSection</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add a row to a section, use <emphasis>
|
||
XkbAddGeomRow</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbRowPtr <emphasis>
|
||
XkbAddGeomRow</emphasis>
|
||
(<emphasis>
|
||
section</emphasis>
|
||
,<emphasis>
|
||
sz_keys</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section to be updated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
sz_keys</emphasis>
|
||
; /* number of keys to be reserved */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
One of the components of a keyboard geometry section is one or more rows of
|
||
keys. <emphasis>
|
||
XkbAddGeomRow</emphasis>
|
||
adds one row to the specified <emphasis>
|
||
section</emphasis>
|
||
. The newly created row contains space for the number of keys specified in
|
||
<emphasis>
|
||
sz_keys</emphasis>
|
||
. They are allocated and zeroed, but otherwise uninitialized. <emphasis>
|
||
XkbAddGeomRow</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add one doodad to a section of a keyboard geometry or to the top-level
|
||
geometry, use <emphasis>
|
||
XkbAddGeomDoodad</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbDoodadPtr <emphasis>
|
||
XkbAddGeomDoodad</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
section</emphasis>
|
||
,<emphasis>
|
||
name</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry to which the doodad is added */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section, if any, to which the doodad is added */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Atom <emphasis>
|
||
name</emphasis>
|
||
; /* name of the new doodad */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
A <emphasis>
|
||
doodad</emphasis>
|
||
describes some visible aspect of the keyboard that is not a key and is not a
|
||
section. <emphasis>
|
||
XkbAddGeomDoodad</emphasis>
|
||
adds a doodad with name specified by name to the geometry <emphasis>
|
||
geom</emphasis>
|
||
if section is <emphasis>
|
||
NULL</emphasis>
|
||
or to the section of the geometry specified by section if <emphasis>
|
||
section</emphasis>
|
||
is not <emphasis>
|
||
NULL</emphasis>
|
||
. <emphasis>
|
||
XkbAddGeomDoodad</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
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 <emphasis>
|
||
name</emphasis>
|
||
in the doodad array for the geometry (if <emphasis>
|
||
section</emphasis>
|
||
is <emphasis>
|
||
NULL</emphasis>
|
||
) or the section (if <emphasis>
|
||
section</emphasis>
|
||
is non-<emphasis>
|
||
NULL</emphasis>
|
||
), 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add one overlay to a section, use <emphasis>
|
||
XkbAddGeomOverlay</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbOverlayPtr <emphasis>
|
||
XkbAddGeomOverlay</emphasis>
|
||
(<emphasis>
|
||
section</emphasis>
|
||
,<emphasis>
|
||
name</emphasis>
|
||
,<emphasis>
|
||
sz_rows</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section to which an overlay will be added */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Atom <emphasis>
|
||
name</emphasis>
|
||
; /* name of the overlay */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
sz_rows</emphasis>
|
||
; /* number of rows to reserve in the overlay */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAddGeomOverlay</emphasis>
|
||
adds an overlay with the specified name to the specified <emphasis>
|
||
section</emphasis>
|
||
. The new overlay is created with space allocated for sz_rows rows. If an
|
||
overlay with name <emphasis>
|
||
name</emphasis>
|
||
already exists in the section, a pointer to the existing overlay is
|
||
returned.<emphasis>
|
||
XkbAddGeomOverlay</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add a row to an existing overlay, use <emphasis>
|
||
XkbAddGeomOverlayRow</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbOverlayRowPtr <emphasis>
|
||
XkbAddGeomOverlayRow</emphasis>
|
||
(<emphasis>
|
||
overlay</emphasis>
|
||
,<emphasis>
|
||
row_under, sz_keys</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbOverlayPtr <emphasis>
|
||
overlay</emphasis>
|
||
; /* overlay to be updated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbRowPtr <emphasis>
|
||
row_under</emphasis>
|
||
; /* row to be overlayed in the section <emphasis>
|
||
overlay</emphasis>
|
||
overlays */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
sz_keys</emphasis>
|
||
; /* number of keys to reserve in the row */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAddGeomOverlayRow</emphasis>
|
||
adds one row to the <emphasis>
|
||
overlay</emphasis>
|
||
. The new row contains space for <emphasis>
|
||
sz_keys</emphasis>
|
||
keys. If <emphasis>
|
||
row_under</emphasis>
|
||
specifies a row that doesn’t exist on the underlying section, <emphasis>
|
||
XkbAddGeomOverlayRow</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
and doesn’t change the overlay.<emphasis>
|
||
XkbAddGeomOverlayRow</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
if any of the parameters is empty or if it was not able to allocate space for
|
||
the overlay.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To add a key to an existing overlay row, use <emphasis>
|
||
XkbAddGeomOverlayKey</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
XkbOverlayKeyPtr <emphasis>
|
||
XkbAddGeomOverlayKey</emphasis>
|
||
(<emphasis>
|
||
overlay</emphasis>
|
||
,<emphasis>
|
||
row, under</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbOverlayPtr <emphasis>
|
||
overlay</emphasis>
|
||
; /* overlay to be updated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbRowPtr <emphasis>
|
||
row</emphasis>
|
||
; /* row in overlay to be updated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
char * <emphasis>
|
||
under</emphasis>
|
||
; /* primary name of the key to be considered */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAddGeomOverlayKey</emphasis>
|
||
adds one key to the <emphasis>
|
||
row</emphasis>
|
||
in the <emphasis>
|
||
overlay</emphasis>
|
||
. If there is no key named <emphasis>
|
||
under</emphasis>
|
||
in the row of the underlying section, <emphasis>
|
||
XkbAddGeomOverlayKey</emphasis>
|
||
returns <emphasis>
|
||
NULL</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
</sect1>
|
||
<sect1 id='allocating_and_freeing_geometry_components'>
|
||
<title>Allocating and Freeing Geometry Components</title>
|
||
|
||
<para>
|
||
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 <emphasis>
|
||
sz_</emphasis>
|
||
<emphasis>
|
||
*</emphasis>
|
||
but never touch <emphasis>
|
||
num_</emphasis>
|
||
<emphasis>
|
||
*</emphasis>
|
||
(unless there is an allocation failure, in which case they reset both
|
||
<emphasis>
|
||
sz_</emphasis>
|
||
<emphasis>
|
||
*</emphasis>
|
||
and <emphasis>
|
||
num_</emphasis>
|
||
<emphasis>
|
||
*</emphasis>
|
||
to zero). These functions return <emphasis>
|
||
Success</emphasis>
|
||
if they succeed, <emphasis>
|
||
BadAlloc</emphasis>
|
||
if they are not able to allocate space, or <emphasis>
|
||
BadValue</emphasis>
|
||
if a parameter is not as expected.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate space for an arbitrary number of outlines to a shape, use
|
||
XkbAllocGeomOutlines.
|
||
</para>
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomOutlines</emphasis>
|
||
(<emphasis>
|
||
shape</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbShapePtr <emphasis>
|
||
shape</emphasis>
|
||
; /* shape for which outlines should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new outlines required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomOutlines</emphasis>
|
||
allocates space for <emphasis>
|
||
num_needed</emphasis>
|
||
outlines in the specified <emphasis>
|
||
shape</emphasis>
|
||
. The outlines are not initialized.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free geometry outlines, use <emphasis>
|
||
XkbFreeGeomOutlines</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomOutlines</emphasis>
|
||
(<emphasis>
|
||
shape</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbShapePtr <emphasis>
|
||
shape</emphasis>
|
||
; /* shape in which outlines should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first outline to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of outlines to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all outlines are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, all outlines are freed regardless of the value of first or count. Otherwise,
|
||
count outlines are freed beginning with the one specified by first.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate space for an arbitrary number of keys to a row, use
|
||
XkbAllocGeomKeys.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomKeys</emphasis>
|
||
(<emphasis>
|
||
row</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbRowPtr <emphasis>
|
||
row</emphasis>
|
||
; /* row to which keys should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new keys required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomKeys</emphasis>
|
||
allocates num_needed keys and adds them to the row. No initialization of the
|
||
keys is done.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free geometry keys, use <emphasis>
|
||
XkbFreeGeomKeys</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomKeys</emphasis>
|
||
(<emphasis>
|
||
row</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbRowPtr <emphasis>
|
||
row</emphasis>
|
||
; /* row in which keys should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first key to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of keys to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all keys are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, all keys are freed regardless of the value of first or count. Otherwise,
|
||
count keys are freed beginning with the one specified by first.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate geometry properties, use <emphasis>
|
||
XkbAllocGeomProps</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomProps</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry for which properties should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new properties required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomProps</emphasis>
|
||
allocates space for num_needed properties and adds them to the specified
|
||
geometry <emphasis>
|
||
geom</emphasis>
|
||
. 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free geometry properties, use <emphasis>
|
||
XkbFreeGeomProperties</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomProperties</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry in which properties should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first property to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of properties to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all properties are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, all properties are freed regardless of the value of first or count.
|
||
Otherwise, count properties are freed beginning with the one specified by first.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate geometry key aliases, use <emphasis>
|
||
XkbAllocGeomKeyAliases</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomKeyAliases</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry for which key aliases should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new key aliases required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomKeyAliases</emphasis>
|
||
allocates space for num_needed key aliases and adds them to the specified
|
||
geometry <emphasis>
|
||
geom</emphasis>
|
||
. A key alias is a pair of strings that associates an alternate name for a key
|
||
with the real name for that key.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free geometry key aliases, use <emphasis>
|
||
XkbFreeGeomKeyAliases</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomKeyAliases</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
, <emphasis>
|
||
count</emphasis>
|
||
, <emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry in which key aliases should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first key alias to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of key aliases to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all key aliases are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, all aliases in the top level of the specified geometry <emphasis>
|
||
geom</emphasis>
|
||
are freed regardless of the value of first or count. Otherwise, count aliases
|
||
in <emphasis>
|
||
geom</emphasis>
|
||
are freed beginning with the one specified by first.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate geometry colors, use <emphasis>
|
||
XkbAllocGeomColors</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomColors</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry for which colors should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new colors required. */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomColors</emphasis>
|
||
allocates space for num_needed colors and adds them to the specified geometry
|
||
<emphasis>
|
||
geom</emphasis>
|
||
. 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free geometry colors, use <emphasis>
|
||
XkbFreeGeomColors</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomColors</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry in which colors should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first color to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of colors to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all colors are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, all colors are freed regardless of the value of first or count. Otherwise,
|
||
count colors are freed beginning with the one specified by first.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate points in an outline, use <emphasis>
|
||
XkbAllocGeomPoints</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomPoints</emphasis>
|
||
(<emphasis>
|
||
outline</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbOutlinePtr <emphasis>
|
||
outline</emphasis>
|
||
; /* outline for which points should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new points required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomPoints</emphasis>
|
||
allocates space for <emphasis>
|
||
num_needed</emphasis>
|
||
points in the specified <emphasis>
|
||
outline</emphasis>
|
||
. The points are not initialized.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free points in a outline, use <emphasis>
|
||
XkbFreeGeomPoints</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomPoints</emphasis>
|
||
(<emphasis>
|
||
outline</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbOutlinePtr <emphasis>
|
||
outline</emphasis>
|
||
; /* outline in which points should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first point to be freed. */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of points to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all points are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate space for an arbitrary number of geometry shapes, use <emphasis>
|
||
XkbAllocGeomShapes</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomShapes</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry for which shapes should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new shapes required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomShapes</emphasis>
|
||
allocates space for <emphasis>
|
||
num_needed</emphasis>
|
||
shapes in the specified geometry <emphasis>
|
||
geom</emphasis>
|
||
. The shapes are not initialized.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free geometry shapes, use <emphasis>
|
||
XkbFreeGeomShapes</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomShapes</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
f ree_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry in which shapes should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first shape to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of shapes to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all shapes are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate geometry sections, use <emphasis>
|
||
XkbAllocGeomSections</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomSections</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /*geometry for which sections should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new sections required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomSections</emphasis>
|
||
allocates num_needed sections and adds them to the geometry geom. No
|
||
initialization of the sections is done.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free geometry sections, use <emphasis>
|
||
XkbFreeGeomSections</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomSections</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry in which sections should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first section to be freed. */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of sections to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all sections are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate rows in a section, use <emphasis>
|
||
XkbAllocGeomRows</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomRows</emphasis>
|
||
(<emphasis>
|
||
section</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section for which rows should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new rows required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomRows</emphasis>
|
||
allocates num_needed rows and adds them to the section. No initialization of
|
||
the rows is done.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free rows in a section, use <emphasis>
|
||
XkbFreeGeomRows</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomRows</emphasis>
|
||
(<emphasis>
|
||
section</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section in which rows should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first row to be freed. */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of rows to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all rows are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate overlays in a section, use <emphasis>
|
||
XkbAllocGeomOverlays</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomOverlays</emphasis>
|
||
(<emphasis>
|
||
section</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section for which overlays should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new overlays required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomRows</emphasis>
|
||
allocates num_needed overlays and adds them to the section. No initialization
|
||
of the overlays is done.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free rows in an section, use <emphasis>
|
||
XkbFreeGeomOverlays</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomOverlays</emphasis>
|
||
(<emphasis>
|
||
section</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section in which overlays should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first overlay to be freed. */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of overlays to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all overlays are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate rows in a overlay, use <emphasis>
|
||
XkbAllocGeomOverlayRows</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomOverlayRows</emphasis>
|
||
(<emphasis>
|
||
overlay</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
overlay</emphasis>
|
||
; /* section for which rows should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new rows required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomOverlayRows</emphasis>
|
||
allocates num_needed rows and adds them to the overlay. No initialization of
|
||
the rows is done.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free rows in an overlay, use <emphasis>
|
||
XkbFreeGeomOverlayRows</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomOverlayRows</emphasis>
|
||
(<emphasis>
|
||
overlay</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
overlay</emphasis>
|
||
; /* section in which rows should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first row to be freed. */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of rows to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all rows are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate keys in an overlay row, use <emphasis>
|
||
XkbAllocGeomOverlayKeys</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomOverlayKeys</emphasis>
|
||
(<emphasis>
|
||
row</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbRowPtr <emphasis>
|
||
row</emphasis>
|
||
; /* section for which rows should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new rows required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomOverlayKeys</emphasis>
|
||
allocates num_needed keys and adds them to the row. No initialization of the
|
||
keys is done.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free keys in an overlay row, use <emphasis>
|
||
XkbFreeGeomOverlayKeys</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomOverlayKeys</emphasis>
|
||
(<emphasis>
|
||
row</emphasis>
|
||
,<emphasis>
|
||
first</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbRowPtr <emphasis>
|
||
row</emphasis>
|
||
; /* row in which keys should be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
first</emphasis>
|
||
; /* first key to be freed. */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of keys to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all keys are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, 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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate doodads that are global to a keyboard geometry, use <emphasis>
|
||
XkbAllocGeomDoodads</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomDoodads</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry for which doodads should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new doodads required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomDoodads</emphasis>
|
||
allocates num_needed doodads and adds them to the specified geometry <emphasis>
|
||
geom</emphasis>
|
||
. No initialization of the doodads is done.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate doodads that are specific to a section, use <emphasis>
|
||
XkbAllocGeomSectionDoodads</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeomSectionDoodads</emphasis>
|
||
(<emphasis>
|
||
section</emphasis>
|
||
,<emphasis>
|
||
num_needed</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbSectionPtr <emphasis>
|
||
section</emphasis>
|
||
; /* section for which doodads should be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
num_needed</emphasis>
|
||
; /* number of new doodads required */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeomSectionDoodads</emphasis>
|
||
allocates num_needed doodads and adds them to the specified <emphasis>
|
||
section</emphasis>
|
||
. No initialization of the doodads is done.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free geometry doodads, use <emphasis>
|
||
XkbFreeGeomDoodads</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeomDoodads</emphasis>
|
||
(<emphasis>
|
||
doodads</emphasis>
|
||
,<emphasis>
|
||
count</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbDoodadPtr <emphasis>
|
||
doodads</emphasis>
|
||
; /* doodads to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
int <emphasis>
|
||
count</emphasis>
|
||
; /* number of doodads to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> all doodads are freed */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
If <emphasis>
|
||
free_all</emphasis>
|
||
is <emphasis>
|
||
True</emphasis>
|
||
, all doodads in the array are freed, regardless of the value of count.
|
||
Otherwise, count doodads are freed.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To allocate an entire geometry, use <emphasis>
|
||
XkbAllocGeometry</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
Status <emphasis>
|
||
XkbAllocGeometry</emphasis>
|
||
(<emphasis>
|
||
xkb</emphasis>
|
||
,<emphasis>
|
||
sizes</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbDescPtr <emphasis>
|
||
xkb</emphasis>
|
||
; /* keyboard description for which geometry is to be allocated */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometrySizesPtr<emphasis>
|
||
sizes</emphasis>
|
||
; /* initial sizes for all geometry components */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
<emphasis>
|
||
XkbAllocGeometry</emphasis>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
To free an entire geometry, use <emphasis>
|
||
XkbFreeGeometry</emphasis>
|
||
.
|
||
</para>
|
||
|
||
|
||
<informaltable frame='none'>
|
||
<tgroup cols='1'>
|
||
<colspec colsep='0'/>
|
||
<tbody>
|
||
<row rowsep='0'>
|
||
<entry role='functiondecl'>
|
||
void <emphasis>
|
||
XkbFreeGeometry</emphasis>
|
||
(<emphasis>
|
||
geom</emphasis>
|
||
,<emphasis>
|
||
which</emphasis>
|
||
,<emphasis>
|
||
free_all</emphasis>
|
||
)
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
XkbGeometryPtr <emphasis>
|
||
geom</emphasis>
|
||
; /* geometry to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
unsigned int <emphasis>
|
||
which</emphasis>
|
||
; /* mask of geometry components to be freed */
|
||
</entry>
|
||
</row>
|
||
<row rowsep='0'>
|
||
<entry role='functionargdecl'>
|
||
Bool <emphasis>
|
||
free_all;</emphasis>
|
||
/* <emphasis>
|
||
True</emphasis>
|
||
=> the entire geometry is freed. */
|
||
</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
The values of which and free_all determine how much of the specified geometry
|
||
is freed. The valid values for which are:
|
||
</para>
|
||
|
||
<para><programlisting>
|
||
#define XkbGeomPropertiesMask (1<<0)
|
||
#define XkbGeomColorsMask (1<<1)
|
||
#define XkbGeomShapesMask (1<<2)
|
||
#define XkbGeomSectionsMask (1<<3)
|
||
#define XkbGeomDoodadsMask (1<<4)
|
||
#define XkbGeomAllMask (0x1f)
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
If free_all is <emphasis>
|
||
True</emphasis>
|
||
, the entire geometry is freed regardless of the value of which. Otherwise, the
|
||
portions of the geometry specified by which are freed.
|
||
</para>
|
||
|
||
</sect1>
|
||
</chapter>
|