Legacy Document

Inside Macintosh: Text /

Chapter 3 - QuickDraw Text / QuickDraw Text Reference

Routines / Measuring Text

TextWidth

The TextWidth function returns the length in pixels of the specified text.

FUNCTION TextWidth (textBuf: Ptr; 
                    firstByte, byteCount: Integer): Integer;

textBuf

A pointer to a buffer that contains the text to be measured.

firstByte

An offset from textBuf to the first byte of the text to be measured.

byteCount

The number of bytes of text to be measured.

DESCRIPTION

You can use TextWidth to measure the screen pixel width of any text segment that has uniform character attributes. You can use it to measure the style runs in a line of text, whether you intend to draw the line using DrawText or DrawJustified. The TextWidth function takes into account the character attributes set in the graphics
port. If you change any of these attributes after determining the text width but before actually drawing the text, the predetermined width may not be correct. For a space character, TextWidth also includes the effect of SpaceExtra. For a nonspace character, TextWidth includes the effect of CharExtra.

The TextWidth function works with text in all script systems because the script management system modifies the routine if necessary to give the proper results.

Note

To draw justified lines of text that include multiple style runs, you calculate the amount of extra pixels, or slop, that remains to be distributed throughout the line. This process entails measuring the screen pixel width of each style run on the line: you can use TextWidth for this purpose. For a complete discussion of how to use TextWidth to prepare to draw a line of justified text, refer to "Measuring and Drawing Lines of Text" beginning page 3-29.

SPECIAL CONSIDERATIONS

For 1-byte complex script systems, TextWidth calculates the widths of any ligatures, reversals, and compound characters that need to be drawn.

Note that byteCount is the number of bytes to be measured, not the number of characters. Because 2-byte script systems also include characters consisting of only one byte, you should not simply multiply the number of characters by 2 to determine this value; you must determine and specify the correct number of bytes.