| Previous | Contents | Index |
This chapter describes writing text using Xlib. The chapter includes the following topics:
VMS DECwindows provides a font compiler to enable programmers to
convert ASCII files into binary form. For a guide to using the font
compiler, see Appendix A.
8.1 Characters and Fonts
The smallest unit of text the server displays on a screen is a character. Pixels that form a character are enclosed within a bounding box that defines the number of pixels the server turns on or off to represent the character on the screen. For example, Figure 8-1 illustrates the bounding box that encloses the character y.
The server turns each pixel within the bounding box either on or off, depending on the character. Consequently, bounding box size affects performance. Larger bounding boxes require more server time to process than do smaller boxes.
The character is positioned relative to the baseline and the character origin. The baseline is logically viewed as the x-axis that runs just below nondescending characters. The character origin is a point along the baseline. The left bearing of the character is the distance from the origin to the left edge of the bounding box; the right bearing is the distance from the origin to the right edge. Ascent and descent measure the distance from the baseline to the top and bottom of the bounding box, respectively. Character width is the distance from the origin to the next character origin ( x+ width , y ).
Figure 8-1 Composition of a Character
Figure 8-2 illustrates that the bounding box of a character can extend beyond the character origin. The bounding box of the slash extends one pixel to the left of the origin of the slash, giving the character a left bearing of -1 . The slash is also unusual because its bounding box extends to the right of the next character. The width of the slash, measured from origin to origin, is 5; the right bearing, measured from origin to the right edge of the bounding box, is 6.
Figure 8-2 Composition of a Slash
The left bearing, right bearing, ascent, descent, and width of a character are its character metrics. Xlib maintains information about character metrics in a char struct data structure. Figure 8-3 illustrates the data structure.
Figure 8-3 Char Struct Data Structure
Table 8-2 describes members of the data structure.
| Member Name | Contents |
|---|---|
| X$T_CHAR2B_BYTE1 | Row in which the character is indexed |
| X$T_CHAR2B_BYTE2 | Position of the character in the row |
Xlib provides clients a font struct data structure to record the characteristics of single-row and multiple-row fonts. Figure 8-7 illustrates the font struct data structure.
Figure 8-7 Font Struct Data Structure
N
is equal to the last column minus the first column plus 1.
For example, the array index of the character specified in Figure 8-9 is 443. Figure 8-9 Indexing Multiple-Row Font Character Metrics
Like windows, fonts may have properties associated
with them. However, font properties differ from window properties.
Window properties are data associated with windows; font properties
describe font characteristics, such as spacing between words. When the
font is compiled, its properties are defined in an array of font prop
data structures.
Just as atoms name window properties, atoms name font properties. If
the atoms are predefined, they have associated literals. For example,
the predefined atom that identifies the height of capitalized letters
is referred to by the literal X$C_XA_CAP_HEIGHT. When working with
properties, clients must know beforehand how to interpret the font
property identified by an atom. Figure 8-10 illustrates this concept.
The server maintains an atom table for font properties. The table
associates values with strings. For example, the atom table illustrated
in Figure 8-10 defines two atoms. One associates the string FULL_NAME
with the value 41. The other associates the string CAP_HEIGHT with the
value 42. Notice that the string in the atom table is different from
X$C_XA_FULL_NAME, the literal that refers to the atom. Both atoms
uniquely identify different types of data. FULL_NAME identifies string
data that names the font. CAP_HEIGHT identifies integer data that
defines the size of capitalized letters. Although the atoms identify
different types of data, the property table illustrated in
Figure 8-10 associates both atoms with integers. The integer
associated with CAP_HEIGHT defines without further interpretation the
height of capitalized letters. However, the integer listed with
FULL_NAME is an atom value. This integer, 90, corresponds to a value in
the atom table that has an associated string, HELVETICA BOLD. To use
the string, the client must know that the value associated with the
atom is itself an atom value.
Figure 8-10 Atoms and Font Properties 
Xlib lists each font property and its corresponding
atom in a font prop data structure. The property value table in
Figure 8-10 is an array of font prop data structures. Figure 8-11
illustrates the font prop data structure. Figure 8-11 Font Prop Data
Structure 5643xfont_prop_pic.tex 0
Table 8-4 describes members of the data structure.
| Member Name | Contents |
|---|---|
| X$L_FNTP_NAME | String of characters that names the property |
| X$L_FNTP_CARD32 | A 32-bit value that defines the font property |
To specify a font for writing text, first load the font and then associate the loaded font with a graphics context. The font files are stored in:
Appendix C lists VMS DECwindows font names.
To load a font, use either the LOAD FONT or the LOAD QUERY FONT routine. LOAD FONT loads the specified font and returns a font identifier. LOAD QUERY FONT loads the specified font and returns information about the font to a font struct data structure.
Because LOAD QUERY FONT returns information to a font struct data structure, calling the routine takes significantly longer than calling LOAD FONT, which returns only the font identifier.
When using either routine, pass the display identifier and font name. Xlib font names consist of the following fields, in left-to-right order:
For more information about font names, see the X Logical Font Description (XLFD) in the X Window System.
The full XLFD name of a representative font is as follows:
-Adobe-ITC Avant Garde Gothic-Book-R-Normal--14-100-100-100-P-80-ISO8859-1 |
The font foundry is Adobe. The font family is ITC Avant Garde Gothic. Font weight is Book, font slant is R (roman), and width between font units is Normal.
The pixel size is 14 and the decipoint size is 100. (The actual point size is 10.)
Horizontal and vertical resolution in dots per inch (dpi) is 100. When the dpi is 100, 14 pixels are required to be a 10-point font.
The font is proportionally spaced. Average width of characters is 80 decipixels. Character encoding is ISO Latin-1.
The following designates the full XLFD name of the comparable font designed for a 75 dpi monitor:
-Adobe-ITC Avant Garde Gothic-Book-R-Normal--10-100-75-75-P-59-ISO8859-1 |
Unlike the previous font, this font requires only 10 pixels to be 10 points. Note that this font differs from the previous font only in pixel size, resolution, and average character width.
Xlib enables clients to substitute a question mark for a single character and an asterisk (*) for one or more fields in a font name. The following illustrates using the asterisk to specify a 10-point ITC Avant Garde Gothic font of book weight, roman style, and normal spacing for display on either 75 or 100 dpi monitors:
-Adobe-ITC Avant Garde Gothic-Book-R-Normal--*-100-*-*-P-*-ISO8859-1 |
See Section 8.7 for more information about using asterisks in font names.
The following example illustrates loading the 10-point font:
CHARACTER*58 FONT_NAME
DATA FONT_NAME
1 /'-Adobe-ITC Avant Garde Gothic-Book-R-Normal--*-100-*-*-P-*-ISO8859-1'/
.
.
.
FONT = X$LOAD_FONT(DPY, FONT_NAME)
.
.
.
|
After loading a font, associate it with a graphics context by calling the SET FONT routine. Specify the font identifier that either LOAD FONT or LOAD QUERY FONT returned and a graphics context, as in the following example:
CALL X$SET_FONT(DPY, GC, FONT) |
The call associates FONT with GC.
When loading fonts, note that the LOAD FONT routine is an asychronous routine and does not return an error if the call is unsuccessful. Use one of the following three methods to determine the validity of the font id:
Xlib provides clients with routines that list available fonts, get font information with or without character metrics, and return the value of a specified font property.
To get a list of available fonts, use the LIST FONTS routine, specifying the font searched for.
LIST FONTS returns a list of available fonts that match the specified font name.
To receive both a list of fonts and information about the fonts, use the LIST FONTS WITH INFO routine. LIST FONTS WITH INFO returns both a list of fonts that match the font specified by the client and the address of a font struct data structure for each font listed. Each data structure contains information about the font. The data structure does not include character metrics in the X$A_FSTR_PER_CHAR member. For a description of the information returned, see Table 8-3.
To receive information about a font, including character metrics, use the QUERY FONT routine. Because the server returns character metrics, calling QUERY FONT takes approximately eight times longer than calling LIST FONTS WITH INFO. To get the value of a specified property, use the GET FONT PROPERTY routine.
Although a font is not guaranteed to have any properties, it should have at least the properties described in Table 8-5. The table lists properties by atom name and data type. For information about properties, see Section 3.5.
| Atom | Data Type | Description of the Property |
|---|---|---|
| X$C_XA_MIN_SPACE | unsigned | Minimum spacing between words, in pixels. |
| X$C_XA_NORMAL_SPACE | unsigned | Normal spacing between words, in pixels. |
| X$C_XA_MAX_SPACE | unsigned | Maximum spacing between words, in pixels. |
| X$C_XA_END_SPACE | unsigned | Additional spacing at the end of a sentence, in pixels. |
| X$C_XA_SUPERSCRIPT_X | signed |
With X$C_XA_SUPERSCRIPT_Y, the offset from the character origin where
superscripts should begin, in pixels. If the origin is [x, y],
superscripts should begin at the following coordinates:
x + X$C_XA_SUPERSCRIPT_X, |
| X$C_XA_SUPERSCRIPT_Y | signed | With X$C_XA_SUPERSCRIPT_X, the offset from the character origin where superscripts should begin, in pixels. See the description under X$C_XA_SUPERSCRIPT_X. |
| X$C_XA_SUBSCRIPT_X | signed |
With X$C_XA_SUBSCRIPT_Y, the offset from the character origin where
subscripts should begin, in pixels. If the origin is [x, y], subscripts
should begin at the following coordinates:
x + X$C_XA_SUBSCRIPT_X, |
| X$C_XA_SUBSCRIPT_Y | signed | With X$C_XA_SUBSCRIPT_X, the offset from the character origin where subscripts should begin, in pixels. See the description under X$C_XA_SUBSCRIPT_X. |
| X$C_XA_UNDERLINE_POSITION | signed | The y offset from the baseline to the top of an underline, in pixels. If the baseline y-coordinate is y, then the top of the underline is at y + X$C_XA_UNDERLINE_POSITION. |
| X$C_XA_UNDERLINE_THICKNESS | unsigned | Thickness of the underline, in pixels. |
| X$C_XA_STRIKEOUT_ASCENT | signed |
With X$C_XA_STRIKEOUT_DESCENT, the vertical extent for boxing or
voiding characters, in pixels. If the baseline y-coordinate is y, the
top of the strikeout box is y - X$C_XA_STRIKEOUT_ASCENT. The height of
the box is as follows:
X$C_XA_STRIKEOUT_ASCENT + |
| X$C_XA_STRIKEOUT_DESCENT | signed | With X$C_XA_STRIKEOUT_ASCENT, the vertical extent for boxing or voiding characters, in pixels. See the description under X$C_XA_STRIKEOUT_ASCENT. |
| X$C_XA_ITALIC_ANGLE | signed | The angle of the dominant staffs of characters in the font, in degrees scaled by 64, relative to the 3 o'clock position from the character origin. Positive values indicate counterclockwise motion. |
| X$C_XA_X_HEIGHT | signed | One ex, as in TeX, but expressed in units of pixels. Often the height of lowercase x. |
| X$C_XA_QUAD_WIDTH | signed | One em, as in TeX, but expressed in units of pixels. Often the width of the digits 0 to 9. |
| X$C_XA_CAP_HEIGHT | signed | The y offset from the baseline to the top of capital letters, ignoring ascents. If the baseline y-coordinate is y, the top of the capitals is at y - X$C_XA_CAP_HEIGHT. |
| X$C_XA_WEIGHT | unsigned | Weight or boldness of the font, expressed as a value between 0 and 1000. |
| X$C_XA_POINT_SIZE | unsigned | Point size of the font at ideal resolution, expressed in 1/10 points. |
| X$C_XA_RESOLUTION | unsigned | Number of pixels per point, expressed in 1/100, at which the font was created. |
| X$C_XA_COPYRIGHT | unsigned | Copyright date of the font. |
| X$C_XA_NOTICE | unsigned | Copyright date of the font name. |
| X$C_XA_FONT_NAME | atom | Font name. For example: -Adobe-Helvetica-Bold-R-Normal--10-100-75-75-P-60-ISO8859-1 |
| X$C_XA_FAMILY_NAME | atom | Name of the font family. For example: Helvetica |
| X$C_XA_FULL_NAME | atom | Full name of the font. For example: Helvetica Bold |
Because allocating fonts requires large amounts of memory, it is important to deallocate these resources when the client no longer needs them. Table 8-6 lists complimentary font routines and the result when the deallocating routine is called.
| Allocating Routine | Deallocating Routine | Result |
|---|---|---|
| LOAD FONT | UNLOAD FONT | Deletes the association between the font resource ID and the specified font and unloads it from server memory |
| LOAD QUERY FONT | FREE FONT | Unloads and frees the storage used by the font structure |
| UNLOAD FONT | Unloads the font from server memory |
Note that because the routines LIST FONTS and LIST FONT WITH INFO
return the font information via a single descriptor, the deallocating
routine FREE FONT NAMES is not needed.
8.5 Computing the Size of Text
Use the TEXT WIDTH and TEXT WIDTH 16 routines to compute the width of 8-bit and 2-byte strings, respectively. The routines return the sum of the width of each character in the specified string. To compute the bounding box of a specified 8-bit string, use either the TEXT EXTENTS or QUERY TEXT EXTENTS routine. Both TEXT EXTENTS and QUERY TEXT EXTENTS return the direction hint, ascent, descent, and overall size of the character string being queried.
TEXT EXTENTS passes to Xlib the font struct data structure returned by a previous call to either LOAD QUERY FONT or QUERY FONT. QUERY TEXT EXTENTS queries the server for font information, which the server returns to a font struct data structure. Because Xlib can process TEXT EXTENTS locally, without querying the server for font metrics, calling TEXT EXTENTS is significantly faster than calling QUERY TEXT EXTENTS.
To compute the bounding boxes of a specified 2-byte string, use either the TEXT EXTENTS 16 or the QUERY TEXT EXTENTS 16 routine. Both routines return information identical to information returned by TEXT EXTENTS and QUERY TEXT EXTENTS. As with TEXT EXTENTS, calling TEXT EXTENTS 16 is significantly faster than calling QUERY TEXT EXTENTS 16 because Xlib can process the call without making the round-trip to the server.
| Previous | Next | Contents | Index |