Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
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
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.
Background
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:
A
CFStringis a "pure" string--that is, it does not include any text styles or formatting.A
CFString"object" is an opaque data type that represents a string as an array of Unicode characters. Most text-manipulating APIs in Mac OS X useCFStrings.The String Services API (part of the Core Foundation software) includes the routines that manage converting between
CFStringsand pure Unicode, comparing and searchingCFStrings, manipulatingCFStrings, and related functions.
Mac OS X provides built-in support for multilingual text, including
multiple languages in the same document with no restrictions on language intermixing
text highlighting that behaves correctly even in complex situations involving multiple languages of dissimilar type
automatic support for Roman, Japanese, Semitic, Chinese, Indic, and other languages
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.
EditUnicodeTextControl
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."
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
document-wide tabs, justification, and margins
text handling of any length (constrained only by memory)
displaying text in all the languages that Mac OS X supports
text-editing and drag-and-drop behavior as defined by the Apple user interface guidelines
inline input of Japanese, Chinese, and other languages
inclusion of sounds, images, and video within a text field
scroll-bar handling and printing
advanced font features
32 levels of undo and redo
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
style objects, which are sets of font-related characteristics (called style run attributes) that are to be applied to a run of text
text layout objects, which associate style runs, a buffer of text, and various default values to provide a software object that you can manipulate with ATSUI routines
ATSUI includes routines that enable you to perform various font, text styling, and layout functions. Among them are
drawing and highlighting text based on the scripts (fonts/language conventions) involved
discovering what fonts are available and which one most closely fits a set of requirements
obtaining information about a given font and individual glyphs within a font
creating and manipulating style objects and text layout objects
manipulating style run attributes and associating them with runs of text
determining the correct insertion point based on where the text has been clicked
obtaining the spatial boundaries of a laid-out line of text
calculating soft line breaks in a range of text
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:
Apple Text Services for Fonts (also called ATS): Used to determine what fonts are available on the current computer.
Text Encoding Conversion Manager: Used to convert text between non-Unicode encodings and Unicode.
Unicode Utilities: Used to determine text boundaries within a Unicode string, convert keystrokes to Unicode text, and determine the alphabetical order of two Unicode strings (taking into account the alphabetizing rules of the geographic locale under which the user is operating).
For Further Information
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) | |
Text Encoding Conversion Manager | |
appearance.h (DrawnThemeTextBox) | located on the main hard disk of a computer running Mac OS X, at |
ControlDefinitions.h | located on the main hard disk of a computer running Mac OS X, at |
Unicode Utilities |
Copyright © 2003, 2011 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2011-01-05