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.

Table 8-6 Complimentary Font Routines

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	Frees the client-side storage used by the font structure
	UNLOAD FONT	Unloads the font from server memory
LIST FONTS	FREE FONT NAMES	Frees the array and strings returned by LIST FONTS
LIST FONTS WITH INFO	FREE FONT NAMES	Frees the array and strings returned by LIST FONTS WITH INFO
	FREE FONT INFO	Frees the font information array

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.

8.6 Drawing Text

Xlib enables clients to draw text stored in text data structures, text whose foreground bits only are displayed, and text whose foreground and background bits are displayed.

To draw 8-bit or 2-byte text stored in data structures, use either the DRAW TEXT or the DRAW TEXT 16 routine. Xlib includes text item and text item 16 data structures to enable clients to store text. The following illustrates the text item data structure:

typedef struct { char *chars; int nchars; int delta; Font font; } XTextItem;

Table 8-7 describes members of the text item data structure.

Table 8-7 Text Item Data Structure Members

Member Name	Contents
chars	Address of a string of characters.
nchars	Number of characters in the string.
delta	Horizontal spacing before the start of the string. Spacing is always added to the string origin and is not dependent on the font used.
font	Identifier of the font used to print the string. If the value of this member is None, the server uses the current font in the GC data structure. If the member has a value other than None, the specified font is stored in the GC data structure.

The following illustrates the text item 16 data structure:

typedef struct { XChar2b *chars; int nchars; int delta; Font font; } XTextItem16;

Table 8-8 describes members of the text item 16 data structure.

Table 8-8 Text Item 16 Data Structure Members

Member Name	Contents
chars	Address of a string of characters stored in a char 2B data structure. For a description of the char 2B data structure, see the description immediately following this table.
nchars	Number of characters in the string.
delta	Horizontal spacing before the start of the string. Spacing is always added to the string origin and is not dependent on the font used.
font	Identifier of the font used to print the string. If the value of this member is None, the server uses the current font in the GC data structure. If the member has a value other than None, the specified font is stored in the GC data structure.

Xlib provides a char 2B data structure to enable clients to store 2-byte text. The following illustrates the data structure:

typedef struct { unsigned char byte1; unsigned char byte2; } XChar2b;

Xlib processes each text item in turn. Each character image, as defined by the font in the graphics context, is treated as an additional mask for a fill operation on the drawable. The drawable is modified only where the font character has a bit set to 1.

Example 8-1 illustrates using the DRAW TEXT routine to draw three words in one call.

Example 8-1 Drawing Text Using the DRAW TEXT Routine

. . . #define FirstFont "-Adobe-New Century Schoolbook-Bold-R-Normal--*-80-*-*-P-*-ISO8859-1" #define SecondFont "-Adobe-New Century Schoolbook-Bold-R-Normal--*-140-*-*-P-*-ISO8859-1" #define ThirdFont "-Adobe-New Century Schoolbook-Bold-R-Normal--*-240-*-*-P-*-ISO8859-1" Display *dpy; Window window; GC gc; Screen *screen; int n; XTextItem text[] = { "small", 5, 0, 0, "bigger", 6, 0, 0, "biggest", 7, 0, 0, }; . . . /***** Load the font for text writing *****/ static void doLoadFont( ) { Font FontOne, FontTwo, FontThree; FontOne = XLoadFont(dpy, FirstFont); FontTwo = XLoadFont(dpy, SecondFont); FontThree = XLoadFont(dpy, ThirdFont); XSetFont(dpy, gc, FontTwo); text[0].delta = 0; text[0].font = FontOne; text[1].delta = 20; text[1].font = FontTwo; text[2].delta = 20; text[2].font = FontThree; } . . . /***** Button press *****/ static void doButtonPress(eventP) XEvent *eventP; { if (eventP->xbutton.button == Button2) sys$exit (1); if (eventP->xbutton.button == Button1) XDrawText(dpy, window, gc, 100, 300, text, 3); }

To draw 8-bit or 2-byte text, use the DRAW STRING, DRAW STRING 16, DRAW IMAGE STRING, and DRAW IMAGE STRING 16 routines. DRAW STRING and DRAW STRING 16 display the foreground values of text only. DRAW IMAGE STRING and DRAW IMAGE STRING 16 display both foreground and background values.

Example 8-2 illustrates drawing text with the DRAW STRING routine. The example modifies the sample program in Chapter 1 to draw shadow text.

Example 8-2 Drawing Text Using the DRAW STRING Routine

. . . /***** Write the message in the window *****/ static void doExpose(eventP) XEvent *eventP; { if (eventP->xexpose.window != window2) return; XClearWindow(dpy, window2); XSetForeground(dpy, gc, doDefineColor(3)); XDrawString(dpy, window2, gc, 35, 75, message[state], strlen(message[state])); XSetForeground(dpy, gc, doDefineColor(4)); XDrawString(dpy, window2, gc, 31, 71, message[state], strlen(message[state])); } /***** Shutdown *****/ static void doButtonPress(eventP) XEvent *eventP; { if (eventP->xexpose.window != window2) { state = 1; XClearWindow(dpy, window2); XSetForeground(dpy, gc, doDefineColor(3)); XDrawString(dpy, window2, gc, 35, 75, message[state], strlen(message[state])); XSetForeground(dpy, gc, doDefineColor(4)); XDrawString(dpy, window2, gc, 31, 71, message[state], strlen(message[state])); return; } /* Unmap and destroy windows */ XUnmapWindow(dpy, window1); XDestroyWindow(dpy, window1); XCloseDisplay(dpy); sys$exit (1); }

