Legacy Document

Inside Macintosh: Text /

Chapter 3 - QuickDraw Text / Using QuickDraw Text

Specifying Text Characteristics

Each time you measure or draw text that begins a new style run and whose characteristics differ from those of the current graphics port, first you need to set the graphics port text-related fields to match those of the text. Here is how the text-related graphic port fields are initialized:

Field	Value	Explanation
txFont	0	System font
txFace	[]	Plain style of the current font
txSize	0	Size of the system font used to draw text
spExtra	0	Standard width of the space character for the font
chExtra	0	Standard width of nonspace characters for the font
txMode	srcOr	Combines the destination with the source

Do not modify any of these fields directly. Instead, always use the QuickDraw routines to change their values: TextFace, TextFont, TextMode, TextSize, SpaceExtra, and CharExtra. Using these routines ensures that your application will benefit from any future improvements to QuickDraw.

Listing 3-1 shows a simple sequence of QuickDraw calls. These routines set the current port, set the graphics port text fields, then draw a text string. The calls render the text in 12-point Geneva font using the styles bold and italic, and widen the spaces between words by 3 pixels to format the text. QuickDraw text-handling procedures that set these fields are discussed later in this section.

Listing 3-1 Using QuickDraw to set the graphics port text-related fields

SetPort(thePort);
TextFont(geneva);
TextFace([bold, italic]);
TextSize(12);
SpaceExtra(3);

If you must directly change the values of any of the graphics port fields, call the QuickDraw PortChanged procedure to notify QuickDraw of the change after you modify the field. For more information about PortChanged, see the QuickDraw chapters in Inside Macintosh: Imaging.

Setting the Font

You use the TextFont procedure to set the font for the text. The value that you specify for this field is either the font family ID or a predefined constant.

If you know the font name, you can get the font family ID by calling the GetFNum procedure, passing it the font name. You can get a font's name if it has a font family ID by calling the Font Manager GetFontName procedure. For more information about these procedures and the predefined font constants, see the chapter "Font Manager" in this book.

If you do not know either the font family ID or the name of the font, you can use the Resource Manager's GetIndResource function followed by the GetResInfo procedure to determine the fonts that are available and what their names and IDs
are. See the chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox
for more information.

The values 0 and 1 have special significance. When a graphics port is created, the txFont field is initialized to 0, which specifies the system font. This is the font that the system uses to draw text in system menus and system dialog boxes. You can use a font that is defined by the system--to do so, it sets this field to 1; 1 always specifies the application font.

Note

Do not use the font family ID 0 or the constant 'chicago' to specify the Chicago font because the ID can vary on localized systems. To specify the Chicago font, use the following calls.

GetFNum('Chicago', theNum);
TextFont(theNum);

The variable theNum is an integer.

Storing a font name in a document

Always store a font name, rather than its font family ID, in a document to avoid problems that can arise because IDs are not unique--many font families share the same font family ID--or because one font family may have different IDs on different computer systems.

You use TextFont to set the txFont field of the current graphics port for a new style run that uses a font different from the current one, and in response to a user's actions, for example, when a user selects a new font from a menu.

Note

Whenever a user changes the keyboard script, you are responsible for setting the txFont field to the new font, so that the keyboard script and the font script are synchronized.

Modifying the Text Style

When you create a graphics port, the txFace field value is initially an empty set ([]), which specifies the plain style of the current font.

To change the text style, you call TextFace, using any combination of the following constants to specify the text style: bold, italic, underline, outline, shadow, condense, and extend. In Pascal, you specify the value or values within square brackets. For example:

TextFace([bold]);          {bold}
TextFace([bold,italic]);   {bold and italic}

You can also add another style to the current text style, or remove a style. For example:

TextFace(thePort^.txFace+[bold]); {existing style plus bold}
TextFace(thePort^.txFace-[bold]); {existing style minus bold}

To reset the style to plain, you specify an empty set. For example:

TextFace([]);  {plain text}

If you want to restore the existing value after you draw the text in another style, save it before you call TextFace. For a description of how QuickDraw renders text in each of these styles, see "Font, Font Style, and Font Size" on page 3-5.

Changing the Font Size

