Introduction to ATSUI Programming Guide

Apple Type Services for Unicode Imaging (ATSUI) is the technology behind all text drawing in Mac OS X. This document gives an overview of ATSUI, provides an introduction to the concepts and terms you need to understand ATSUI, discusses the core data types you use to control text layout and styles, and shows you how to use ATSUI in your application.

You should read this document if you plan to write an application that

You might also find parts of this document useful if you are using an API (such as MLTE) that calls into ATSUI, as this document discusses typographical concepts and terms that are relevant to the APIs that call ATSUI.

Organization of This Document

The chapters in the rest of this document cover the following topics:

Overview of ATSUI

Mac OS X is an international operating system. It fully supports Unicode and comes with high-quality fonts capable of displaying many languages, including Japanese and Chinese. Mac OS X supports input of non-phonetic characters used by Chinese, Japanese, and Korean through the use of input methods. Because Mac OS X uses Unicode for all onscreen text display, ASTUI is at the heart of all text drawing in Mac OS X, as shown in Figure I-1. From the Mac OS X Human Interface Toolbox to the Menu Manager, all Mac OS X text drawing at some point uses ATSUI to render Unicode text. For example, the Finder uses ATSUI to display menu items and create text editing fields:

TextEdit is another application among the many Mac OS X applications that use ATSUI to lay out and render Unicode text. The Unicode text rendering of ATSUI includes support for accents and ligatures, bidirectional text, contextual forms and vowel reordering, vertical text, and surrogates.

ATSUI is not just a technology that works behind the scenes; you can call directly into the ATSUI API from your application to render Unicode-encoded text. With ATSUI, you can control many aspects of text layout, including justification, alignment (flushness), kerning, tracking, shifting, and ligature formation. Using ATSUI direct-access functions, you can, if necessary, control how individual segments of glyphs are drawn.

Figure I-1  ATSUI and text drawing in Mac OS X
ATSUI and text drawing in Mac OS X

ATSUI uses opaque objects to keep track of style and layout information that specify how you want text displayed. Using the information in these objects, ATSUI can support high-end typographic control of

ATSUI has a number of functions that support text editing, including highlighting, hit-testing, caret movement, and caret positioning functions. For developers who need to manipulate glyphs directly, ATSUI also provides a set of functions that allows access to glyph outlines and details of the glyph array.

ATSUI provides full Unicode 3.2 layout support and supports text rendering support for all the features required by scripts included with version 2.1 of the Unicode standard or later. The ability of ATSUI to render Unicode text is limited only by the available fonts the user has installed. (ATSUI does not provide other Unicode-related text processing services such as formatting the date and time.)

ATSUI and Font Data

ATSUI takes advantage of all data included in a font. This means if a font designer includes ligatures, swashes, alternate forms, or any data that describes the font, ATSUI can use the data. For example, the Zapfino font provides several forms for a ligature. Using ATSUI, you can access the Zapfino font data to automatically form the appropriate ligature. When ATSUI changes glyphs to provide an alternate form, ligature, or other modification, the text doesn’t change. This ensures that such services as spelling checking and text searching work properly even when the text is redrawn. If you don’t want to use the data provided with a font, you can set up ATSUI to override the data with the settings you provide.

ATSUI and Quartz

ATSUI renders text with Quartz, Apple’s 2D rendering engine, giving your text the look and feel that makes Mac OS X unique. ATSUI is fully integrated with Quartz in Mac OS X. You can use the two technologies together to get superior anti-aliasing and to take advantage of the attributes associated with a Quartz context (CGContext). For example, some features, such as line rotation, are supported by both ATSUI and Quartz. By using ATSUI and Quartz together, you have the option to choose which technology does the rotation. You’ll see how to do this later in Drawing Text Using a Quartz Context.

Quartz provides a number of other features that you may want to take advantage of, such as transparency. You can set a transparency level for a Quartz context, then when you use ATSUI to draw text into the context, the text is drawn with the transparency level specified for the Quartz context.

See Also

ATSUI Reference, a complete reference to the ATSUI programming interface

To download ATSUI-related sample code and to obtain documentation about other programming interfaces related to text and international services, see the Apple developer website:

For detailed information about Unicode: