Legacy Document

Inside Macintosh: Text /

Chapter 3 - QuickDraw Text / Using QuickDraw Text

Measuring and Drawing Single Segments of Text

This section describes how to draw a single glyph or a series of glyphs that share the same font and character attributes. Because you usually measure text before you draw it to determine if it fits on the display area, this section describes the measuring and drawing routines in pairs. These pairs are CharWidth and DrawChar to measure and draw the glyph of a single character, StringWidth and DrawString to measure and draw Pascal strings, and TextWidth and DrawText to measure and draw text segments.

You are responsible for tracking and specifying the memory location and the character attributes of the text to be drawn. This is true whether you are working with a single glyph, a Pascal string, or a text string. For a single glyph, you pass the character code to the procedure; for a Pascal string, you pass the string.

Note

Before you call a QuickDraw measuring or drawing routine, you need to set the graphics port text-related fields to those of the character.

Individual Glyphs

You measure text a character at a time by calling the CharWidth function, and you draw text a character at a time by calling the DrawChar procedure. These routines only work with 1-byte simple script systems.

Although this section describes how to use these routines, you should understand their limitations, and avoid using CharWidth and DrawChar for applications drawing sequences of more than one character. Nevertheless, you may want to use DrawChar for special purposes, such as including a glyph in a book's index, to show a single glyph as it exists apart from contextual transformations.

The CharWidth function takes into account all of the text characteristics defined in the current graphics port, so make sure these values reflect the attributes that you intend to draw with. You can draw a sequence of individual glyphs by placing the pen at the beginning of the leftmost glyph, and making a succession of calls to DrawChar.

Always use CharWidth to measure the width of a sequence of glyphs that you intend to draw using DrawChar, instead of using StringWidth; StringWidth and DrawString accumulate fractional portions, while CharWidth and DrawChar do not. Making successive calls to CharWidth to measure a segment of text and calling StringWidth to measure the same segment of text produce different results.

In general, you should measure and draw text in segments, rather than as individual glyphs. In Roman fonts, if you measure fractional-width glyphs singly using CharWidth, you can get incorrect results, because CharWidth doesn't accumulate fractional-width positions. Also, it takes longer to measure the widths of several glyphs one at a time than it does to measure them together using TextWidth.

For contextual 1-byte fonts, CharWidth and DrawChar do not correctly measure or draw ligatures, reversals, or other contextual forms. You cannot use CharWidth and DrawChar for 2-byte fonts, because they take a 1-byte character code as a parameter.

Pascal Strings

You can call the StringWidth function to measure the screen pixel width of a Pascal string to determine how many glyphs will fit on the screen, and you can call the DrawString procedure to draw a Pascal string with the text characteristics of the current graphics port. The DrawString procedure accumulates the fractional portion as it draws each glyph and positions the next glyph correctly.

You cannot use the DrawString and StringWidth routines to draw or measure a Pascal string that is justified or explicitly scaled. If you want to do this, you must separate the string from its length byte, and call MeasureJustified or StdTxMeas to measure it, and then DrawJustified to draw it, passing the text and the text length separately. Note that a Pascal string is limited to 255 characters. The following code fragment shows how to adjust for the length byte.

myTextPtr := Ptr(Ord(@myString) + 1);
myTextLength := Ord(myString[0]);

Text Segments

You can call the TextWidth function to measure a segment of text to see if it fits on a single line; if it does, then you can the DrawText procedure to draw it.

You pass DrawText a pointer to the text buffer, the byte offset into the text buffer of the first character to be drawn, and the length of the text segment you want to draw. QuickDraw draws the text at the current pen position with the text characteristics of the current graphics port.