When you create a graphics port, the value of the txSize field is 0, which specifies the size of the font to be used to draw system text, such as menus. The size of the system font is usually 12 points. You use the TextSize procedure to set the txSize field of the current graphics port to the font's point size. Text drawn on the QuickDraw coordinate plane can range from 1 point to 32,767 points.

Changing the Width of Characters

When you create a graphics port, the spExtra and chExtra fields are set to 0, which specifies the standard width for space and nonspace characters in the font. You change the width of space characters and nonspace characters using the SpaceExtra and CharExtra procedures, respectively.

Widening or narrowing space and nonspace characters lets you meet special formatting requirements that are not satisfied by simply justifying the text. If you want to change only the width of the space characters in a line of text for onscreen typographical formatting, you can set the spExtra field value before you draw each style run, narrowing spaces in some style runs and widening those in others. To change the width of nonspace characters, either extending them or narrowing them, you set the chExtra field value before you draw a style run.

You use the SpaceExtra procedure to set the spExtra field of the current graphics port to the number of pixels to be added to or subtracted from the standard width of the space character in the style run. (A value specified in the spExtra field is ignored by script systems that do not use space characters, so don't to set it for 2-byte script systems that use only intercharacter spacing.) The text measuring and drawing routines apply the spExtra field pixel value to every space in the text string, regardless of whether the space occurs at the beginning or the end of a style run or between words within a style run. You can use the SpaceExtra procedure, for both a color graphics port (CGrafPort) and an original graphics port (GrafPort).

You use the CharExtra procedure to set the chExtra field of the current graphics port to the number of extra pixels to be added to or subtracted from the width of all nonspace characters in a style run. Because only the color graphics port record has a chExtra field, use of CharExtra is limited to color graphics ports. The measuring and drawing routines apply the pixel value that you set in the chExtra field to the right side of the glyph of each nonspace character.

You can use SpaceExtra and CharExtra together, for example, to format text consisting of multiple style runs with different fonts in order to create a smooth visual effect by causing the fonts to measure the same or proportionally.

Note

Although printing on a LaserWriter preserves the line's endpoints, it alters the line layout in between. Any formatting internal to the line that you set through SpaceExtra and CharExtra is lost when you print.

If you do not want to use the justification routines to draw justified text, you can justify a line of text using SpaceExtra and CharExtra to widen each glyph (space and nonspace characters) by the same amount of pixels for onscreen display. Here is how
you do this:

1. Determine the slop value to be applied to the text to justify it.
   • Measure the width in pixels of each style run in the line of text using TextWidth.
   • Sum the values.
   • Subtract the total from the display line length.

2. Count the total number of characters (both space characters and nonspace characters) that the text contains.
3. Divide the slop value by the number of characters minus 1. Round the slop value to a whole number.
4. Call the SpaceExtra procedure, passing it the result of step 3.
5. Call the CharExtra procedure, passing it the result of step 3.
6. Call DrawText or DrawString to draw each style run on the line.

Use of CharExtra entails some restrictions. You cannot use intercharacter spacing for 1-byte complex script systems or 1-byte simple script systems that include zero-width characters, such as diacritical marks, because of the way extra width is applied to a glyph. For example, for 1-byte simple script systems with diacritical marks, intercharacter space is added to all glyphs separating the diacritical mark from the glyph of the character.

Using Fractional Glyph Widths

Fractional glyph widths are measurements of a glyph's width that can include fractions of a pixel. Using fractional glyph widths allows QuickDraw to place glyphs on the screen
in a manner that will closely match the eventual placement of glyphs on a page printed by a LaserWriter. Fractional glyph widths make it possible for the LaserWriter printer to print with better spacing. You can use the Font Manager's SetFractEnable procedure to turn the use of fractional glyph widths on or off.

Because screen glyphs are made up of whole pixels, QuickDraw cannot draw a fractional glyph. To compensate, QuickDraw rounds off the fractional parts resulting in uneven spacing between glyphs and words. Although the text is somewhat distorted on the screen, it is correctly proportioned and shows no distortion when printed on a page using a LaserWriter.

However, to avoid screen distortion, your application can disable the use of fractional widths. A consequence of this it that placement of text on the printed page is less than optimal. For more information about fractional glyph widths, see the chapter "Font Manager" in this book.