< Previous PageNext Page > Hide TOC

Using Text in Mac OS X

Given the Macintosh's strong roots in desktop publishing, it should come as no surprise that Mac OS X provides powerful APIs for manipulating and displaying multilingual, styled, static, and editable text. Of course, since you are porting an existing Win32 application to Mac OS X, you may not be interested in Mac OS X's advanced text features. Still, it's nice to know what's available, and that's what this section is about.

Depending on your situation, you may not even need know about the Mac OS X text APIs. If your use of text is limited to providing simple text-entry fields and labeling user-interface elements, you can do that from Interface Builder. If your application uses text in more sophisticated ways, you need to read this section.


Comparisons with Win32
Drawing Static Text
Drawing Editable Text
Other APIs
For Further Information

Comparisons with Win32

The most important thing you need to know about Mac OS X's use of text is that, like the Win32 platform, Mac OS X always stores its strings in Unicode. Since your application probably uses Unicode for encoding text, you should be comfortable with Mac OS X's use of Unicode.

Like Win32, Mac OS X provides several APIs for static and editable text. If your needs are simple, Mac OS X provides easy-to-use routines that get the job done. Other, more complex APIs give you additional capabilities and greater control. Somewhere along this spectrum, you should able to find routines that roughly correspond to the Win32 routines in your original code.


Although some Mac OS X routines take Unicode strings as arguments, most manipulate text stored as a CFString ("CF" is an abbreviation for Core Foundation, which is the part of Mac OS X that defines fundamental data structures and types used by Carbon and Cocoa). Here are some things to remember about CFStrings:

Mac OS X provides built-in support for multilingual text, including

Drawing Static Text

If you simply need to draw static text (that is, text that cannot be edited), your best choice is DrawThemeTextBox, which is part of the Appearance Manager API. This routine can only draw unstyled text, but the text is drawn in a font that matches a selected theme. Look for documentation on this and related routines in the file appearance.h. If the text you need to draw is part of your user interface, use the StaticText control on the Carbon-Controls pane of the Interface Builder controls palette.

Multilingual Text Engine (MLTE) contains more capable text-drawing routines. Its basic routine is TXNDrawCFStringTextBox, which takes a CFString as input. Since you are probably using Unicode strings in your application, you may want to use TXNDrawUnicodeTextBox, which takes a plain Unicode string as input.

For the most powerful text-drawing routines, you need to use Apple Type Services for Unicode Imaging (ATSUI). The text-drawing routine is ATSUDrawText, although you must first use other ATSUI routines to set up the drawing operation.

Drawing Editable Text

Mac OS X includes three APIs that you can use to provide editable text in your applications. The simplest, EditUnicodeTextControl, is sufficient for most situations. The second, MLTE, provides all the functionality most developers will need. Very few developers will need to use the third, ATSUI. The following sections describe these APIs.


The EditUnicodeTextControl is the simplest control for editable Unicode text. (Remember, Mac OS X uses Unicode strings throughout the system, so you need to be sure that you capture any text the user enters as Unicode text.) The routine you use to create an EditUnicodeTextControl is called CreateEditUnicodeTextControl; you can find it in the file ControlDefinitions.h.

If the text box you need is part of your user interface, use the EditText control on the Carbon-Controls pane of the Interface Builder controls palette. In the Attributes pane on the Info window for the EditText control, be sure to check the option titled "Unicode Edit Text."

image: ../art/unicodetext.jpg

Multilingual Text Engine

MLTE provides a straightforward interface for providing multilingual Unicode styled text editing to your application. Built on top of ATSUI, MLTE includes support for

Apple Type Services for Unicode Imaging (ATSUI)

ATSUI is the type technology that underlies all text drawing in Mac OS X. Although other APIs built on top of ATSUI provide simpler text-drawing functions, ATSUI provides an extremely high level of typographic control.

ATSUI enables sophisticated rendering of Unicode 3.2-encoded text (including such features as kerning, ligatures, and optical alignment). It automatically handles many of the complexities inherent in text layout, including how to correctly render text in bidirectional and vertical script systems.

ATSUI introduces new objects that enable it to provide higher levels of control and flexibility. Some examples are

ATSUI includes routines that enable you to perform various font, text styling, and layout functions. Among them are

Because ATSUI uses Mac OS X's Quartz 2D graphics engine for all of its drawing, ATSUI users can access Quartz's image scaling, rotation, and transformation features.

One technical note: By reallocating and reusing ATSUStyle records, you can speed up the drawing of ATSUI-based text. See "Improving ATSUI text drawing performance" for details.

Other APIs

Mac OS X includes a number of other APIs related to text, fonts, and strings. In addition to the ones already discussed, here are the ones that you are most likely to use:

For Further Information

You can find all the APIs discussed here on the Carbon Developer Documentation page.

Appearance Manager

Appearance Manager Reference

Apple Text Services for Fonts (ATS)

Apple Type Services for Fonts Reference

Apple Text Services for Unicode Imaging (ATSUI)

ATSUI Reference

"Improving ATSUI text drawing performance" Technical Note


Multilingual Text Engine (MLTE)

Multilingual Text Engine Reference

String Services (CFStrings)

Strings Programming Guide for Core Foundation

Text Encoding Conversion Manager

Text Encoding Conversion Manager Reference

appearance.h (DrawnThemeTextBox)

located on the main hard disk of a computer running Mac OS X, at /System/Library/Frameworks/Carbon.framework/Frameworks/ HIToolbox.framework/Headers/appearance.h


located on the main hard disk of a computer running Mac OS X, at /System/Library/Frameworks/Carbon.framework/Frameworks/ HIToolbox.framework/Headers/ControlDefinitions.h

Text and Fonts Sample Code

Unicode Utilities

Unicode Utilities Reference

< Previous PageNext Page > Hide TOC

© 2003, 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-05-06)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.