Drawing Text

ATSUI and Cocoa Text, or one of the application framework utilities that are built on top of them should provide the majority of the functionality that an application needs. Applications with very special text demands can turn to Quartz 2D and draw text directly. There are two different sets of routines for drawing text directly with Quartz 2D. The first set of routines simplify the drawing process by only handling text in a single encoding, Mac Roman. These routines are obviously inappropriate for the broader field of international text. The second set of routines requires the application to supply Quartz 2D with glyph IDs. Applications that want to use these routines must understand quite a bit more about the relationship between characters, encodings, fonts, and glyphs. Both of these routines share some common fields in the graphics state that affect the way they draw.

Text Matrix

The text matrix is an additional affine transformation that Quartz 2D applies to the current transformation matrix when drawing glyphs. You can use this matrix to adjust text independently of the transformation matrix used to draw other graphics. CGContextSetTextMatrix allows you to set the current text matrix, and there is a corresponding Get routine that you can use to retrieve the matrix. These routines accept and return CGAffi neTransformations.

When Quartz applies the text matrix it adjusts the glyphs it is drawing relative to the current text position. The text matrix also affects the way the computer adjusts the current text position after drawing a glyph. This means that if you set the current text matrix to scale the glyphs you draw by 200%, then the computer will also move the advance width by twice the usual distance. All this really means is that the computer adjusts the current text position in accordance with the glyphs that it draws.

Text Position

The translation point stored in the text matrix is called the current text position. When the computer draws text in the context, it places the baseline of the text, in user space, at the current text position. As Quartz 2D draws each glyph, it adjusts the current position to a new location based on the advance width of the glyphs it is drawing. This leaves the current text position where it needs to be to draw the next glyph. Figure 11.3 shows how the current text position changes when the computer draws a character.

Figure 11.3. How Drawing Changes the Text Position

You can set the current text position in a CGContext explicitly using CGContextSetTextPosition. You can also retrieve the current text position with the companion routine CGContextGetTextPosition. If you haven't explicitly set the text position, but the context has a current point, established by using CGContextMoveToPoint for example, the text will draw at that point.

Cocoa Text utility routines draw from a different location than the raw Quartz 2D routines. For example, the point passed to Cocoa drawing routines like drawAtPoint:withAttributes: represent the upper left corner of the bounding box of the text rather than a point on the baseline.

Current Font

As you may guess, the current font determines which font the computer uses when drawing glyphs. There are two routines that allow you to change the current font in the graphics context. The first is CGContextSetFont. This routine accepts an instance of the CGFont opaque data type. A CGFontRef represents a particular font on your system, like Times-Bold. You can create CGFont references using various means including font references from the Apple Type System (ATS). The second routine is CGContextSelectFont. This routine accepts the PostScript name of a font, a font size, and a text encoding as parameters. This routine will attempt to set the current font to the one you specify, but it can fail if the font cannot be found on your system. Unfortunately, the routine doesn't return any indication that it has failed. If you wish to set the text size of the context after selecting a font (using either of the routines just mentioned, you can use the routine CGContextSetFontSize.

Text Drawing Modes

Another field found in the graphics state of a context that you can take advantage of is the text drawing mode. The following list describes the eight text drawing modes supported in Mac OS X 10.4 Tiger:

kCGTextFill Fill the glyph paths.

kCGTextStroke Stroke the glyph paths.

kCGTextFillStroke Fill and then stroke, the glyph paths.

kCGTextInvisible Don't draw the glyphs at all but update the text position as if the glyphs were drawn.

kCGTextClip Do not draw the glyphs but add their shapes to the clipping path of the current context.

kCGTextFillClip Fill the text and then add the glyph outlines to the context's clipping path.

kCGTextStrokeClip Stroke the glyphs and then add the outlines to the context's clipping path.

kCGTextFillStrokeClip Fill and then stroke the text and add the outlines to the text paths.