The server refers to the following members of the GC data structure when writing text with DRAW TEXT, DRAW TEXT 16, DRAW STRING, and DRAW STRING 16:

Function	Plane mask
Foreground	Subwindow mode
Stipple	Font
Background	Tile
Tile stipple x origin	Tile stipple y origin
Clip x origin	Clip y origin
Clip mask	Fill style

To draw both foreground and background values of text, use the DRAW IMAGE STRING and DRAW IMAGE STRING 16 routines. For example, the sample program uses the DRAW IMAGE routine to write the text "Click here to exit," as follows:

int n, state = 0; char *message[]= { "Click here to exit", "Click HERE to exit!" }; . . . if (eventP->xexpose.window != window2) return; XDrawImageString(dpy, window2, gc, 75, 75, message[state], strlen(message[state]));

The effect is first to fill a rectangle with the background defined in the graphics context and then to paint the text with the foreground pixel. The upper left corner of the filled rectangle is at 75, (75- font ascent ) . The width of the rectangle is equal to the width of the string. The height of the rectangle is equal to font ascent + font descent .

When drawing text in response to calls to DRAW IMAGE STRING and DRAW IMAGE STRING 16, the server ignores the function and fill style the client has defined in the graphics context. The value of the function member of the GC data structure is effectively the value specified by the constant GXCopy. The value of the fill style member is effectively the value specified by the constant FillSolid.

The server refers to the following members of the GC data structure when writing text with DRAW IMAGE STRING and DRAW IMAGE STRING 16:

Subwindow mode	Plane mask
Foreground	Background
Stipple	Font
Clip x origin	Clip y origin
Clip mask

8.7 Font Usage Hints

This section includes information about the Digital font fallback strategy and hints for using font names efficiently.

8.7.1 Font Fallback Strategy

When specifying fonts, the client should use fonts that are common to both DECwindows Motif and X Window System, Version 11, Release 4 software. Using common fonts makes a client application interoperable and enables it to display on a wide variety of third-party workstations and X terminals. The following lists the common font families:

• Courier
• Helvetica
• New Century Schoolbook
• Symbol
• Times

If clients use other font families (such as ITC Avant Garde Gothic, ITC Lubalin Graph, or ITC Souvenir), the DECwindows toolkit provides the DxmFindFontFallback routine that supports the Digital font fallback strategy. For more information about this routine, see the DECwindows Extensions to Motif.

Digital recommends that clients not use certain fonts. Table 8-9 lists the font families and the reason why. All other font families are for general use.

Table 8-9 Fonts Not Recommended for General Use

Font Family	Reason
Interim DEC Math	For use only by the DECwindows Bookreader. This font will eventually be phased out.
Menu	For use by the DECwindows Toolkit.
Terminal	For use by terminal emulators.
Fixed	Available for compatibility reasons only. Should not be used by new clients.
Variable	Available for compatibility reasons only. Should not be used by new clients.
Fixed Width	Available for compatibility reasons only. Should not be used by new clients.

8.7.2 Speeding Up Font Name Searches

The DECwindows X server uses a heuristic to speed up font name searching. When the client specifies the FAMILY_NAME, WEIGHT_NAME, SLANT, SETWIDTH_NAME, CHARSET_REGISTRY, and CHARSET_ENCODING fields explicitly, the server uses a hash table to speed up font name searching. For example, the following font name is specified correctly to use the heuristic:

-*-Times-Medium-R-Normal--*-140-*-*-P-*-ISO8859-1

The previous example will be found more quickly than the following because a wildcard has been used in the SLANT field:

-*-Times-Medium-*-Normal--*-140-*-*-P-*-ISO8859-1

The client can specify other fields, such as the FOUNDRY field; however, all fourteen hyphens in a font name must be specified for the heuristic to work. The ADD_STYLE_NAME field (the field after Normal in the example) should be left empty because this field may be used in the hashing algorithm in the future.

8.7.3 Monitor Density Independence

To choose a particular sized font without regard to the density of the monitor, the client should always use a wildcard for the PIXEL_SIZE field and never use a wildcard for the POINT_SIZE field. In addition, the client should use a wildcard for the RESOLUTION_X and RESOLUTION_Y fields.

8.7.4 Character Set Considerations

The client should always explicitly specify the CHARSET_REGISTRY and CHARSET_ENCODING fields (for example, ISO8859-1), not only because they speed up font name searching, but because they ensure that the client uses the correct character set. ISO8859-1 specifies the Latin-1 character set that is normally used in text files. There are other possible character sets that could match a wildcard search, such as Latin-2 or Latin-3, but they should not be used if the client can only process and display Latin-1 text.