ATSUI Reference (Not Recommended)

Framework
ApplicationServices/ApplicationServices.h
Declared in
ATSLayoutTypes.h
ATSUnicodeDirectAccess.h
ATSUnicodeDrawing.h
ATSUnicodeFlattening.h
ATSUnicodeFonts.h
ATSUnicodeGlyphs.h
ATSUnicodeObjects.h
ATSUnicodeTypes.h

Overview

Apple Type Services for Unicode Imaging (ATSUI) enables the rendering of Unicode-encoded text with advanced typographic features. It automatically handles many of the complexities inherent in text layout, including the correct rendering of text in bidirectional and vertical script systems.

ATSUI may be useful to developers who are writing new text editors or word processing applications that render Unicode-encoded text. You can also use ATSUI if you want to modify your existing application to support Unicode text rendering.

This document describes the ATSUI application programming interface (API) through version 2.4. If you are a font designer or want more information about fonts, see the Apple font site: http://developer.apple.com/fonts/

Functions by Task

Creating and Initializing Style Objects

Manipulating Style Attributes

Manipulating Font Features

Manipulating Font Variations

Creating and Initializing Text Layout Objects

Manipulating Text Layout Attributes

Manipulating Line Attributes

Manipulating Line Breaks

Substituting Fonts

Identifying Fonts

Drawing and Highlighting Text

Supporting User Interaction With Onscreen Text

Obtaining Text Metrics

Working With Tabs

Accessing Glyph Data

Flattening and Parsing Style Data

Creating, Calling, and Deleting Universal Procedure Pointers

Not Recommended

Callbacks

ATSCubicClosePathProcPtr

Defines a pointer to a cubic close-path callback for drawing glyphs that overrides ATSUI’s cubic close-path operation for drawing glyphs.

typedef OSStatus(* ATSCubicClosePathProcPtr)
(
   void *callBackDataPtr
);

If you name your function MyATSCubicClosePathCallback, you would declare it like this:

OSStatus MyATSCubicClosePathCallback (
   void *callBackDataPtr
);

Parameters
callBackDataPtr

A pointer to any data your callback function needs. You pass this pointer to the function ATSUGlyphGetCurvePaths. Then, ATSUI passes the pointer through to your callback function when your callback function is invoked.

Return Value

A value that indicates the status of your callback function. When a callback function returns any value other than 0, the ATSGlyphGetCubicPaths function stops parsing the path outline and returns the result kATSOutlineParseAbortedErr.

Discussion

You supply a pointer to your customized cubic close-path callback as a parameter to the function ATSUGlyphGetCubicPaths.

To provide a pointer to your cubic close-path callback, you create a universal procedure pointer (UPP) of type ATSCubicClosePathUPP, using the function NewATSCubicClosePathUPP. You can do so with code similar to the following:

ATSCubicClosePathUPP MyCubicClosePathUPP;
MyCubicClosePathUPP = NewATSCubicClosePathUPP (&MyATSCubicClosePathCallback);

When you no longer need to use your cubic close-path callback, you should use the function DisposeATSCubicClosePathUPP to dispose of the universal procedure pointer associated with the callback.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSCubicCurveToProcPtr

Defines a pointer to a cubic curve-to callback for drawing glyphs that overrides ATSUI’s cubic curve-to operation for drawing glyphs.

typedef OSStatus(* ATSCubicCurveToProcPtr)
(
   const Float32Point *pt1,
   const Float32Point *pt2,
   const Float32Point *pt3,
   void *callBackDataPtr
);

If you name your function MyATSCubicCurveToCallback, you would declare it like this:

OSStatus MyATSCubicCurveToCallback (
   const Float32Point *pt1,
   const Float32Point *pt2,
   const Float32Point *pt3,
   void *callBackDataPtr
);

Parameters
pt1

A Float32Point data structure that contains the x and y coordinates for the relative point that defines the first off-curve point for this segment of the glyph.

pt2

A Float32Point data structure that contains the x and y coordinates for the relative point that defines the second off-curve point for this segment of the glyph.

pt3

A Float32Point data structure that contains the x and y coordinates for the relative point that defines the end of the curve (an on-curve point) for this segment of the glyph.

callBackDataPtr

A pointer to any data your callback function needs. You pass this pointer to the function ATSUGlyphGetCurvePaths. Then, ATSUI passes the pointer through to your callback function when your callback function is invoked.

Return Value

A value that indicates the status of your callback function. When a callback function returns any value other than 0, the ATSGlyphGetCubicPaths function stops parsing the path outline and returns the result kATSOutlineParseAbortedErr.

Discussion

You supply a pointer to your customized cubic curve-to function as a parameter to the function ATSUGlyphGetCubicPaths.

To provide a pointer to your cubic curve-to callback, you create a universal procedure pointer (UPP) of type ATSCubicCurveToUPP, using the function NewATSCubicCurveToUPP. You can do so with code similar to the following:

ATSCubicCurveToUPP MyCubicCurveToUPP;
MyCubicCurveToUPP = NewATSCubicCurveToUPP (&MyATSCubicCurveToCallback);

When you no longer need to use your cubic curve-to callback, you should use the function DisposeATSCubicCurveToUPP to dispose of the universal procedure pointer associated with the callback.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSCubicLineToProcPtr

Defines a pointer to a cubic line-to callback for drawing glyphs that overrides ATSUI’s cubic line-to operation for drawing glyphs.

typedef OSStatus(* ATSCubicLineToProcPtr)
(
   const Float32Point *pt,
   void *callBackDataPtr
);

If you name your function MyATSCubicLineToCallback, you would declare it like this:

OSStatus MyATSCubicLineToCallback (
   const Float32Point *pt,
   void *callBackDataPtr
);

Parameters
pt

A Float32Point data structure that contains the x and y coordinates for the relative point to which the pen should draw a line.

callBackDataPtr

A pointer to any data your callback function needs. You pass this pointer to the function ATSUGlyphGetCurvePaths. Then, ATSUI passes the pointer through to your callback function when your callback function is invoked.

Return Value

A value that indicates the status of your callback function. When a callback function returns any value other than 0, the ATSGlyphGetCubicPaths function stops parsing the path outline and returns the result kATSOutlineParseAbortedErr.

Discussion

You supply a pointer to your customized cubic line-to callback as a parameter to the function ATSUGlyphGetCubicPaths.

To provide a pointer to your cubic line-to callback, you create a universal procedure pointer (UPP) of type ATSCubicLineToUPP, using the function NewATSCubicLineToUPP. You can do so with code similar to the following:

ATSCubicLineToUPP MyCubicLineToUPP;
MyCubicLineToUPP = NewATSCubicLineToUPP (&MyATSCubicLineToCallback);

When you no longer need to use your cubic line-to callback, you should use the function DisposeATSCubicLineToUPP to dispose of the universal procedure pointer associated with the callback.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSCubicMoveToProcPtr

Defines a pointer to a cubic move-to function for drawing glyphs that overrides ATSUI’s cubic move-to operation for drawing glyphs.

typedef OSStatus(* ATSCubicMoveToProcPtr)
(
   const Float32Point *pt,
   void *callBackDataPtr
);

If you name your function MyATSCubicMoveToCallback, you would declare it like this:

OSStatus MyATSCubicMoveToCallback (
   const Float32Point *pt,
   void *callBackDataPtr
);

Parameters
pt

A Float32Point data structure that contains the x and y coordinates for the relative point to which the pen should move before it begins drawing this segment of the glyph.

callBackDataPtr

A pointer to any data your callback function needs. You pass this pointer to the function ATSUGlyphGetCurvePaths. Then, ATSUI passes the pointer through to your callback function when your callback function is invoked.

Return Value

A value that indicates the status of your callback function. When a callback function returns any value other than 0, the ATSGlyphGetCubicPaths function stops parsing the path outline and returns the result kATSOutlineParseAbortedErr.

Discussion

You supply a pointer to your customized cubic move-to callback as a parameter to the function ATSUGlyphGetCubicPaths.

To provide a pointer to your cubic move-to callback, you create a universal procedure pointer (UPP) of type ATSCubicMoveToUPP, using the function NewATSCubicMoveToUPP. You can do so with code similar to the following:

ATSCubicMoveToUPP MyCubicMoveToUPP;
MyCubicMoveToUPP = ATSCubicMoveToUPP (&MyATSCubicMoveToCallback);

When you no longer need to use your cubic move-to callback, you should use the function DisposeATSCubicMoveToUPP to dispose of the universal procedure pointer associated with the callback.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSQuadraticClosePathProcPtr

Defines a pointer to a quadratic close-path callback for drawing glyphs that overrides ATSUI’s quadratic close-path operation for drawing glyphs.

typedef OSStatus(* ATSQuadraticClosePathProcPtr)
(
   void *callBackDataPtr
);

If you name your function MyATSQuadraticClosePathCallback, you would declare it like this:

OSStatus MyATSQuadraticClosePathCallback
(
   void *callBackDataPtr
);

Parameters
callBackDataPtr

A pointer to any data your callback function needs. You pass this pointer to the function ATSUGlyphGetQuadraticPaths. Then, ATSUI passes the pointer through to your callback function when your callback function is invoked.

Return Value

A value that indicates the status of your callback function. When a callback function returns any value other than 0, the ATSGlyphGetQuadraticPaths function stops parsing the path outline and returns the result kATSOutlineParseAbortedErr.

Discussion

You supply a pointer to your customized quadratic close-path callback as a parameter to the function ATSUGlyphGetQuadraticPaths.

To provide a pointer to your quadratic close-path callback, you create a universal procedure pointer (UPP) of type ATSQuadraticClosePathUPP, using the function NewATSQuadraticClosePathUPP. You can do so with code similar to the following:

ATSQuadraticClosePathUPP MyQuadraticClosePathUPP;
MyQuadraticClosePathUPP = NewATSQuadraticClosePathUPP  (&MyATSQuadraticClosePathCallback);

When you no longer need to use your quadratic close-path callback, you should use the function DisposeATSQuadraticClosePathUPP to dispose of the universal procedure pointer associated with the callback.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSQuadraticCurveProcPtr

Defines a pointer to a quadratic curve callback for drawing glyphs that overrides ATSUI’s quadratic curve operation for drawing glyphs.

typedef OSStatus(* ATSQuadraticCurveProcPtr)
(
   const Float32Point *pt1,
   const Float32Point *controlPt,
   const Float32Point *pt2,
   void *callBackDataPtr
);

If you name your function MyATSQuadraticCurveCallback, you would declare it like this:

OSStatus MyATSQuadraticCurveCallback (
   const Float32Point *pt1,
   const Float32Point *controlPt,
   const Float32Point *pt2,
   void *callBackDataPtr
);

Parameters
pt1

A Float32Point data structure that contains the x and y coordinates for the relative point that defines the start of the curve (an on-curve point) for this segment of the glyph.

controlPt

A Float32Point data structure that contains the x and y coordinates for the relative point that defines the control point (an off-curve point) for this segment of the glyph.

pt2

A Float32Point data structure that contains the x and y coordinates for the relative point that defines the end of the curve (an on-curve point) for this segment of the glyph.

callBackDataPtr

A pointer to any data your callback function needs. You pass this pointer to the function ATSUGlyphGetQuadraticPaths. Then, ATSUI passes the pointer through to your callback function when your callback function is invoked.

Return Value

A value that indicates the status of your callback function. When a callback function returns any value other than 0, the ATSGlyphGetQuadraticPaths function stops parsing the path outline and returns the result kATSOutlineParseAbortedErr.

Discussion

You supply a pointer to your customized quadratic curve callback as a parameter to the function ATSUGlyphGetQuadraticPaths.

To provide a pointer to your quadratic curve callback, you create a universal procedure pointer (UPP) of type ATSQuadraticCurveUPP, using the function NewATSQuadraticCurveUPP. You can do so with code similar to the following:

ATSQuadraticCurveUPP MyQuadraticCurveUPP;
MyQuadraticCurveUPP = NewATSQuadraticCurveUPP (&MyATSQuadraticCurveCallback);

When you no longer need to use your quadratic curve callback, you should use the function DisposeATSQuadraticCurveUPP to dispose of the universal procedure pointer associated with the callback.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSQuadraticLineProcPtr

Defines a pointer to a quadratic line callback for drawing glyphs that overrides ATSUI’s quadratic line operation for drawing glyphs.

typedef OSStatus(* ATSQuadraticLineProcPtr)
(
   const Float32Point *pt1,
   const Float32Point *pt2,
   void *callBackDataPtr
);

If you name your function MyATSQuadraticLineCallback, you would declare it like this:

OSStatus MyATSQuadraticLineCallback (
   const Float32Point *pt1,
   const Float32Point *pt2,
   void *callBackDataPtr
);

Parameters
pt1

A Float32Point data structure that contains the x and y coordinates for the relative point that defines the start of the line for this segment of the glyph.

pt2

A Float32Point data structure that contains the x and y coordinates for the relative point that defines the end of the line for this segment of the glyph.

callBackDataPtr

A pointer to any data your callback function needs. You pass this pointer to the function ATSUGlyphGetQuadraticPaths. Then, ATSUI passes the pointer through to your callback function when your callback function is invoked.

Return Value

A value that indicates the status of your callback function. When a callback function returns any value other than 0, the ATSGlyphGetQuadraticPaths function stops parsing the path outline and returns the result kATSOutlineParseAbortedErr.

Discussion

You supply a pointer to your customized quadratic line callback as a parameter to the function ATSUGlyphGetQuadraticPaths.

To provide a pointer to your quadratic line callback, you create a universal procedure pointer (UPP) of type ATSQuadraticLineUPP, using the function NewATSQuadraticLineUPP. You can do so with code similar to the following:

ATSQuadraticLineUPP MyQuadraticLineUPP;
MyQuadraticLineUPP = NewATSQuadraticLineUPP (&MyATSQuadraticLineCallback);

When you no longer need to use your quadratic line callback, you should use the function DisposeATSQuadraticLineUPP to dispose of the universal procedure pointer associated with the callback.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSQuadraticNewPathProcPtr

Defines a pointer to a quadratic new-path callback for drawing glyphs that overrides ATSUI’s quadratic new-path operation for drawing glyphs.

typedef OSStatus(* ATSQuadraticNewPathProcPtr)
(
   void *callBackDataPtr
);

If you name your function MyATSQuadraticNewPathCallback, you would declare it like this:

OSStatus MyATSQuadraticNewPathCallback
(
   void *callBackDataPtr
);

Parameters
callBackDataPtr

A pointer to any data your callback function needs. You pass this pointer to the function ATSUGlyphGetQuadraticPaths. Then, ATSUI passes the pointer through to your callback function when your callback function is invoked.

Return Value

A value that indicates the status of your callback function. When a callback function returns any value other than 0, the ATSGlyphGetQuadraticPaths function stops parsing the path outline and returns the result kATSOutlineParseAbortedErr.

Discussion

You supply a pointer to your customized quadratic new-path callback as a parameter to the function ATSUGlyphGetQuadraticPaths.

To provide a pointer to your quadratic new-path callback, you create a universal procedure pointer (UPP) of type ATSQuadraticNewPathUPP, using the function NewATSQuadraticNewPathUPP. You can do so with code similar to the following:

ATSQuadraticNewPathUPP MyQuadraticNewPathUPP;
MyQuadraticNewPathUPP = NewATSQuadraticNewPathUPP  (&MyATSQuadraticNewPathCallback);

When you no longer need to use your quadratic new-path callback, you should use the function DisposeATSQuadraticNewPathUPP to dispose of the universal procedure pointer associated with the callback.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSUDirectLayoutOperationOverrideProcPtr

Defines a pointer to a layout operation callback that overrides an ATSUI layout operation.

typedef CALLBACK_API_C (OSStatus, ATSUDirectLayoutOperationOverrideProcPtr
)
   ATSULayoutOperationSelector iCurrentOperation,
   ATSULineRef iLineRef,
   UInt32 iRefCon,
   void *iOperationCallbackParameterPtr,
   ATSULayoutOperationCallbackStatus *oCallbackStatus
);

If you name your function MyLayoutOperationOverrideCallback, you would declare it like this:

OSStatus MyLayoutOperationOverrideCallback
(
   ATSULayoutOperationSelector iCurrentOperation,
   ATSULineRef iLineRef,
   UInt32 iRefCon,
   void *iOperationCallbackParameterPtr,
   ATSULayoutOperationCallbackStatus *oCallbackStatus
);

Parameters
iCurrentOperation

The operation that triggered the callback. This value is passed to your callback by ATSUI. If you write a callback that handles more than one layout operation, you can use this value to determine which operation you should handle.

iLineRef

An ATSULineRef value that specifies the line of text on which your callback will operation. Your callback gets called for each line of text associated with the text layout object on which you installed the callback.

iRefCon

An unsigned 32-bit integer. This is an optional value. You can use this value to specify any data your application needs, such as user preference data.

iOperationCallbackParameterPtr

A pointer. This is currently unused and should be set to NULL.

oCallbackStatus

A layout callback status value. On output, you must supply a status value to indicate to ATSUI whether or not your callback handled the operation. See “Layout Callback Status Values” for a list of the constants you can supply.

Discussion

ATSUI calls your layout operation override function each time the layout operation you specify is invoked. You associate a universal procedure pointer with a text layout object by treating the callback as a layout attribute. That is, you set up a triple (tag, size, value) to specify the layout operation your callback handles, then you call the function ATSUSetLayoutControls to associate the triple with the text layout object whose layout operation you want to override. The attribute tag you specify is kATSULayoutOperationOverrideTag. The attribute value you specify is an ATSULayoutOperationOverrideSpecifier structure that contains a selector for a layout operation and a pointer to your callback function.

To provide a pointer to your layout operation override callback, you create a universal procedure pointer (UPP) of type ATSUDirectLayoutOperationOverrideUPP, using the function NewATSUDirectLayoutOperationOverrideUPP. You can do so with code similar to the following:

ATSUDirectLayoutOperationOverrideUPP MyLayoutOperationOverrideUPP;
MyLayoutOperationOverrideUPP = NewATSUDirectLayoutOperationOverrideUPP
                                (&MyLayoutOperationOverrideCallback);

When your layout operation is completed, you should use the function DisposeATSUDirectLayoutOperationOverrideUPP to dispose of the universal procedure pointer associated with your layout operation override function. However, if you plan to use the same layout operation override function in subsequent layout operations, you can reuse the same UPP, rather than dispose of it and later create a new UPP.

You are limited to the ATSUI functions you can call from within your callback. You can call only those functions that have do not trigger ATSUI to perform the layout operation again. Otherwise, you run the risk of causing infinite recursion. Most functions that use “create”, “get”, or “copy” semantics are safe to use within your callback. If you call one of the restricted functions, the function returns immediately with the error kATSUInvalidCallInsideCallbackErr.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSLayoutTypes.h

RedrawBackgroundProcPtr

Defines a pointer to a redraw-background callback that overrides ATSUI’s highlighting method for drawing backgrounds.

typedef Boolean (* RedrawBackgroundProcPtr)
(
   ATSUTextLayout iLayout,
   UniCharArrayOffset iTextOffset,
   UniCharCount iTextLength,
   ATSTrapezoid *iUnhighlightArea,
   ItemCount iTrapezoidCount
);

If you name your function MyRedrawBackgroundCallback, you would declare it like this:

Boolean MyRedrawBackgroundCallback (
   ATSUTextLayout iLayout,
   UniCharArrayOffset iTextOffset,
   UniCharCount iTextLength,
   ATSTrapezoid *iUnhighlightArea,
   ItemCount iTrapezoidCount
);

Parameters
iLayout

An ATSUTextLayout value that specifies the text layout object on which your callback will operate.

iTextOffset

The offset of the text to be highlighted.

iTextLength

The length of the text to be highlighted.

iUnhighlightArea

An array of ATSTrapezoid data structures that describe the boundaries of the highlight area. The boundary values in this array are always specified in QuickDraw coordinates.

iTrapezoidCount

The number of ATSTrapezoid data structures in the iUnhighlightArea array.

Return Value

A Boolean value that indicates whether ATSUI should redraw the text. If your function redraws the text, your callback should return false, otherwise you callback should return true to have ATSUI redraw any text that needs to be redrawn.

Discussion

ATSUI calls your customized redraw-background callback when it needs to redraw complex backgrounds (and optionally the text as well). For ATSUI to use your callback, you must first call the ATSUSetHighlightingMethod function with the iMethod parameter set to kRedrawHighlighting. You must also pass an ATSUUnhighlightData data structure as a parameter to the ATSUSetHighlightingMethod function. This structure should contain a pointer to your redraw background callback.

To provide a pointer to your redraw background callback, you create a universal procedure pointer (UPP) of type RedrawBackgroundUPP, using the function NewRedrawBackgroundUPP. You can do so with code similar to the following:

RedrawBackgroundUPP gMyRedrawBackgroundUPP;
gMyRedrawBackgroundUPP = NewRedrawBackgroundUPP
                            (&MyRedrawBackgroundCallback);

For ATSUI to invoke your callback function, you must also pass the RedrawBackgroundUPP in the unhighlightData.backgroundUPP field of the iUnhighlightData parameter for the function ATSUSetHighlightingMethod. When finished, you must call the function DisposeRedrawBackgroundUPP to dispose of the RedrawBackgroundUPP.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

Data Types

Core Data Types

ATSUAttributeInfo

Contains an attribute tag and the size of the attribute.

struct ATSUAttributeInfo {
   ATSUAttributeTag fTag;
   ByteCount fValueSize;
};
Fields
fTag

Identifies a particular style run or text attribute value. For a description of the Apple-defined style run and text layout attribute tag constants, see “Attribute Tags.”

fValueSize

The size (in bytes) of the style run or text layout attribute value.

Discussion

Several ATSUI functions pass back an array of structures of this type. The function ATSUGetAllAttributes passes back an array of ATSUAttributeInfo structures to represent the data sizes of all previously set style run attribute values and the corresponding style run attribute tags that identify those style run attribute values. The function ATSUGetAllLayoutControls passes back an array of ATSUAttributeInfo structures to represent the data sizes of all previously set text layout attribute values for an entire text layout object and the corresponding text layout attribute tags that identify those text layout attribute values. The function ATSUGetAllLineControls passes back an array of ATSUAttributeInfo structures to represent the data sizes of all previously set text layout attribute values for a single line in a text layout object and the corresponding text layout attribute tags that identify those text layout attribute values.

ATSLayoutRecord

Contains basic layout information for a single glyph.

struct ATSLayoutRecord {
   ATSGlyphRef         glyphID;
   ATSGlyphInfoFlags   flags;
   ByteCount           originalOffset;
   Fixed               realPos;
};
typedef struct ATSLayoutRecord ATSLayoutRecord;
Fields
glyphID

A reference to a glyph ID.

flags

A flag that specifies the glyph’s properties. See “Glyph Property Flags” for the constants you can use.

originalOffset

The byte offset of the character with which this glyph is associated.

realPos

A Fixed value that specifies the real position of the glyph. This is the x-coordinate of the glyph.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSLayoutTypes.h

ATSUStyleSettingRef

A reference to an opaque style setting object.

typedef struct LLCStyleInfo*         ATSUStyleSettingRef;
Discussion

You can obtain a style setting reference by calling the functions ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout with the selector set to kATSUDirectDataStyleSettingATSUStyleSettingRefArray. You can move a style setting reference from one text layout object to another by calling the function ATSUDirectAddStyleSettingRef.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeDirectAccess.h

ATSUAttributeValuePtr

Represents a pointer to a style run or text layout attribute value of unknown size.

typedef void* ATSUAttributeValuePtr;
Discussion

Each attribute value pointed to by ATSUAttributeValuePtr is identified by an attribute tag and the size (in bytes) of the attribute value.

You pass the ATSUAttributeValuePtr type to functions that set or clear attribute values in style and text layout objects. The ATSUAttributeValuePtr type is passed back by functions that query style and text layout objects for their attribute values. You must dereference this pointer and cast it to the appropriate data type to obtain the actual attribute value.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ConstATSUAttributeValuePtr

A pointer to a constant attribute value pointer (ATSUAttributeValuePtr).

typedef const void* ConstATSUAttributeValuePtr;
Discussion

An ATSUAttributeValuePtr data type provides generic access to storage of attribute values which vary in size.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ATSURGBAlphaColor

Contains color information that includes alpha channel information.

struct ATSURGBAlphaColor {
   float               red;
   float               green;
   float               blue;
   float               alpha;
};
typedef struct ATSURGBAlphaColor        ATSURGBAlphaColor;
Fields
red

A value that specifies the red component of the background color.

green

A value that specifies the green component of the background color.

blue

A value that specifies the blue component of the background color.

alpha

A value that specifies thee alpha channel component of the background color.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeTypes.h

ATSUBackgroundColor

Redefines the ATSUBackgroundColor data type to be an ATSURGBAlphaColor data type.

typedef ATSURGBAlphaColor ATSUBackgroundColor;
Discussion

Prior to Mac OS X version 10.2, the ATSUBackgroundColor data type did not include an alpha channel.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ATSUBackgroundData

A union that contains a background color or a universal procedure pointer to a callback that redraws the background.

union ATSUBackgroundData {
   ATSUBackgroundColor backgroundColor;
   RedrawBackgroundUPP backgroundUPP;
};
Fields
backgroundColor

A structure that specifies the background color.

backgroundUPP

A universal procedure pointer to a callback function for redrawing complex backgrounds. See RedrawBackgroundUPP for more information.

ATSUCaret

Contains the coordinates needed to draw a caret.

struct ATSUCaret {
   Fixed fX;
   Fixed fY;
   Fixed fDeltaX;
   Fixed fDeltaY;
};
Fields
fX

Represents the x-coordinate of the caret’s starting pen position relative to the position of the origin of the line in the current graphics port in which the hit occurred.

fY

Represents the y-coordinate of the caret’s starting pen position relative to the position of the origin of the line in the current graphics port in which the hit occurred.

fDeltaX

Represents the x-coordinate of the caret’s ending pen position relative to the position of the origin of the line in the current graphics port in which the hit occurred. This position takes into account line rotation. You do not have to rotate it yourself.

fDeltaY

Represents the y-coordinate of the caret’s ending pen position relative to the position of the origin of the line in the current graphics port in which the hit occurred. This position takes into account line rotation. You do not have to rotate it yourself.

Discussion

The function ATSUOffsetToPosition passes back two structures of type ATSUCaret to represent the caret position relative to the origin of the line in the current graphics port, corresponding to a specified edge offset. If the edge offset is at a line boundary, the structure passed back in oMainCaret contains the starting and ending pen locations of the high caret, while oSecondCaret contains the low caret. If the offset is not at a line boundary, both parameters contain the same structure. This structure contains the starting and ending pen locations of the main caret.

You can use the information in this structure to draw a caret by calling the MoveTo and LineTo functions. For example.

MoveTo (fX, fY);
LineTo (fDeltaX, fDeltaY);

ATSUFontFeatureType

Represents the attributes of a particular font feature.

typedef UInt16 ATSUFontFeatureType;
Discussion

Font features are typographic and layout capabilities that you can select or deselect and which control many aspects of glyph selection, ordering, and positioning. Font features include fundamental controls such as whether your text is drawn with contextual forms, as well as details of appearance such as whether you want alternate forms of glyphs to be used at the beginning of a word. To a large extent, how text looks when it is laid out is a function of the number and kinds of font features you choose.

Font vendors create tables that implement the specific set of features which are included in a font by the font designer. Note that only a few feature types and selectors may be available with a given font. If you select features that are not available in a font, you won’t see a change in the glyph’s appearance. To determine the available features of a font, you can call the functions ATSUGetFontFeatureTypes and ATSUGetFontFeatureSelectors.

For a complete discussion of font features, the selectors you use to access them, and illustrations of the features, see Inside Mac OS X: Rendering Unicode Text With ATSUI.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ATSUFontFeatureSelector

Represents the state (on or off) of a particular feature type.

typedef UInt16 ATSUFontFeatureSelector;
Discussion

You pass the ATSUFontFeatureSelector type to functions that set or clear font feature selectors in a style run. The ATSUFontFeatureSelector type is passed back by functions that obtain font feature selectors in a style run. For a complete discussion of font feature selectors, see Inside Mac OS X: Rendering Unicode Text With ATSUI.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ATSUFontVariationAxis

Represents a stylistic attribute and the range of values that the font can use to express this attribute.

typedef FourCharCode ATSUFontVariationAxis;
Discussion

Font variations allow your application to produce a range of type styles algorithmically. You can obtain a a variation axis and its maximum, minimum, and default values for a font by calling the function ATSUGetIndFontVariation. For a complete discussion of font variations, see Inside Mac OS X: Rendering Unicode Text With ATSUI.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ATSUFontVariationValue

Represents the range of values that the font can use for a particular font variation.

typedef Fixed ATSUFontVariationValue;
Discussion

You pass the ATSUFontVariationValue type to functions that set and clear font variations in a style run. The ATSUFontVariationValue type is passed back by functions that query a style run for font variations.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ATSUFontFallbacks

An opaque structure that contains a font fallback list and font fallback cache information.

typedef struct OpaqueATSUFontFallbacks *ATSUFontFallbacks;
Availability
  • Available in OS X v10.1 and later.
Declared In
ATSUnicodeTypes.h

ATSUFontID

Represents the unique identifier of a font to the font management system in ATSUI.

typedef FMFont ATSUFontID;
Discussion

You pass the ATSUFontID type with functions that set and obtain font information. The ATSUFontID type is passed back by functions that count fonts installed on a user’s system. The ATSUFontID type can be also used to set and get the font in a style run; see “Attribute Tags.”

An ATSUFontID specifies a font family and instance. This value is not guaranteed to remain constant if the system is restarted. You should obtain the font’s unique name and store that information in documents for which you need persistent font information.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ATSUGlyphInfo

Contains information about a glyph.

struct ATSUGlyphInfo {
   GlyphID glyphID;
   UInt16 reserved;
   UInt32 layoutFlags;
   UniCharArrayOffset charIndex;
   ATSUStyle style;
   Float32 deltaY;
   Float32 idealX;
   SInt16 screenX;
   SInt16 caretX;
};
Fields
glyphID

A glyph ID. This is unique to the associated font.

reserved

Reserved for Apple’s use.

layoutFlags

The layout flags associated with this glyph.

charIndex

The index of the character in the Unicode character stream from which this glyph is derived.

style

An ATSUStyle value that specifies the style object associated with this glyph.

deltaY

The cross-stream shift value for this glyph.

idealX

The ideal with-stream offset from the origin of this layout.

screenX

The device-adjusted with-stream offset from the origin of this layout.

caretX

The position in device coordinates where a trailing caret for this glyph intersects the baseline.

Discussion

This data structure is used by ATSUI to return the glyph information associated with one glyph.

ATSUGlyphInfoArray

Contains text layout information for an array of glyphs.

struct ATSUGlyphInfoArray {
   ATSUTextLayout layout;
   ItemCount numGlyphs;
   ATSUGlyphInfo glyphs[1];
};
Fields
layout

An ATSUTextLayout value that specifies the text layout object associated with the glyphs.

numGlyphs

The number of glyphs associated with the text layout object.

glyphs

An array of glyph information structures.

Discussion

This data structure is used by ATSUI to return the glyph information associated with the glyphs in a text layout object.

ATSUGlyphSelector

Contains information that directs ATSUI to use a specific glyph instead of the one ATSUI normally derives.

struct ATSUGlyphSelector {
   GlyphCollection     collection;
   GlyphID             glyphID;
};
typedef struct ATSUGlyphSelector        ATSUGlyphSelector;
Fields
collection

A value that represents the collection of glyphs you want ATSUI to use. See “Glyph Collection Types ” for possible values you can supply.

glyphID

A glyph ID value or a collection ID (CID) value. Supply a glyph ID when the collection type is kGlyphCollectionGID. Otherwise supply a CID.

Discussion

The ATSUGlyphSelector structure along with the attribute tag kATSUGlyphSelectorTag allow display of glyphs that do not have an explicit Unicode character. You can use the kATSUGlyphSelectorTag to access characters in fonts that otherwise would not be accessible. You can choose the variant glyph by font-specific glyph ID or CID. For more information on CID conventions, see go to http://www.adobe.com. You can get the variant glyph information from an input method through the Text Services Manager using the Carbon event key kEventParamTextInputGlyphInfoArray.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeTypes.h

ATSJustPriorityWidthDeltaOverrides

Contains justification width delta override structures, one for each priority-level override.

typedef ATSJustWidthDeltaEntryOverride ATSJustPriorityWidthDeltaOverrides[4];
Discussion

For more information see ATSJustWidthDeltaEntryOverride.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSLayoutTypes.h

ATSJustWidthDeltaEntryOverride

Contains values that specify the amount of space that can be added to or removed from the right and left sides of each of the glyphs of a given justification priority.

struct ATSJustWidthDeltaEntryOverride {
   Fixed beforeGrowLimit;
   Fixed beforeShrinkLimit;
   Fixed afterGrowLimit;
   Fixed afterShrinkLimit;
   JustificationFlags growFlags;
   JustificationFlags shrinkFlags;
};
typedef struct ATSJustWidthDeltaEntryOverride ATSJustWidthDeltaEntryOverride;
Fields
beforeGrowLimit

The proportion by which a glyph can expand on the left side (top side for vertical text). For example, a value of 0.2 means that a 24-point glyph can have by no more than 4.8 points (0.2 x 24 = 4.8) of extra space added on the left side (top side for vertical text).

beforeShrinkLimit

The proportion by which a glyph can shrink on the left side (top side for vertical text). If specified, this value should be negative.

afterGrowLimit

The proportion by which a glyph can expand on the right side (bottom side for vertical text).

afterShrinkLimit

The proportion by which a glyph can shrink on the right side (bottom side for vertical text). If specified, this value should be negative.

growFlags

Mask constants that indicate whether ATSUI should apply the limits defined in the beforeGrowLimit and afterGrowLimit fields. See “Justification Override Mask Constants” in the Font Manager for a description of possible values. These mask constants also control whether unlimited gap absorption should be applied to the priority of glyphs specified in the given width delta override structure. You can use these mask constants to selectively override the grow case only, while retaining default behavior for other cases.

shrinkFlags

Mask constants that indicate whether ATSUI should apply the limits defined in the beforeShrinkLimit and afterShrinkLimit fields. See “Justification Override Mask Constants” in the Font Manager for a description of possible values. These mask constants also control whether unlimited gap absorption should be applied to the priority of glyphs specified in the given width delta override structure. You can use these mask constants to selectively override the shrink case only, while retaining default behavior for other cases.

Discussion

The JustWidthDeltaEntryOverride structure specifies proportions for justification growth and shrinkage, both on the left and the right sides. The growth and shrinkage values override the font-specified widths, such as those specified by the font for kashidas.

It also contains justification flags. The ATSJustWidthDeltaEntryOverride data type can be used to set and get justification behavior and priority override weighting; see “Attribute Tags.”

If you need to access other 'just' table constants and structures from the 'sfnt' resource, see the header file SFNTLayoutTypes.h.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSLayoutTypes.h

ATSULayoutOperationOverrideSpecifier

Contains an layout operation selector and a pointer to a layout operation override callback.

struct ATSULayoutOperationOverrideSpecifier {
   ATSULayoutOperationSelector  operationSelector;
   ATSUDirectLayoutOperationOverrideUPP  overrideUPP;
};
typedef struct ATSULayoutOperationOverrideSpecifier ATSULayoutOperationOverrideSpecifier;
Fields
operationSelector

A layout operation selector that specifies the operation for which the callback should be invoked. See “Layout Operation Selectors” for the selectors you can specify.

overrideUPP

A universal procedure pointer to a layout operation override callback.

Discussion

You can pass this structure as an attribute value for the layout attribute tag kATSULayoutOperationOverrideTag.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSLayoutTypes.h

ATSULineRef

Represents a reference to a structure that specifies a line of text.

typedef struct ATSGlyphVector *ATSULineRef;
Discussion

You get an ATSUI line reference from ATSUI when your layout operation override callback is invoked. The line reference refers to the line that ATSUI is in the process of laying out.

From within your callback, you pass an ATSUI line reference to the function ATSUDirectGetLayoutDataArrayPtrFromLineRef to obtain layout data for that line. The only way you can obtain an ATSUI line reference is from inside your layout operation override callback. An ATSUI line reference is not valid is outside of the callback.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSLayoutTypes.h

ATSUStyle

Represents a reference to an opaque structure that contains information about a style object.

typedef struct OpaqueATSUStyle *ATSUStyle;
Discussion

A style object is an opaque structure encapsulating the following character-level style settings

  • style attributes: including font ID, font size, font color, kerning control, optical alignment, verticality, and with-stream (left-right) and cross-stream (up-down) shifting (as for superscripts and subscripts)

  • font features: including ligatures, swashes, and alternate glyph forms

  • font variations: such as continually varying font weight, width, or slant

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ATSUStyleRunInfo

Contains information for a style run.

struct ATSUStyleRunInfo {
   UniCharCount        runLength;
   ItemCount           styleObjectIndex;
};
typedef struct ATSUStyleRunInfo         ATSUStyleRunInfo;
Fields
runLength

The length of the style run.

styleObjectIndex

An index into an array of unique style objects.

Discussion

This structure is used by the function ATSUUnflattenStyleRunsFromStream to return style run information.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSUTab

Contains tab settings.

struct ATSUTab {
   ATSUTextMeasurement  tabPosition;
   ATSUTabType                        tabType;
};
typedef struct ATSUTab ATSUTab;
Fields
tabPosition

Specifies a tab position.

tabType

Specifies a type of tab stop. See “Tab Positioning Options.”

Discussion

You can set tabs for a text layout object by calling the function ATSUSetTabArray. You can obtain tab settings by calling the function ATSUGetTabArray.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeTypes.h

ATSUTextLayout

Represents a reference to an opaque text layout structure that contains information about a text layout.

typedef struct OpaqueATSUTextLayout* ATSUTextLayout;
Discussion

The basic building block upon which ATSUI operates is a text layout object (ATSUTextLayout). A text layout object ties one or more paragraphs of text together with style attributes that may apply to characters, lines, or the entire layout. The text layout object itself contains information about line and layout attributes, including justification, rotation, direction, and others. Character style information is contained in a style object, which is only associated with, not contained by, a text layout object. For more information on text layout objects, see Inside Mac OS X: Rendering Unicode Text With ATSUI.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ATSUTextMeasurement

Represents measurements needed by ATSUI to lay out text, such as outline metrics and line width, ascent, descent.

typedef Fixed ATSUTextMeasurement;
Discussion

The ATSUTextMeasurement type is defined as a Fixed value, with a limit of 32K. You must ensure that your measurements are converted to Fixed values before passing them to ATSUI functions that use this type.

ATSUI uses fractional Fixed values instead of short values used in QuickDraw Text. Fractional Fixed values provide exact outline metrics and line specifications such as line width, ascent, descent, and so on.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

ATSTrapezoid

Contains the coordinates of the typographic bounding trapezoid for the final layout of a line a text.

struct ATSTrapezoid {
   FixedPoint upperLeft;
   FixedPoint upperRight;
   FixedPoint lowerRight;
   FixedPoint lowerLeft;
};
Fields
upperLeft

A structure of type FixedPoint that contains the upper left coordinates (assuming a horizontal line of text) of the typographic glyph bounds.

upperRight

A structure of type FixedPoint that contains the upper right coordinates (assuming a horizontal line of text) of the typographic glyph bounds.

lowerRight

A structure of type FixedPoint that identifies the lower right coordinates (assuming a horizontal line of text) of the typographic glyph bounds.

lowerLeft

A structure of type FixedPoint that identifies the lower left coordinates (assuming a horizontal line of text) of the typographic glyph bounds.

Discussion

The dimensions of the resulting trapezoid are relative to the coordinates specified in the iTextBasePointX and iTextBasePointY parameters. The width of the glyph bounds is determined based on the value passed in the iTypeOfBounds parameter.

The function ATSUGetGlyphBounds passes back an array of structures of type ATSTrapezoid to specify the enclosing trapezoid(s) of a final laid-out line of text. If the range of text spans directional boundaries, ATSUGetGlyphBounds produces multiple trapezoids defining these regions.

Version Notes

In ATSUI 1.1, the function ATSUGetGlyphBounds can pass back a maximum of 31 bounding trapezoids. In ATSUI 1.2, ATSUGetGlyphBounds can pass back as many as 127 bounding trapezoids.

ATSUUnhighlightData

Contains data needed to redraw the background.

struct ATSUUnhighlightData {
   ATSUBackgroundDataType dataType;
   ATSUBackgroundData unhighlightData;
};
Fields
dataType

The data type of the background—a color or a callback.

unhighlightData

A background color or a universal procedure pointer to a callback that redraws the background.

USTL Data Structure Data Types

The data types in this section define the 'ustl' data structure, which is the data structure used by ATSUI to contain flattened data. The 'ustl' data structure has four blocks. The Block 1 structure defines is a header for the entire 'ustl' data structure. Block 2 structures define flattened text layout data. (Note that Block 2 structures are not currently used by the functions ATSUFlattenStyleRunsToStream and ATSUUnflattenStyleRunsFromStream.) Block 3 structures define flattened style run data. Block 4 structures define flattened style data.

The 'ustl' data structure can accommodate any ATSUI text layout and style run data associated with a document. That is, the 'ustl' data structure can contain data for multiple text layout objects, multiple style runs, and multiple style objects. Within each block (text layout, style run, and style) you must specify the number structures in that block.

ATSFlatDataMainHeaderBlock

Contains the 'ustl' data structure version and size and provides offsets to the text layout, style run, and style list data blocks.

struct ATSFlatDataMainHeaderBlock {
   UInt32              version;
   ByteCount           sizeOfDataBlock;
   ByteCount           offsetToTextLayouts;
   ByteCount           offsetToStyleRuns;
   ByteCount           offsetToStyleList;
};
typedef struct ATSFlatDataMainHeaderBlock ATSFlatDataMainHeaderBlock;
Fields
version

The version number of the 'ustl' data structure. You must make sure this number is the first item in the data block, otherwise the data may not be readable by code written to parse earlier versions of 'ustl' data.

sizeOfDataBlock

The total size of the data in bytes, including the four bytes needed for the version number.

offsetToTextlayouts

The offset from the beginning of the data block to the flattened text layout data. You can set this value to 0 if there is no text layout data. This value specifies the offset to the ATSFlatDataTextLayoutDataHeader structure.

offsetToStyleRuns

The offset from the beginning of the data to the flattened style run data. You can set this value to 0 if there is no flattened style run data. This value specifies the offset to the ATSFlatDataStyleRunDataHeader structure.

offsetToStyleList

The offset to the flattened style list data. You can set this value to 0 if there is no flattened style list data. This value specifies the offset to the ATSFlatDataStyleListHeader structure.

Discussion

The structure ATSFlatDataMainHeaderBlock is Block 1 of the 'ustl' data structure. This structure contains information about the rest of the 'ustl' data structure and provides offsets to each of the other three data blocks. Figure 1 illustrates the main header structure.

Figure 1  The main header for the ustl data structure
The main header for the ustl data structure

Per the 'ustl' specification, all data blocks with the 'ustl' data structure must maintain 4-byte alignment. For such items as font names, which have a variable width, you must add padding bytes to ensure the 4-byte alignment is always maintained.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataTextLayoutDataHeader

Contains size, length, and offset information for a text layout data block.

struct ATSFlatDataTextLayoutDataHeader {
   ByteCount           sizeOfLayoutData;
   ByteCount           textLayoutLength;
   ByteCount           offsetToLayoutControls;
   ByteCount           offsetToLineInfo;
};
typedef struct ATSFlatDataTextLayoutDataHeader ATSFlatDataTextLayoutDataHeader;
Fields
sizeOfLayoutData

The size of the flattened text layout data. This value must include any bytes that have been added to maintain the required 4-byte alignment.

textLayoutLength

The number of characters to which the flattened text layout data applies.

offsetLayoutControls

The offset to the flattened layout control data. This offset is relative to the start of the text layout data block, and specifies the offset to the ATSFlatDataLayoutControlsDataHeader structure. The offset can be set to zero if there are no layout controls.

offsetToLineLength

The offset to the flattened line info data. This offset is relative to the start of the text layout data block, and specifies the offset to the ATSFlatDataLineInfoHeader structure. The offset can be set to zero if there is no line info in this layout.

Discussion

The ATSFlatDataTextLayoutDataHeader structure is a block 2 data structure and it is the main header for text layout data. If you have text layout data to flatten or unflatten, you must have one of these structures. for each text layout object whose data you want to flatten.

Note that the ATSFlatDataTextLayoutDataHeader data structure(s) must be preceded by an ItemCount value that specifies the number of ATSFlatDataTextLayoutDataHeader data structures included in the flattened data. Although the ItemCount value is not part of any 'ustl' data structure, you need to include this 4-byte value when you flatten your text layout data so that you can successfully parse the flattened data at a later time.

The offsetToTextLayouts field in the ATSFlatDataMainHeaderBlock structure specifies the offset to the structure ATSFlatDataTextLayoutDataHeader.

Figure 2 depicts the flattened text layout data. At the top of the figure is the information contained in the data header (ATSFlatDataTextLayoutDataHeader). Following the header are layout controls data (see ATSFlatDataLayoutControlsDataHeader) and line length data (see ATSFlatDataLineInfoHeader and ATSFlatDataLineInfoData).

Figure 2  Flattened text layout data
Flattened text layout data

If the offsetToLayoutControls value is not zero, there must be a ATSFlatDataLayoutControlsDataHeader structure that contains a count of the number of layout controls and an array of layout control attribute data.

If the offsetToLineInfo is not zero, then following the flattened layout controls data you must have an ATSFlatDataLineInfoHeader structure.

This and other Block 2 structures are not currently used by the functions ATSUFlattenStyleRunsToStream and ATSUUnflattenStyleRunsFromStream.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataLayoutControlsDataHeader

Contains the number of flattened layout controls and an array of layout control attribute data.

struct ATSFlatDataLayoutControlsDataHeader {
   ItemCount           numberOfLayoutControls;
   ATSUAttributeInfo   controlArray[1];
};typedef struct ATSFlatDataLayoutControlsDataHeader ATSFlatDataLayoutControlsDataHeader;
Fields
numberOfLayoutControls

The number of flattened layout controls. There should be at least one layout control that specifies the line direction of the layout.

controlArray[1]

The first entry in an array of ATSUI attribute information. There should be numberOfLayoutControls entries in this array. If necessary, each ATSUI attribute info structure in the array should be followed by padding bytes to maintain the required 4-byte alignment. The value in the fValueSize field of each ATSUAttributeInfo structure must specify the size of the attribute value, and must not reflect any padding bytes you added.

Discussion

The ATSFlatDataLayoutControlsDataHeader structure is the header for the flattened layout controls structure. The offsetToLayoutControls field in the ATSFlatDataTextLayoutDataHeader structure specifies the offset to the structure ATSFlatDataLayoutControlsDataHeader. If there are no layout controls, you do not need the ATSFlatDataLayoutControlsDataHeader structure.

This and other Block 2 structures are not currently used by the functions ATSUFlattenStyleRunsToStream and ATSUUnflattenStyleRunsFromStream.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataLineInfoHeader

Contains the number of lines and an array of line information data.

struct ATSFlatDataLineInfoHeader {
   ItemCount           numberOfLines;
   ATSFlatDataLineInfoData  lineInfoArray[1];
};
typedef struct ATSFlatDataLineInfoHeader ATSFlatDataLineInfoHeader;
Fields
numberOfLines

The number of flattened line info structures that are stored in this block. This value should be greater than zero and equal to the number of soft line breaks in the layout plus one.

lineInfoArray[1]

The first entry in a array of ATSFlatDataLineInfoData structures. There should be numberOfLines entries in this array.

Discussion

The ATSFlatDataLineInfoHeader structure is the main data header for the flattened line info data. The value offsetToLineInfo in the ATSFlatDataTextLayoutDataHeader specifies the offset to the ATSFlatDataLineInfoHeader structure.

This and other Block 2 structures are not currently used by the functions ATSUFlattenStyleRunsToStream and ATSUUnflattenStyleRunsFromStream.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataLineInfoData

Contains a line length and the number of line controls for a line of flattened text.

struct ATSFlatDataLineInfoData {
   UniCharCount        lineLength;
   ItemCount           numberOfLineControls;
};
typedef struct ATSFlatDataLineInfoData  ATSFlatDataLineInfoData;
Fields
lineLength

The number of UniChars characters in the line.

numberOfLineControls

The number of line controls applied to the line. You can set this value to zero if there are no line controls applied to this line.

Discussion

If the numberOfLineControls is not zero, then you must supply an array of ATSUAttributeInfo structures that contains numberOfLineControls elements.

This and other Block 2 structures are not currently used by the functions ATSUFlattenStyleRunsToStream and ATSUUnflattenStyleRunsFromStream.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataStyleRunDataHeader

Contains the number of style runs and style run information for the style run data block.

struct ATSFlatDataStyleRunDataHeader {
   ItemCount           numberOfStyleRuns;
   ATSUStyleRunInfo    styleRunArray[1];
};
typedef struct ATSFlatDataStyleRunDataHeader ATSFlatDataStyleRunDataHeader;
Fields
numberOfStyleRuns

The number of style run data structures stored in this block.

styleRunArray[1]

The first entry in a array of ATSUStyleRunInfo structures. There should be numberOfStyleRuns entries in this array.

Discussion

The ATSFlatDataStyleRunDataHeader structure precedes style run data structures. The offsetToStyleRuns field in the ATSFlatDataMainHeaderBlock specifies the offset to the structure ATSFlatDataStyleRunDataHeader.

Figure 3  Flattened style run data
Flattened style run data

This is a Block 3 structure. Block 3 structures are used by ATSUI style run flattening and parsing functions, ATSUFlattenStyleRunsToStream and ATSUUnflattenStyleRunsFromStream, to represent flattened style run information. These structures work together with Block 4 structures.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataStyleListHeader

Contains the number of styles and the first item in the style list style data header.

struct ATSFlatDataStyleListHeader {
   ItemCount           numberOfStyles;
   ATSFlatDataStyleListStyleDataHeader  styleDataArray[1];
};
typedef struct ATSFlatDataStyleListHeader ATSFlatDataStyleListHeader;
Fields
numberOfStyles

The number of flattened style objects in this block.

styleDataArray[1]

The first item in an array of ATSFlatDataStyleListStyleDataHeader structures. There should be numberOfStyles entries in this array. Note that the data stored in these structures can be of variable sizes.

Discussion

The ATSFlatDataStyleListHeader structure is the main header for Block 4. The offsetToStyleList field in the ATSFlatDataMainHeaderBlock specifies the offset to the structure ATSFlatDataStyleListHeader.

Figure 4  Flattened style list data
Flattened style list data
Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataStyleListStyleDataHeader

Contains size information and the number of attributes, features, and variations for the style list data block.

struct ATSFlatDataStyleListStyleDataHeader {
   ByteCount           sizeOfStyleInfo;
   ItemCount           numberOfSetAttributes;
   ItemCount           numberOfSetFeatures;
   ItemCount           numberOfSetVariations;
};
typedef struct ATSFlatDataStyleListStyleDataHeader ATSFlatDataStyleListStyleDataHeader;
Fields
sizeOfStyleInfo

The size of the flattened style object. This value should include the four bytes for this field (sizeOfStyleInfo) and any padding bytes you add to end of the structure to maintain the required 4-byte alignment.

numberOfSetAttributes

The number of attributes in the flattened style object. You should have at least one attribute for the font data, although you can set this value to 0 if you do not want to specify font data.

numberOfSetFeatures

The number of font features in the flattened style object. You can set this value to 0 if there are no font features in the style object.

numberOfSetVariations

The number of font variations in the flattened style object. You can set this value to 0 if there are no font variations in the style object.

Discussion

The ATSFlatDataStyleListStyleDataHeader structure forms the beginning of an individually flattened ATSUStyle object. This structure precedes the following data:

  1. If the value numberOfSetAttributes is non-zero, there must be an array of ATSUAttributeInfo structures immediately following the ATSFlatDataStyleListStyleDataHeader structure to store the style attributes. This is a variable-size array. The number of ATSUAttributeInfo structures must be equal to the value numberOfSetAttributes, one structure for each attribute.

    If the value numberOfSetAttributes is zero, you do not need an array of ATSUAttributeInfo structures.

  2. If the value numberOfSetFeatures is non-zero, there must be an array of ATSFlatDataStyleListFeatureData structures. These structures must appear immediately following the ATSUAttributeInfo array above (if there is such an array). The number of ATSFlatDataStyleListFeatureData structures must be equal to the value numberOfSetFeatures, one structure for each feature.

    If the value numberOfSetFeatures is zero, you do not need an array of ATSFlatDataStyleListFeatureData structures.

  3. If the value numberOfSetVariations is non-zero, there must be an array of ATSFlatDataStyleListVariationData structures immediately following the ATSFlatDataStyleListFeatureData array (if there is such an array). The number of ATSFlatDataStyleListVariationData structures must be equal to the value numberOfSetVariations, one structure for each variation.

This is a Block 4 structure. Block 4 structures store flattened ATSUStyle objects and are currently used by the ATSUI style run flattening and parsing functions, ATSUFlattenStyleRunsToStream and ATSUUnflattenStyleRunsFromStream.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataStyleListFeatureData

Contains flattened font feature data.

struct ATSFlatDataStyleListFeatureData {
   ATSUFontFeatureType  theFeatureType;
   ATSUFontFeatureSelector  theFeatureSelector;
};
typedef struct ATSFlatDataStyleListFeatureData ATSFlatDataStyleListFeatureData;
Fields
theFeatureType

A font feature type.

theFeatureSelector

A font feature selector.

Discussion

This is a Block 4 structure. The structure ATSFlatDataStyleListFeatureData stores flattened font feature data. If the value numberOfSetFeatures in the ATSFlatDataStyleListStyleDataHeader structure is non-zero, an array of these structure must follow the array of font data attributes (if such an array exists) if the numberOfSetFeatures is non-zero. The number of ATSFlatDataStyleListFeatureData structures must be equal to the value numberOfSetFeatures.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataStyleListVariationData

Contains flattened font variation axis data.

struct ATSFlatDataStyleListVariationData {
   ATSUFontVariationAxis  theVariationAxis;
   ATSUFontVariationValue  theVariationValue;
};
typedef struct ATSFlatDataStyleListVariationData ATSFlatDataStyleListVariationData;
Fields
theVariationAxis

A font variation axis.

theVariationValue

A font variation value.

Discussion

This is a Block 4 structure. The structure ATSFlatDataStyleListVariationData stores flattened font variation data. If the value numberOfSetVariations in the ATSFlatDataStyleListStyleDataHeader structure is non-zero, an array of these structure must follow the array of font features (if such an array exists) if the numberOfSetVariations is non-zero. The number of ATSFlatDataStyleListVariationData structures must be equal to the value numberOfSetVariations.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataFontNameDataHeader

Contains font name information.

struct ATSFlatDataFontNameDataHeader {
   ATSFlatDataFontSpeciferType  nameSpecifierType;
   ByteCount           nameSpecifierSize;
};
typedef struct ATSFlatDataFontNameDataHeader ATSFlatDataFontNameDataHeader;
Fields
nameSpecifierType

A font specifier for the type of the font name data you plan to supply. See “Flattened Data Font Type Selectors” for a list of the font specifiers you can supply. The font name data must follow the ATSFlatDataFontNameDataHeader structure.

nameSpecifierSize

The size of the flattened font name data. This value must not include any padding bytes that may be necessary to achieve the required 4-byte alignment, unless the padding bytes are specified as part of structure, such as with the ATSFlatDataFontSpecRawNameData structure.

Discussion

Font information can be recorded in an ATSUStyle object using the attribute tag kATSUFontTag and an attribute value that is of type ATSUFontID. Unfortunately, a font ID can vary between systems or system startups, which means you cannot ensure that the font used when the style is flattened is the same font that will be used with the style is unflattened. To preserve font information, you must flatten font name data. You specify font information using the structure ATSFlatDataFontNameDataHeader. You store this structure as a style attribute value. You must make sure this structure maintains the required 4-byte alignment.

Following the ATSFlatDataFontNameDataHeader structure must be the flattened font name data of the type specified by the nameSpecifierType field. For instance, if the value of the nameSpecType field is kATSFlattenedFontNameSpecifierRawNameData, the structure that immediately follows should be a ATSFlatDataFontSpecRawNameDataHeader structure.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataFontSpecRawNameDataHeader

Contains raw font name data.

struct ATSFlatDataFontSpecRawNameDataHeader {
   ItemCount           numberOfFlattenedNames;
   ATSFlatDataFontSpecRawNameData  nameDataArray[1];
};
typedef struct ATSFlatDataFontSpecRawNameDataHeader ATSFlatDataFontSpecRawNameDataHeader;
Fields
numberOfFlattenedNames

The number of flattened font names. There must be at least one flattened font name, otherwise the structure is malformed.

nameDataArray[1]

The first element in an array of raw font name data.

Discussion

The function ATSUUnflattenStyleRunsFromStream searches for fonts that match the font data provides in the nameDataArray. ATSUI obtains matches for all the font name specifiers in the structure. You must supply at least one entry in the nameDataArray, but you may want to supply more than one entry to ensure a specific match. For example, the default ATSUI implementation is to use two name specifiers—the full name of the font (kFontFullName) and the font manufacturer’s name (kFontManufacturerName).

The ATSFlatDataFontSpecRawNameDataHeader structure must be followed by one or more ATSFlatDataFontSpecRawNameData structures. The number of structures must match the value specified by the numberOfFlattenedName field.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

ATSFlatDataFontSpecRawNameData

Contains data for a font name.

struct ATSFlatDataFontSpecRawNameData {
   FontNameCode        fontNameType;
   FontPlatformCode    fontNamePlatform;
   FontScriptCode      fontNameScript;
   FontLanguageCode    fontNameLanguage;
   ByteCount           fontNameLength;
};
typedef struct ATSFlatDataFontSpecRawNameData ATSFlatDataFontSpecRawNameData;
Fields
fontNameType

The type of font name. You must supply this parameter.

fontNamePlatform

The platform type of the font name. You should specify this if you know it (Unicode, Mac, and so forth). If you do not know the platform type, then specify kFontNoPlatform. In this case all matching is done by ATSUI based on the first font in the name table that matches the other parameters in this structure.

fontNameScript

The script code of the font name based on the platform specified in the fontNamePlatform field. If you set this to kFontNoScript, the name is matched based on the first font in the name table that matches the other font name parameters in this structure.

fontNameLanguage

The language of the font name. If you set this to kFontNoLanguage, the name is matched based on the first font in the name table that matches the other font name parameters in this structure.

fontNameLength

The length of the font name. The length should include any padding bytes needed to maintain the required 4-byte alignment.

Discussion

The ATSFlatDataFontSpecRawNameData structure is the structure in which raw font name data is actually stored. This structure is used only when the value of the nameSpecifierType field in the ATSFlatDataFontNameDataHeader structure is kATSFlattenedFontSpecifierRawNameData. The structure stores multiple font name table entries for the purposes of reconstructing an ATSUFontID value for the same font at some time in the future.

When the ATSUI parsing function ATSUUnflattenStyleRunsFromStream searches for fonts to match the font data in this structure, it obtains matches for all the font name specifiers in the structure. The default ATSUI implementation is to use two name specifiers—the full name of the font (kFontFullName) and the font manufacturer’s name (kFontManufacturerName).

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSUnicodeFlattening.h

Universal Procedure Pointers

ATSUDirectLayoutOperationOverrideUPP

Defines a universal procedure pointer to a layout operation callback.

typedef ATSUDirectLayoutOperationOverrideProcPtr ATSUDirectLayoutOperationOverrideUPP;
Discussion

For more information, see the description of the ATSUDirectLayoutOperationOverrideProcPtr callback function.

Availability
  • Available in OS X v10.2 and later.
Declared In
ATSLayoutTypes.h

ATSCubicClosePathUPP

Defines a universal procedure pointer to a cubic close-path callback.

typedef ATSCubicClosePathProcPtr ATSCubicClosePathUPP;
Discussion

For more information, see the description of the ATSCubicClosePathProcPtr callback function.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSCubicCurveToUPP

Defines a universal procedure pointer to a cubic curve-to callback.

typedef ATSCubicCurveToProcPtr ATSCubicCurveToUPP;
Discussion

For more information, see the description of the ATSCubicCurveToProcPtr callback function.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSCubicLineToUPP

Defines a universal procedure pointer to a cubic line-to callback.

typedef ATSCubicLineToProcPtr ATSCubicLineToProcUPP;
Discussion

For more information, see the description of the ATSCubicLineToProcPtr callback function.

ATSCubicMoveToUPP

Defines a universal procedure pointer to a cubic move-to callback.

typedef ATSCubicMoveToProcPtr ATSCubicMoveToUPP;
Discussion

For more information, see the description of the ATSCubicMoveToProcPtr callback function.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSQuadraticClosePathUPP

Defines a universal procedure pointer to a quadratic close-path callback.

typedef ATSQuadraticClosePathProcPtr ATSQuadraticClosePathUPP;
Discussion

For more information, see the description of the ATSQuadraticClosePathProcPtr callback function.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSQuadraticCurveUPP

Defines a universal procedure pointer to a quadratic curve callback.

typedef ATSQuadraticCurveProcPtr ATSQuadraticCurveUPP;
Discussion

For more information, see the description of the ATSQuadraticCurveProcPtr callback function.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSQuadraticLineUPP

Defines a universal procedure pointer to a quadratic line callback.

typedef ATSQuadraticLineProcPtr ATSQuadraticLineUPP;
Discussion

For more information, see the description of the ATSQuadraticLineProcPtr callback function.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

ATSQuadraticNewPathUPP

Defines a universal procedure pointer to a quadratic new-path callback.

typedef ATSQuadraticNewPathProcPtr ATSQuadraticNewPathUPP;
Discussion

For more information, see the description of the ATSQuadraticNewPathProcPtr callback function.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeGlyphs.h

RedrawBackgroundUPP

Defines a universal procedure pointer to a redraw-background callback.

typedef RedrawBackgroundProcPtr RedrawBackgroundUPP;
Discussion

For more information, see the description of the RedrawBackgroundProcPtr callback function.

Availability
  • Available in OS X v10.0 and later.
Declared In
ATSUnicodeTypes.h

Constants

Attribute Tags

Specify attributes that can be applied to a style object, a text layout object, or a line in a text layout object.

typedef UInt32 ATSUAttributeTag;
enum {
   kATSULineWidthTag = 1L,
   kATSULineRotationTag = 2L,
   kATSULineDirectionTag = 3L,
   kATSULineJustificationFactorTag = 4L,
   kATSULineFlushFactorTag = 5L,
   kATSULineBaselineValuesTag = 6L,
   kATSULineLayoutOptionsTag = 7L,
   kATSULineAscentTag = 8L,
   kATSULineDescentTag = 9L,
   kATSULineLangRegionTag = 10L,
   kATSULineTextLocatorTag = 11L,
   kATSULineTruncationTag = 12L,
   kATSULineFontFallbacksTag = 13L,
   kATSULineDecimalTabCharacterTag = 14L,
   kATSULayoutOperationOverrideTag = 15L,
   kATSULineHighlightCGColorTag  = 17L,
   kATSUMaxLineTag = 18L,
   kATSULineLanguageTag = 10L,
   kATSUCGContextTag = 32767L,
   kATSUQDBoldfaceTag = 256L,
   kATSUQDItalicTag = 257L,
   kATSUQDUnderlineTag = 258L,
   kATSUQDCondensedTag = 259L,
   kATSUQDExtendedTag = 260L,
   kATSUFontTag = 261L,
   kATSUSizeTag = 262L,
   kATSUColorTag = 263L,
   kATSULangRegionTag = 264L,
   kATSUVerticalCharacterTag = 265L,
   kATSUImposeWidthTag = 266L,
   kATSUBeforeWithStreamShiftTag = 267L,
   kATSUAfterWithStreamShiftTag = 268L,
   kATSUCrossStreamShiftTag = 269L,
   kATSUTrackingTag = 270L,
   kATSUHangingInhibitFactorTag = 271L,
   kATSUKerningInhibitFactorTag = 272L,
   kATSUDecompositionFactorTag = 273L,
   kATSUBaselineClassTag = 274L,
   kATSUPriorityJustOverrideTag = 275L,
   kATSUNoLigatureSplitTag = 276L,
   kATSUNoCaretAngleTag = 277L,
   kATSUSuppressCrossKerningTag = 278L,
   kATSUNoOpticalAlignmentTag = 279L,
   kATSUForceHangingTag = 280L,
   kATSUNoSpecialJustificationTag = 281L,
   kATSUStyleTextLocatorTag = 282L,
   kATSUStyleRenderingOptionsTag = 283L,
   kATSUAscentTag         = 284L,
   kATSUDescentTag = 285L,
   kATSULeadingTag = 286L,
   kATSUGlyphSelectorTag = 287L,
   kATSURGBAlphaColorTag     = 288L,
   kATSUFontMatrixTag = 289L,
   kATSUStyleUnderlineCountOptionTag = 290L,
   kATSUStyleUnderlineColorOptionTag = 291L,
   kATSUStyleStrikeThroughTag    = 292L,
   kATSUStyleStrikeThroughCountOptionTag = 293L,
   kATSUStyleStrikeThroughColorOptionTag = 294L,
   kATSUStyleDropShadowTag = 295L,
   kATSUStyleDropShadowBlurOptionTag = 296L,
   kATSUStyleDropShadowOffsetOptionTag = 297L,
   kATSUStyleDropShadowColorOptionTag = 298L,
   kATSUMaxStyleTag = 299L,
   kATSULanguageTag = 264L,
   kATSUMaxATSUITagValue = 65535L
};
Constants
kATSULineWidthTag

Specifies the desired width of a line of text, in typographic points, of the line when drawn as justified or right-aligned text. The associated value is of type ATSUTextMeasurement and has a default value of 0.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineRotationTag

Specifies the angle by which the entire line should be rotated. The associated value is a Fixed value that specifies degrees in a right-hand coordinate system, and has a default value of 0.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineDirectionTag

Specifies a left-to-right or right-to-left direction for the glyphs in a text layout object, regardless of their natural direction as specified in the font. The associated value is Boolean (kATSURightToLeftBaseDirection or kATSULeftToRightBaseDirection) and has a default value of GetSysDirection(). See “Glyph Direction Selectors” for more information on the values that can be associated with this tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineJustificationFactorTag

Specifies how ATSUI should typographically fit a line of text to a given width (or height, in the case of vertical text). The associated value is a Fract value between 0 and 1 and has a default value of kATSUNoJustification. See “Line Justification Selectors” for information on the values that can be associated with this tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineFlushFactorTag

Specifies how ATSUI should place text in relation to one or both margins, which are the left and right sides (or top and bottom sides) of the text area. The associated value is a Fract value between 0 and 1 and has a default value of kATSUStartAlignment. See “Line Alignment Selectors ” for information on the values that can be associated with this tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineBaselineValuesTag

Specifies the positions of different baseline types with respect to one another in a line of text. The associated value is of type BslnBaselineRecord and contains default values all of which are 0. The values are calculated from other style attributes such as font and point size.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineLayoutOptionsTag

Specifies how ATSUI should manipulate basic attributes of a line or the text layout object, such as whether a line should have optical hangers or whether the last line of a text layout object should be justified. The associated value is of type ATSLineLayoutOptions and has a default value of kATSLineNoLayoutOptions. See “Line Layout Attribute Tags” for information on the values that can be associated with this tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineAscentTag

Specifies line ascent. The associated value is of type ATSUTextMeasurement and has a default value of kATSUseLineHeight. See “Line Height and Font Tracking Selectors” for information on the values that can be associated with this tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineDescentTag

Specifies line descent. The associated value is of type ATSUTextMeasurement and has a default value of kATSUseLineHeight. See “Line Height and Font Tracking Selectors” for information on the values that can be associated with this tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineLangRegionTag

Specifies line language region. The associated value is a region code (see the Script Manager reference for a list of region codes) and has a default value of kTextRegionDontCare.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineTextLocatorTag

Specifies line text location. The associated value is of type TextBreakLocatorRef and has a default value of NULL.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineTruncationTag

Specifies where in a line truncation should occur. The associated value is of type ATSULineTruncation and has a default value of kATSUTruncateNone. See “Line Truncation Selectors” for the values that can be associated with the line truncation tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineFontFallbacksTag

Specifies line font fallbacks. The associated value is of type ATSUFontFallbacks. See “Font Fallback Methods” for information on the values that can be associated with this tag.

Available in OS X v10.1 and later.

Declared in ATSUnicodeTypes.h.

kATSULineDecimalTabCharacterTag

Specifies the current setting for the decimal separator, and affects the behavior of decimal tabs for a text layout (not an individual line). The associated value is of type CFStringRef. The CFString object (CFStringRef) is retained by the style object in which it is set. The default value is the user setting in System Preferences.

Declared in ATSUnicodeTypes.h.

Available in Mac OS X version 10.3 and later.

kATSULineHighlightCGColorTag

Specifies the current setting of the highlight color and opacity. The associated value is of type CGColorRef. This can be set as a line or layout control. The CGColor object (CGColorRef) is retained by the text layout object in which it is set.

Available in Mac OS X version 10.3 and later.

Declared in ATSUnicodeTypes.h.

kATSULayoutOperationOverrideTag

Specifies to override a layout operation. The associated value is of type ATSULayoutOperationOverrideSpecifier and has a default value of NULL.

Available starting with Mac OS X version 10.2.

Declared in ATSUnicodeTypes.h.

kATSUMaxLineTag

A convenience tag that specifies the upper limit of the text layout attribute tags.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULineLanguageTag

Not recommended. Instead use kATSULineLangRegionTag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUCGContextTag

Specifies to use a Quartz context. When you use this tag to set up a Quartz context, ATSUI uses an 8-bit, sub-pixel rendering. This method of rendering positions glyph origins on fractional points, which results in superior rendering compared to ATSUI’s default 4-bit pixel-aligned rendering. The attribute has a default value of NULL; you must provide a pointer to a CGContext. The CGContext is not retained by the text layout object; if the context is destroyed, the text layout contains an invalid CGContext. Available only in Mac OS X.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUQDBoldfaceTag

Specifies a boldface text style. Text style attribute tags are included for compatibility with the Style type used by the QuickDraw function TextFace. If a font variant for this text style exists, ATSUI uses that variant. Otherwise, the variant is generated algorithmically. The associated value is of type Boolean and has a default value of false.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUQDItalicTag

Specifies an italic text style. Text style attribute tags are included for compatibility with the Style type used by the QuickDraw function TextFace. If a font variant for this text style exists, ATSUI uses that variant. Otherwise, the variant is generated. The associated value is of type Boolean and has a default value of false.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUQDUnderlineTag

Specifies an underline text style. Text style attribute tags are included for compatibility with the Style type used by the QuickDraw function TextFace. If a font variant for this text style exists, ATSUI uses that variant. Otherwise, the variant is generated. The associated value is of type Boolean and has a default value of false.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUQDCondensedTag

Specifies a condensed text style. Text style attribute tags are included for compatibility with the Style type used by the QuickDraw function TextFace. If a font variant for this text style exists, ATSUI uses that variant. Otherwise, the variant is generated. The associated value is of type Boolean and has a default value of false.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUQDExtendedTag

Specifies an extended text style. Text style attribute tags are included for compatibility with the Style type used by the QuickDraw function TextFace. If a font variant for this text style exists, ATSUI uses that variant. Otherwise, the variant is generated The associated value is of type Boolean and has a default value of false.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUFontTag

Specifies a unique value that identifies a font to the font management system. The associated value is of type ATSUFontID and has a default value of GetScriptVariable (smSystemScript, smScriptAppFond).

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUSizeTag

Specifies the font size of the text in the style run. The associated value, in typographic points (72 per inch), is of type Fixed and has a default value of GetScriptVariable (smSystemScript, smScriptAppFondSize).

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUColorTag

Specifies the color of the glyphs in a style run. The associated value is of type RGBColor and has a default value of (0,0,0).

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULangRegionTag

Specifies a language region. The associated value is a region code (see the Script Manager reference for a list of region codes) and has a default value of GetScriptManagerVariable (smRegionCode).

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUVerticalCharacterTag

Specifies which direction (vertical or horizontal) glyphs should be drawn. The associated value is of type ATSUVerticalCharacterType and has a default value of kATSUStronglyHorizontal. See “Vertical Character Types” for more information on the values that can be associated with this tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUImposeWidthTag

Specifies an imposed width. The associated value is of type ATSUTextMeasurement and has a default value of 0; all glyphs use their own font defined advance widths.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUBeforeWithStreamShiftTag

Specifies a uniform shift parallel to the baseline of the positions of individual pairs or sets of glyphs in the style run that’s applied before (to the left) the glyphs of the style run. The associated value is of type Fixed and has a default value of 0. Starting with Mac OS version 10.3, glyphs cannot be negatively shifted such that later glyphs appear before earlier glyphs. In other words, ATSUI limits the shift to a value that is, at most, the advance of the previous glyph.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUAfterWithStreamShiftTag

Specifies a uniform shift parallel to the baseline of the positions of individual pairs or sets of glyphs in the style run that’s applied after (to the right) the glyphs of the style run. The associated value is of type Fixed and has a default value of 0. Starting with Mac OS version 10.3, glyphs cannot be negatively shifted such that later glyphs appear before earlier glyphs. In other words, ATSUI limits the shift to a value that is, at most, the advance of the current glyph.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUCrossStreamShiftTag

Specifies the distance to raise or lower glyphs in the style run perpendicular to the text stream. This shift is vertical for horizontal text and horizontal for vertical text. The associated value (in points, 72 per inch) is of type Fixed and has a default value of 0.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUTrackingTag

Specifies the relative proportion of font-defined adjustments to apply to interglyph positions. The associated value is of type Fixed and has a default value of kATSNoTracking. See “Line Height and Font Tracking Selectors” for information on the values that can be associated with this tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUHangingInhibitFactorTag

Specifies to what degree punctuation glyphs can hang beyond the end of a line for justification purposes. The associated value is a Fract value between 0 and 1 and has a default value of 0.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUKerningInhibitFactorTag

Specifies how much to inhibit kerning; that is, the increase or decrease the space between glyphs. The associated value is a Fract value between 0 and 1 and has a default value of 0.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUDecompositionFactorTag

Specifies the fractional adjustment to the font-specified threshold at which ligature decomposition occurs during justification. The associated value is a Fract value between -1.0 and 1.0 and has a default value of 0 (no adjustment to the font-specified threshold).

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUBaselineClassTag

Specifies the preferred baseline (such as Roman, hanging, or ideographic centered) to use for text of a given font in a style run. The associated value is of type BslnBaselineClass (see SFNTLayoutTypes.h) and has a default value of kBSLNRomanBaseline. You can set the value to kBSLNNoBaselineOverride to use intrinsic baselines.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUPriorityJustOverrideTag

Specifies the degree to which ATSUI should override justification behavior for glyphs in the style run. The associated value is of type ATSJustWidthDeltaEntryOverride. The default values in this structure are all 0.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUNoLigatureSplitTag

Specifies whether or not ligatures and compound characters in a style have divisible components. The associated value is a Boolean and has a default value of false; ligatures and compound characters have divisible components.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUNoCaretAngleTag

Specifies whether the text caret or edges of a highlighted area are always parallel to the slant of the style run’s text or always perpendicular to the baseline. The associated value is a Boolean and has a default value of false; use the character's angularity to determine its boundaries.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUSuppressCrossKerningTag

Specifies whether or not to suppress cross kerning. The associated value is a Boolean and has a default value of false; do not suppress automatic cross kerning (defined by font).

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUNoOpticalAlignmentTag

Specifies the amount to which ATSUI should adjust glyph positions at the ends of lines to give a more even visual appearance to margins. The associated value is a Boolean and has a default value of false; do not suppress character's automatic optical positional alignment

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUForceHangingTag

Specifies to treat glyphs in a style run as hanging punctuation, whether or not the font designer intended them to be. The associated value is a Boolean and has a default value of false; do not force the character's to hang beyond the line boundaries

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUNoSpecialJustificationTag

Specifies whether processes (such as glyph stretching and ligature decomposition) that occur at the end of the justification process should be applied. The associated value is a Boolean and has a default value of false; perform post-compensation justification if needed

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleTextLocatorTag

Specifies style text locator. The associated value is of type TextBreakLocatorRef and has a default value of NULL—region derived locator or the default Text Utilities locator.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleRenderingOptionsTag

Specifies style rendering options. The associated value is of type ATSUStyleRenderingOptions and has a default value of kATSStyleApplyHints—ATS glyph rendering uses hinting. See “Style Rendering Options” for more information on the values that can be associated with this tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUAscentTag

Specifies the ascent value of a style’s font. The associated value is of type ATSUTextMeasurement and has a default value of the ascent value of the style object’s font with the current point size.

Available starting with Mac OS X version 10.2.

Declared in ATSUnicodeTypes.h.

kATSUDescentTag

Specifies the descent value of a style’s font. The associated value is of type ATSUTextMeasurement and has a default value of the descent value of the style object’s font with the current point size. The leading value is not included as par of the descent.

Declared in ATSUnicodeTypes.h.

Available starting with Mac OS X version 10.2.

kATSULeadingTag

Specifies the leading value of a style’s font. The associated value is of type ATSUTextMeasurement and has a default value of the leading value of the style object’s font with the current point size.

Available starting with Mac OS X version 10.2.

Declared in ATSUnicodeTypes.h.

kATSUGlyphSelectorTag

Specifies a glyph collection. The associated value is an address to an ATSUGlyphSelector data structure. Using this tag allows you access to characters in the fonts that otherwise would not be accessible. You can choose the variant glyph by providing a font-specific glyph ID or a CID. For more information on CID conventions, see http://www.adobe.com. You can get the variant glyph information from an input method through the Text Services Manager using the Carbon event key, kEventParamTextInputGlyphInfoArray.

Declared in ATSUnicodeTypes.h.

Available starting with Mac OS X version 10.2.

kATSURGBAlphaColorTag

Specifies RGB color with an alpha channel. The associated value is of type ATSURGBAlphaColor and has a default value of (0,0,0,1).

Available starting with Mac OS X version 10.2.

Declared in ATSUnicodeTypes.h.

kATSUFontMatrixTag

Specifies a font transformation matrix. The associated value is of type CGAffineTransform. (See the Quartz 2D reference documentation for more information on this data type.) You can use a font matrix to achieve effects through ATSUI at a style-run level that were previously available only by changing settings directly in a CGContext. When you use the tag kATSUFontMatrixTag, you associate a font transformation matrix with an ATSUStyle object. You can set the values in the font transformation matrix to achieve such effects as reversing glyphs across the X-axes and rotating glyphs Note that ATSUI’s layout uses the transformed metrics so layout will be effected and in some cases the effects might be unexpected. For example, for a transformation that mirrors the glyph across the Y-axes the metrics are in reverse and glyphs are rendered on top of each other.

Declared in ATSUnicodeTypes.h.

Available starting with Mac OS X version 10.2.

kATSUStyleUnderlineCountOptionTag

Specifies the number of strokes to be drawn for an underline. The associated value is of type ATSUStyleLineCountType. The default value is kATSUStyleSingleLineCount. May be set as a style attribute.

Available in Mac OS X version 10.3 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleUnderlineColorOptionTag

Specifies the color of the strokes to draw for an underlined run of text. The associated value is of type CGColorRef. The default value is NULL. If NULL, the text color is used. The CGColor object (CGColorRef) is retained by the style object in which it is set. May be set as a style attribute.

Declared in ATSUnicodeTypes.h.

Available in Mac OS X version 10.3 and later.

kATSUStyleStrikeThroughTag

Specifies strikethrough style. The associated value is of type Boolean. The default value is false. May be set as a style attribute.

Available in Mac OS X version 10.3 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleStrikeThroughCountOptionTag

Specifies the number of strokes to be drawn for a strikethrough. The associated value is of type ATSUStyleLineCountType. The default value is kATSUStyleSingleLineCount. May be set as a style attribute.

Available in Mac OS X version 10.3 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleStrikeThroughColorOptionTag

Specifies the color of the strokes to draw for a strikethrough style. The associated value is of type CGColorRef. The CGColor object (CGColorRef) is retained by the style object in which it is set. The default value is NULL. If NULL, the text color is used. May be set as a style attribute.

Declared in ATSUnicodeTypes.h.

Available in Mac OS X version 10.3 and later.

kATSUStyleDropShadowTag

Specifies the text should be drawn with a drop shadow. The associated value is of type Boolean. The default value is false. Only takes effect if a CGContext is used for drawing. If you set this style attribute, you also need to set the drop shadow color using the tag kATSUStyleDropShadowColorOptionTag.

Declared in ATSUnicodeTypes.h.

Available in Mac OS X version 10.3 and later.

kATSUStyleDropShadowBlurOptionTag

Specifies the amount of blur for a drop shadow. The associated value is of type float. The default value is 0.0. May be set as a style attribute.

Available in Mac OS X version 10.3 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleDropShadowColorOptionTag

Specifies the color and opacity of a drop shadow. The associated value is of type CGColorRef. The default value is NULL. You need to set the CGColorRef to a value other than NULL if you want to see the drop shadow. May be set as a style attribute.

Available in Mac OS X version 10.3 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleDropShadowOffsetOptionTag

Specifies the amount of offset from the text to be used when drawing a drop shadow. The associated value is of type CGSize. The default value is (3.0, -3.0). May be set as a style attribute.

Available in Mac OS X version 10.3 and later.

Declared in ATSUnicodeTypes.h.

kATSUMaxStyleTag

A convenience tag that specifies the upper limit of style attribute tags.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULanguageTag

This tag is obsolete. Instead use kATSULangRegionTag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUMaxATSUITagValue

Specifies this maximum Apple ATSUI reserved tag value. If you define a tag, it must have a value larger than the value of this tag.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Discussion

An attribute tag cannot be used in versions of the Mac OS that are earlier than the version in which the tag was introduced. For example, a tag available in Mac OS version 10.2 cannot be used in Mac OS version 10.1 or earlier. You can call the function Gestalt to check version information for ATSUI.

Attribute tags indicates the particular type of attribute under consideration: font, size, color, and so on. Each style run may have at most one attribute with a given attribute tag (that is, a style run can't have more than one font or size) but may have none.

Some of the constants specify attributes that are applied to a style run, while other attributes are applied to an entire text layout object or to just a line in a text layout object. The constant descriptions assume horizontal text. If you set or get the an attribute that has been set for vertical text, you should interpret the constant descriptions accordingly.

Most of the constants in this section are described in further detail in Inside Mac OS X: Rendering Unicode Text With ATSUI. Where appropriate, that document provides illustrations that show the effect of applying an attribute. It also describes how to write code that sets style, line, and layout attributes.

A style run may have at most one style attribute with a given attribute tag. That is, a style run can't have more than one font or size attribute set but the style run does not need to have any attribute set explicitly.

When you set an attribute value for a line, the value overrides the attribute value set for the text layout object that contains the line. This is true even if you set line attributes before you set attributes for the entire text layout object that contains the line.

You can create your own attribute tag as long as your tag is outside those values reserved by Apple— 0 to 65,535 (0 to 0x0000FFFF). See Rendering Unicode Text With ATSUI for information on creating and registering your own attribute tags.

Background Data Types

Specify the data type of the background—a color or a callback.

typedef UInt32 ATSUBackgroundDataType;
enum {
   kATSUBackgroundColor = 0,
   kATSUBackgroundCallback = 1
};
Constants
kATSUBackgroundColor

Specifies the data type of the text background is a color.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUBackgroundCallback

Specifies the data type of the text background is a callback.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Caret Movement Types

Specify the unit distance by which the caret moves.

typedef UInt16 ATSUCursorMovementType;
enum {
   kATSUByCharacter = 0,
   kATSUByTypographicCluster = 1,
   kATSUByWord = 2,
   kATSUByCharacterCluster = 3,
   kATSUByCluster = 1
};
Constants
kATSUByCharacter

Specifies to move the caret by a units based on single characters.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUByTypographicCluster

Specifies to move the caret by units of clusters based on characters or ligatures.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUByWord

Specifies to move the caret by units based on words.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUByCharacterCluster

Specifies to move the caret by units based only on clusters of characters.

Available only in Mac OS X and in CarbonLib versions 1.3 and later.

Declared in ATSUnicodeTypes.h.

kATSUByCluster

An obsolete name for the constant kATSUByTypographicCluster.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Discussion

A caret movement type is used to indicate the unit (character, word, and so on) by which to move the caret. You use these constants when you call the ATSUI caret movement functions. Functions that use caret movement types use this information to calculate the edge offset in memory that corresponds to the resulting cursor position.

Convenience Constants

Specify whether to clear values or whether drawing, measuring, or hit-testing should be done relative to the current pen location in the current graphics port.

enum {
   kATSUUseGrafPortPenLoc = (unsigned long)xFFFFFFFF,
   kATSUClearAll = (unsigned long)xFFFFFFFF
};
Constants
kATSUUseGrafPortPenLoc

Indicates that drawing, measuring, or hit-testing should be done relative to the current pen location in the current graphics port.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUClearAll

Removes all previously set values from a style object, a single line, or a text layout object.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Discussion

You can pass the kATSUUseGrafPortPenLoc constant to functions that operate on text layout objects to indicate that drawing, measuring, or hit-testing should be done relative to the current pen location in the current graphics port.

You can pass the kATSUClearAll constant to the following functions to remove previously set values from a style object: to ATSUClearAttributes to remove style run attributes, to ATSUClearFontFeatures to remove font features, and to ATSUClearFontVariations to remove font variations.

You can also use the kATSUClearAll constant to remove previously set text layout attributes: to ATSUClearLineControls, to remove text layout attributes from a single line of a text layout object, and to ATSUClearLayoutControls to remove text layout attributes from every line in a text layout object.

Direct Data Selectors

Specify the layout data to obtain when calling the functions ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout.

typedef UInt32 ATSUDirectDataSelector;
enum {
   kATSUDirectDataAdvanceDeltaFixedArray = 0L,
   kATSUDirectDataBaselineDeltaFixedArray = 1L,
   kATSUDirectDataDeviceDeltaSInt16Array = 2L,
   kATSUDirectDataStyleIndexUInt16Array = 3L,
   kATSUDirectDataStyleSettingATSUStyleSettingRefArray = 4L,
   kATSUDirectDataLayoutRecordATSLayoutRecordVersion1 = 100L,
   kATSUDirectDataLayoutRecordATSLayoutRecordCurrent =
   kATSUDirectDataLayoutRecordATSLayoutRecordVersion1
};
Constants
kATSUDirectDataAdvanceDeltaFixedArray

Specifies the parallel advance delta (delta X) array, which is an array of Fixed values. This array is created only on demand. If you plan to modify the data in this array, you should set the iCreate parameter to true when you call the functions ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout to obtain this array.

Available in OS X v10.2 and later.

Declared in ATSUnicodeDirectAccess.h.

kATSUDirectDataBaselineDeltaFixedArray

Specifies the parallel baseline delta (delta Y) array, which is an array of Fixed values. This array is created only on demand. If you plan to modify the data in this array, you should set the iCreate parameter to true when you call the functions ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout to obtain this array.

Available in OS X v10.2 and later.

Declared in ATSUnicodeDirectAccess.h.

kATSUDirectDataDeviceDeltaSInt16Array

Specifies the parallel device delta array, which is an array of SInt16 values used to adjust truncated fractional values for devices that do not accept fractional positioning. The array specified by this selector is also used to provide precise positioning for connected scripts. This array is created only on demand. If you plan to modify the data in this array, you should set the iCreate parameter to true when you call the functions ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout to obtain this array.

Available in OS X v10.2 and later.

Declared in ATSUnicodeDirectAccess.h.

kATSUDirectDataStyleIndexUInt16Array

Specifies the parallel style index array, which is an array of (UInt16) values. The values in this array are indexes into the style setting reference (ATSUStyleSettingRef) array. This array is created only on demand. If you plan to modify the data in this array, you should set the iCreate parameter to true when you call the functions ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout to obtain this array.

Available in OS X v10.2 and later.

Declared in ATSUnicodeDirectAccess.h.

kATSUDirectDataStyleSettingATSUStyleSettingRefArray

Specifies the style setting reference (ATSUStyleSettingRef) array. This array is always available if the text layout object has any text associated with it. Setting the iCreate parameter when you call the functions ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout to obtain this array has no effect.

Available in OS X v10.2 and later.

Declared in ATSUnicodeDirectAccess.h.

kATSUDirectDataLayoutRecordATSLayoutRecordVersion1

Specifies the ATSLayoutRecord array, with the version 1 of the ATSLayoutRecord data structure. You should not use this selector. Instead use the selector kATSUDirectDataLayoutRecordATSLayoutRecordCurrent to ensure that your code uses the most current version of the ATSLayoutRecord data structure. ATSUI performs the most efficient processing only for the latest version of ATSLayoutRecord data structure. This array is always available if the text layout object has any text associated with it. Setting the iCreate parameter when you call the functions ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout to obtain this array has no effect.

Available in OS X v10.2 and later.

Declared in ATSUnicodeDirectAccess.h.

kATSUDirectDataLayoutRecordATSLayoutRecordCurrent

Specifies the ATSLayoutRecord array, with the current version of the ATSLayoutRecord data structure. Always use this selector to get the array of ATSLayoutRecord data structures. This array is always available if the text layout object has any text associated with it. Setting the iCreate parameter when you call the functions ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout to obtain this array has no effect.

Available in OS X v10.2 and later.

Declared in ATSUnicodeDirectAccess.h.

Discussion

You can provide direct data selectors to the functions ATSUDirectGetLayoutDataArrayPtrFromLineRef or ATSUDirectGetLayoutDataArrayPtrFromTextLayout.

Flattened Data Font Type Selectors

Specifies the data type for flattened font name data.

typedef UInt32 ATSFlatDataFontSpeciferType;
enum {
   kATSFlattenedFontSpecifierRawNameData = 'namd'
};
Constants
kATSFlattenedFontSpecifierRawNameData

Specifies to use the font name as the flattened font name.

Available in OS X v10.2 and later.

Declared in ATSUnicodeFlattening.h.

Flattened Data Format Selectors

Specify the format to use when flattening or unflattening data.

typedef UInt32 ATSUFlattenedDataStreamFormat;
enum {
   kATSUDataStreamUnicodeStyledText = 'ustl'
};
Constants
kATSUDataStreamUnicodeStyledText

Specifies to use the 'ustl' data specification when flattening or unflattening data.

Available in OS X v10.2 and later.

Declared in ATSUnicodeFlattening.h.

Flattened Style Run Data Options

Specify options to use when flattening ATSUI style run data.

typedef UInt32 ATSUFlattenStyleRunOptions;
enum {
   kATSUFlattenOptionNoOptionsMask = 0x00000000
};
Constants
kATSUFlattenOptionNoOptionsMask

Specifies that no options are to be used.

Available in OS X v10.2 and later.

Declared in ATSUnicodeFlattening.h.

Discussion

Additional options may be added in the future.

Flattened Data Version Numbers

Specify versions of the 'ustl' specification.

enum {
   kATSFlatDataUstlVersion0      = 0,
   kATSFlatDataUstlVersion1      = 1,
   kATSFlatDataUstlVersion2      = 2,
   kATSFlatDataUstlCurrentVersion = kATSFlatDataUstlVersion2};
Constants
kATSFlatDataUstlVersion0

Specifies version 0. This version is obsolete.

Available in OS X v10.2 and later.

Declared in ATSUnicodeFlattening.h.

kATSFlatDataUstlVersion1

Specifies version 1. This version is obsolete.

Available in OS X v10.2 and later.

Declared in ATSUnicodeFlattening.h.

kATSFlatDataUstlVersion2

Specifies version 2.

Available in OS X v10.2 and later.

Declared in ATSUnicodeFlattening.h.

kATSFlatDataUstlCurrentVersion

Specifies the current version.

Available in OS X v10.2 and later.

Declared in ATSUnicodeFlattening.h.

Discussion

The ATSUI functions ATSUFlattenStyleRunsToStream and ATSUUnflattenStyleRunsFromStream operate on data that conform to version 2 of the 'ustl' specification.

Font Fallback Methods

Specify the method by which ATSUI tries to find an appropriate font for a character if the assigned font does not contain the needed glyphs.

typedef UInt16 ATSUFontFallbackMethod;
enum {
   kATSUDefaultFontFallbacks = 0,
   kATSULastResortOnlyFallback = 1,
   kATSUSequentialFallbacksPreferred = 2,
   kATSUSequentialFallbacksExclusive = 3
};
Constants
kATSUDefaultFontFallbacks

Specifies to use ATSUI’s default font search method. ATSUI searches through all available fonts on the system for one that matches any text that cannot be drawn with the font specified in the current ATSU style object (ATSUStyle). ATSUI first searches in the standard application fonts for various languages. If that fails, it searches through the remaining fonts on the system in whatever order the Font Manager returns them. After ATSUI has searched all the fonts in the system, any unmatched text is drawn with the last-resort font.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSULastResortOnlyFallback

Specifies that ATSUI should use the last resort font if the assigned font does not contain the needed glyphs.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUSequentialFallbacksPreferred

Specifies that ATSUI should first search sequentially through the list of supplied fonts before it searching through all available fonts on the system.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUSequentialFallbacksExclusive

Specifies that ATSUI should search exclusively through the list of supplied fonts. ATSUI use the last-resort font if it does not find a match in the list of supplied fonts.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Glyph Origin Selectors

Specify which glyph origin to use to determine the width of the typographic glyph bounds.

enum {
   kATSUseCaretOrigins           = 0,
   kATSUseDeviceOrigins          = 1,
   kATSUseFractionalOrigins      = 2,
   kATSUseOriginFlags            = 3
};
Constants
kATSUseCaretOrigins

Specifies to use the caret origin to determine the width of the typographic glyph bounds. The caret origin is halfway between two characters.

Available in OS X v10.0 and later.

Declared in ATSLayoutTypes.h.

kATSUseDeviceOrigins

Specifies to use the glyph origin in device space to determine the width of the typographic glyph bounds. This is useful if you need to adjust text on the screen.

Available in OS X v10.0 and later.

Declared in ATSLayoutTypes.h.

kATSUseFractionalOrigins

Specifies to use the glyph origin in fractional absolute positions (which are uncorrected for display device) to determine the width of the typographic glyph bounds. This provides the ideal position of laid-out text and is useful if you need to scale text on the screen. The glyph origin is also used to obtain the width of the typographic bounding rectangle when you call the function ATSUMeasureText.

Available in OS X v10.0 and later.

Declared in ATSLayoutTypes.h.

kATSUseOriginFlags

The number of glyph origin selectors.

Available in OS X v10.0 and later.

Declared in ATSLayoutTypes.h.

Discussion

You can pass a glyph bounds selector in the iTypeOfBounds parameter of the function ATSUGetGlyphBounds to indicate whether the width of the resulting typographic glyph bounds is determined using the caret origin, glyph origin in device space, or glyph origin in fractional absolute positions.

Glyph Collection Types

Specify a character set.

typedef UInt16 GlyphCollection;
enum {
   kGlyphCollectionGID           = 0,
   kGlyphCollectionAdobeCNS1     = 1,
   kGlyphCollectionAdobeGB1      = 2,
   kGlyphCollectionAdobeJapan1   = 3,
   kGlyphCollectionAdobeJapan2   = 4,
   kGlyphCollectionAdobeKorea1   = 5,
   kGlyphCollectionUnspecified   = 0xFF
};
Constants
kGlyphCollectionGID

Indicates that the glyph value represents the actual glyph ID of a specific font.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

kGlyphCollectionAdobeCNS1

Specifies Adobe CNS1 CID-keyed fonts.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

kGlyphCollectionAdobeGB1

Specifies Adobe GB1 CID-keyed fonts.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

kGlyphCollectionAdobeJapan1

Specifies Adobe Japan1 CID-keyed fonts.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

kGlyphCollectionAdobeJapan2

Specifies Adobe Japan2 CID-keyed fonts.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

kGlyphCollectionAdobeKorea1

Specifies Adobe Korea1 CID-keyed fonts.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

kGlyphCollectionUnspecified

Indicates that the glyph collection is not specified.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

Discussion

A CID-keyed font is a PostScript font that uses a font file format developed by Adobe for fonts that have large character sets, such as Chinese, Japanese, and Korean fonts. For more information on CID-keyed fonts, see the Adobe website:

http://partners.adobe.com/

Glyph Direction Selectors

Specify a glyph direction.

enum {
   kATSULeftToRightBaseDirection = 0,
   kATSURightToLeftBaseDirection = 1
};
Constants
kATSULeftToRightBaseDirection

Imposes left-to-right direction on glyphs in a line of horizontal text; for vertical text, imposes top-to-bottom direction.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSURightToLeftBaseDirection

Imposes right-to-left direction on glyphs in a line of horizontal text; for vertical text, imposes bottom-to-top direction.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Discussion

These constants specify values for the kATSULineDirectionTag attribute tag. You can use one of these constants to set or obtain glyph direction in a line of text or an entire text layout object, regardless of their font-specified direction; see the functions ATSUSetLayoutControls, ATSUSetLineControls, ATSUGetLayoutControl, and ATSUGetLineControl.

Glyph Property Flags

Specify properties for a glyph.

typedef UInt32 ATSGlyphInfoFlags;
enum {
   kATSGlyphInfoAppleReserved    = 0x1FFBFFE8,
   kATSGlyphInfoIsAttachment     = (unsigned long)x80000000,
   kATSGlyphInfoIsLTHanger       = 0x40000000,
   kATSGlyphInfoIsRBHanger       = 0x20000000,
   kATSGlyphInfoTerminatorGlyph  = 0x00080000,
   kATSGlyphInfoIsWhiteSpace     = 0x00040000,
   kATSGlyphInfoHasImposedWidth  = 0x00000010,
   kATSGlyphInfoByteSizeMask     = 0x00000007
};
Constants
kATSGlyphInfoAppleReserved

This flag is reserved by Apple. If you try to use it you may get an invalid value error.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSGlyphInfoIsAttachment

Specifies that the glyph attaches to another glyph.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSGlyphInfoIsLTHanger

Specifies that the glyph can hang off the left or top edge of a line.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSGlyphInfoIsRBHanger

Specifies that the glyph can hang off the right or bottom edge of a line.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSGlyphInfoTerminatorGlyph

Specifies that the glyph is not truly a glyph, but an end-marker to allow the calculation of the previous glyph's advance.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSGlyphInfoIsWhiteSpace

Specifies that the glyph is a whitespace glyph.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSGlyphInfoHasImposedWidth

Specifies that the glyph has an imposed width (that is, an advance width) specified by the style.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSGlyphInfoByteSizeMask

Specifies the size of the character that spawned the glyph. This is a three-bit mask that you can use to obtain the size of the original character that spawned a glyph. If you perform a logical and operation between this mask and an ATSGlyphInfoFlags flag, you obtain the size in bytes of the original character (0 - 7 bytes).

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

Discussion

Glyph information flags are set in the individual ATSLayoutRecord structure and apply only to the ATSGlyphRef reference in that structure. The flags are used by the ATSUI to tag a glyph with one or more specific properties.

Highlight Methods

Specify a text highlighting method.

typedef UInt32 ATSUHighlightMethod;
enum {
   kInvertHighlighting = 0,
   kRedrawHighlighting = 1
};
Constants
kInvertHighlighting

Specifies to use inversion for highlighting. You can use this when the background is a single color.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kRedrawHighlighting

Specifies to use your callback for highlighting. You should use this when the background is complex (containing, for example, multiple colors, patterns, or pictures).

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Discussion

You set the highlighting method by calling the function ATSUSetHighlightingMethod.

Invalid Font ID Constant

Specifies a Font ID is not valid.

enum {
   kATSUInvalidFontID = 0
};
Constants
kATSUInvalidFontID

Indicates that the font ID is invalid.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Discussion

The functions ATSUFONDtoFontID, ATSUFindFontFromName, and ATSUMatchFontsToText pass back this constant to indicate an invalid font ID. This constant is available with ATSUI 1.0.

Line Truncation Selectors

Specify where in a line truncation should occur.

typedef UInt32 ATSULineTruncation;
enum {
   kATSUTruncateNone = 0,
   kATSUTruncateStart = 1,
   kATSUTruncateEnd = 2,
   kATSUTruncateMiddle = 3,
   kATSUTruncateSpecificationMask = 7,
   kATSUTruncFeatNoSquishing = 8
};
Constants
kATSUTruncateNone

Specifies not to truncate the line.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUTruncateStart

Specifies to truncate the line at the beginning.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUTruncateEnd

Specifies to truncate the line at the end.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUTruncateMiddle

Specifies to truncate the line in the middle

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUTruncateSpecificationMask

Reserved for the truncation specification (0 - 7).

Available in OS X v10.1 and later.

Declared in ATSUnicodeTypes.h.

kATSUTruncFeatNoSquishing

Specifies not to perform any negative justification in lieu of truncation.

Available in OS X v10.1 and later.

Declared in ATSUnicodeTypes.h.

Discussion

Line truncation options specify values for the kATSULineTruncation attribute tag. You can add any line truncation option to the option kATSUTruncateSpecificationMask. For example, adding kATSUTruncateEnd and kATSUTruncFeatNoSquishing to the mask kATSUTruncateSpecificationMask results in the value 0x0000000A.

Layout Callback Status Values

Specify the status of a layout operation override callback.

typedef UInt32 ATSULayoutOperationCallbackStatus;
enum {
   kATSULayoutOperationCallbackStatusHandled = 0x00000000,
   kATSULayoutOperationCallbackStatusContinue = 0x00000001
};
Constants
kATSULayoutOperationCallbackStatusHandled

Specifies that your callback function has handled the operation which triggered the callback. This indicates to ATSUI that it does not need to perform any further processing for the layout operation.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSULayoutOperationCallbackStatusContinue

Specifies that your callback function has not handled the operation which triggered the callback. This indicates to ATSUI that needs to perform its own processing for the layout operation.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

Discussion

You must return one of these status values from your ATSUDirectLayoutOperationOverrideProcPtr callback function to indicate to ATSUI whether or not your callback handled the layout operation.

Layout Operation Selectors

Specify a layout operation.

typedef UInt32 ATSULayoutOperationSelector;
enum {
   kATSULayoutOperationNone      = 0x00000000,
   kATSULayoutOperationJustification = 0x00000001,
   kATSULayoutOperationMorph     = 0x00000002,
   kATSULayoutOperationKerningAdjustment = 0x00000004,
   kATSULayoutOperationBaselineAdjustment = 0x00000008,
   kATSULayoutOperationTrackingAdjustment = 0x00000010,
   kATSULayoutOperationPostLayoutAdjustment = 0x00000020,
   kATSULayoutOperationAppleReserved = (unsigned long)xFFFFFFC0
};
Constants
kATSULayoutOperationNone

Specifies that no layout operation is currently selected.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSULayoutOperationJustification

Specifies the justification operation.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSULayoutOperationMorph

Specifies the character-morphing operation.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSULayoutOperationKerningAdjustment

Specifies the kerning-adjustment operation.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSULayoutOperationBaselineAdjustment

Specifies the baseline-adjustment operation.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSULayoutOperationTrackingAdjustment

Specifies the tracking-adjustment operation.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSULayoutOperationPostLayoutAdjustment

Specifies the period of time after ATSUI has completed its layout operations.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSULayoutOperationAppleReserved

This selector is reserved for future use.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

Discussion

You can use layout operation selectors to specify to ATSUI which operations to override. These selectors can also be passed from ATSUI to your application to indicate which operation is currently in progress.

Line Alignment Selectors

Specify the alignment of text relative to the margins in a line of text or in an entire text layout object.

#define kATSUStartAlignment ((Fract) 0x00000000L)
#define kATSUEndAlignment ((Fract) 0x40000000L)
#define kATSUCenterAlignment ((Fract) 0x20000000L)
Constants
kATSUStartAlignment

Specifies that horizontal text should be drawn to the right of the left margin (that is, its left edge coincides with the text layout object’s position plus text width). Vertical text should be drawn below the top margin.

kATSUEndAlignment

Specifies that horizontal text should be drawn to the left of the right margin. Vertical text should be drawn above the bottom margin.

kATSUCenterAlignment

Specifies that horizontal text should be drawn between the left and right margins with an equal amount of space on either side. Vertical text should be drawn between the top and bottom margins with an equal amount of space on either side.

Discussion

You can use one of these constants to set or obtain the alignment of text relative to the margins in a line of text or in an entire text layout object; see the functions ATSUSetLayoutControls, ATSUSetLineControls, ATSUGetLayoutControl, and ATSUGetLineControl, respectively.

Line Height and Font Tracking Selectors

Specify how to determine line height and whether to turn off font tracking.

enum {
   kATSUseGlyphAdvance = 0x7FFFFFFF,
   kATSUseLineHeight = 0x7FFFFFFF,
   kATSNoTracking = (long)x80000000
};
Constants
kATSUseGlyphAdvance

Specifies that ATSUI use the natural glyph advance value in a line or entire text layout object.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSUseLineHeight

Specifies that ATSUI use the natural line ascent and descent values dictated by the font and pixel size to determine line ascent and descent in a line or entire text layout object.

Available in OS X v10.0 and later.

Declared in ATSLayoutTypes.h.

kATSNoTracking

A value of type negativeInfinity that indicates that font tracking should be off.

Available in OS X v10.0 and later.

Declared in ATSLayoutTypes.h.

Discussion

You use line height selectors to set line ascent and descent text layout attributes. You can set the line ascent text layout attribute for a line or an entire text layout object by passing the kATSULineAscentTag tag to the functions ATSUSetLineControls and ATSUSetLayoutControls, respectively. You can set the line descent text layout attribute for a line or an entire text layout object by passing the kATSULineDescentTag tag to the functions ATSUSetLineControls and ATSUSetLayoutControls, respectively.

Line Justification Selectors

Specify the degree of line justification for a single line or an entire text layout object.

#define kATSUNoJustification        ((Fract) 0x00000000L)
#define kATSUFullJustification      ((Fract) 0x40000000L)
Constants
kATSUNoJustification

Indicates no justification.

kATSUFullJustification

Full justification between the text margins. White space is “stretched” to make the line extend to both text margins.

Discussion

You can set the line justification text layout attribute for a line or an entire text layout object by passing the kATSULineJustificationFactorTag tag the functions ATSUSetLineControls and ATSUSetLayoutControls, respectively.

Line Layout Attribute Tags

Specify line layout attributes to be applied at the line level.

typedef UInt32 ATSLineLayoutOptions;
enum {
   kATSLineNoLayoutOptions       = 0x00000000,
   kATSLineIsDisplayOnly         = 0x00000001,
   kATSLineHasNoHangers          = 0x00000002,
   kATSLineHasNoOpticalAlignment = 0x00000004,
   kATSLineKeepSpacesOutOfMargin = 0x00000008,
   kATSLineNoSpecialJustification = 0x00000010,
   kATSLineLastNoJustification   = 0x00000020,
   kATSLineFractDisable          = 0x00000040,
   kATSLineImposeNoAngleForEnds  = 0x00000080,
   kATSLineFillOutToWidth        = 0x00000100,
   kATSLineTabAdjustEnabled      = 0x00000200,
   kATSLineIgnoreFontLeading     = 0x00000400,
   kATSLineApplyAntiAliasing     = 0x00000800,
   kATSLineNoAntiAliasing        = 0x00001000,
   kATSLineDisableNegativeJustification = 0x00002000,
   kATSLineDisableAutoAdjustDisplayPos = 0x00004000,
   kATSLineUseQDRendering        = 0x00008000,
   kATSLineDisableAllJustification = 0x00010000,
   kATSLineDisableAllGlyphMorphing = 0x00020000,
   kATSLineDisableAllKerningAdjustments = 0x00040000,
   kATSLineDisableAllBaselineAdjustments = 0x00080000,
   kATSLineDisableAllTrackingAdjustments = 0x00100000,
   kATSLineDisableAllLayoutOperations = kATSLineDisableAllJustification
|
   kATSLineDisableAllGlyphMorphing |
   kATSLineDisableAllKerningAdjustments |
   kATSLineDisableAllBaselineAdjustments |
   kATSLineDisableAllTrackingAdjustments,
   kATSLineUseDeviceMetrics      = 0x01000000,
   kATSLineBreakToNearestCharacter = 0x02000000,
   kATSLineAppleReserved         = (unsigned long)xFCE00000};
Constants
kATSLineNoLayoutOptions

Specifies not to apply any options.

Available i n ATSUI 1.0 and later.

Declared in ATSLayoutTypes.h.

kATSLineIsDisplayOnly

This line option is no longer used. Instead use kATSLineUseDeviceMetrics.

Available in OS X v10.0 and later.

Declared in ATSLayoutTypes.h.

kATSLineHasNoHangers

Specifies not to form hanging punctuation on the line. If the bit specified by this mask is set, the automatic hanging punctuation in the text layout object is overridden. The value in this bit overrides any adjustment to hanging punctuation set for a style run inside the text layout object using the style run attribute tags kATSUForceHangingTag or kATSUHangingInhibitFactorTag.

Declared in ATSLayoutTypes.h.

Available in ATSUI 1.0 and later.

kATSLineHasNoOpticalAlignment

Specifies not to perform optical alignment on the line. Optical alignment adjusts characters at the text margin so that they appear to be properly aligned; strict alignment can often cause the illusion of a ragged edge. The value in this bit overrides any adjustment to optical alignment set for a style run inside the text layout object using the style run attribute tag kATSUNoOpticalAlignmentTag.

Declared in ATSLayoutTypes.h.

Available in ATSUI 1.0 and later.

kATSLineKeepSpacesOutOfMargin

Specifies that the trailing white spaces at the end of a line of justified text should be placed outside the margin.

Available in ATSUI 1.0 and later.

Declared in ATSLayoutTypes.h.

kATSLineNoSpecialJustification

Specifies not to perform post-compensation justification on the line, even if such processing is necessary. This flag cannot be set for a single line of a text layout object. The value in this bit overrides any adjustment to the postcompensation actions set for a style run using the style run attribute tag kATSUNoSpecialJustificationTag.

Declared in ATSLayoutTypes.h.

Available in ATSUI 1.0 and later.

kATSLineLastNoJustification

Specifies not to justify a line if it is the last line of a justified text layout object. This flag is meaningless when setting a line’s text layout attributes.

Available in ATSUI 1.0 and later.

Declared in ATSLayoutTypes.h.

kATSLineFractDisable

Specifies to position of the text in the line or text layout object relative to fractional absolute positions, which are uncorrected for device display. This provides the ideal position of laid-out text and is useful for scaling text onscreen. This origin is also used to get the width of the typographic bounding rectangle when you call the function ATSUGetUnjustifiedBounds.

Declared in ATSLayoutTypes.h.

Available in ATSUI 1.1 and later.

kATSLineImposeNoAngleForEnds

Specifies to draw the carets on the far right and left sides of an unrotated line as vertical, no matter what the angle of text.

Available in ATSUI 1.1 and later.

Declared in ATSLayoutTypes.h.

kATSLineFillOutToWidth

Specifies to extend highlighting to both ends of a line, regardless of caret locations. This option does not effect the caret locations. This is provided for your convenience to extend your highlighting to the full width of the line.

Available in ATSUI 1.1 and later.

Declared in ATSLayoutTypes.h.

kATSLineTabAdjustEnabled

Specifies to automatically adjust the tab character width so that it fits the specified line width. If you are using ATSUI’s tab functions—ATSUSetTabArray and ATSUGetTabArray to define a tab rule you do not need to use this selector. The selector is useful if you are handling your own tabs and only applies if the tab is at the end of a line (backing store). You must set this bit to ensure that highlighting is done correctly across tab stops. To ensure this, you should also set the bit specified by the kATSLineImposeNoAngleForEnds mask constant.

Declared in ATSLayoutTypes.h.

Available in ATSUI 1.2 and later.

kATSLineIgnoreFontLeading

Specifies to ignore any leading value specified by a font.

Available in ATSUI 2.3 and later.

Declared in ATSLayoutTypes.h.

kATSLineApplyAntiAliasing

Specifies that Apple Type Services should produce antialiased glyph images even if system preferences or Quartz settings indicate otherwise.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineNoAntiAliasing

Specifies that Apple Type Services should turn-off antialiasing glyph imaging even if system preferences or Quartz settings indicate otherwise. This option negates the kATSLineApplyAntiAliasing bit if it is set.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineDisableNegativeJustification

Specifies to allow glyph positions to extend beyond the line's assigned width if the line width is not sufficient to hold all its glyphs. This ensures that negative justification is not used.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineDisableAutoAdjustDisplayPos

Specifies not to automatically adjust individual character positions when rendering lines that have any integer glyph positioning, whether the integer glyph positioning is due to non-antialiased characters or though the use of the selector kATSLineFractDisable.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineUseQDRendering

Specifies to use QuickDraw to render a line of text instead of the default ATSUI rendering. With Mac OS X version 10.2, ATSUI renders text through Quartz, even if you do not attach a CGContext to a text layout object. In the default case, ATSUI retrieves the internal canonical CGContext of the current port, and renders to that port using Quartz at an antialiasing setting that simulates QuickDraw rendering. That is, a 4-bit pixel-aligned antialiasing. Because the default setting gives you simulated QuickDraw rendering, you should use the tag kATSLineUseQDRendering only if you must have backward compatibility. With Mac OS X version 10.3, this option no longer does anything different from not declaring a CGContext.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineDisableAllJustification

Specifies not to perform any justification operations on the line.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineDisableAllGlyphMorphing

Specifies not to perform any glyph-morphing operations on the line.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineDisableAllKerningAdjustments

Specifies not to perform any kerning-adjustment operations on the line.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineDisableAllBaselineAdjustments

Specifies not to perform any baseline-adjustment operations on the line.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineDisableAllTrackingAdjustments

Specifies not to perform any tracking-adjustment operations on the line.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineDisableAllLayoutOperations

Specifies to turn off all layout adjustments for this line.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineUseDeviceMetrics

Specifies to used rounded device metrics instead of fractional path metrics. This optimizes display of text and should be used only in cases in which the text is displayed onscreen as opposed to printed or output to PDF. If you use this option to display text onscreen as well as to print or create a PDF, you will get different results between the two types of output. This attribute is not recommended for Quartz antialiased text.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSLineBreakToNearestCharacter

Specifies that line breaking should occur at the nearest character, not word. This could cause a word to be split over multiple lines.

Available in Mac OS X version 10.3 and later.

Declared in ATSLayoutTypes.h.

kATSLineAppleReserved

This selector is reserved by Apple. If you try to use it, ATSUI returns the kATSUInvalidAttributeValueEr result code.

Available in ATSUI 1.1 and later.

Declared in ATSLayoutTypes.h.

Discussion

You can use a constant of type ATSLineLayoutOptions to set or obtain the line layout options in a line of text or for an entire text layout object; see the functions ATSUSetLineControls and ATSUSetLayoutControls, respectively.

Line Layout Width Selector

Specifies a line width.

enum {
   kATSUUseLineControlWidth = 0X7FFFFFFF
};
Constants
kATSUUseLineControlWidth

Indicates that the functions ATSUBreakLine or ATSUBatchBreakLines should use the previously set line width attribute for the current line to determine how many characters can fit on the line. If no line width has been set for the line, these functions use the line width set for the text layout object; if not set, these functions use the default line width value.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Discussion

You can pass this constant to the functions ATSUBreakLine or ATSUBatchBreakLines to indicate that the function should use the line width previously set for that line to calculate the soft line break. If no line width has been set for the line, these functions use the line width set for the text layout object.

No Selectors Option

Specifies no selectors are chosen.

enum {
   kATSUNoSelector = 0x0000FFFF
};
Constants
kATSUNoSelector

Specifies no selectors are chosen.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Style Comparison Options

Specify how two style objects compare to each other.

typedef UInt16 ATSUStyleComparison;
enum {
   kATSUStyleUnequal = 0,
   kATSUStyleContains = 1,
   kATSUStyleEquals = 2,
   kATSUStyleContainedBy = 3
};
Constants
kATSUStyleUnequal

Specifies that styles are unequal.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleContains

Specifies that style 1 contains style 2 as a proper subset.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleEquals

Specifies that style 1 equals style 2.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleContainedBy

Specifies that style 1 is contained by style 2.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Discussion

The function ATSUCompareStyles returns a constant of type ATSUStyleComparison to indicate whether two style objects are the same, different, or a subset of one another.

Style Line Count Types

Specifies how many lines to draw for a given style type.

typedef UInt16 ATSUStyleLineCountType;
enum {
   kATSUStyleSingleLineCount     = 1,
   kATSUStyleDoubleLineCount     = 2
};
Constants
kATSUStyleSingleLineCount

Specifies to use a single line.

Available in OS X v10.3 and later.

Declared in ATSUnicodeTypes.h.

kATSUStyleDoubleLineCount

Specifies to use a double line.

Available in OS X v10.3 and later.

Declared in ATSUnicodeTypes.h.

Discussion

These constants are available in Mac OS X version 10.3 and later. Currently only the underline and strike through styles support this type.

Style Rendering Options

Specify rendering options for a style object.

typedef UInt32 ATSStyleRenderingOptions;
enum {
   kATSStyleNoOptions            = 0x00000000,
   kATSStyleNoHinting            = 0x00000001,
   kATSStyleApplyAntiAliasing    = 0x00000002,
   kATSStyleNoAntiAliasing       = 0x00000004,
   kATSStyleAppleReserved        = (unsigned long)xFFFFFFF8,
   kATSStyleApplyHints           = kATSStyleNoOptions
};
Constants
kATSStyleNoOptions

Specifies no options are set.

Available in OS X v10.0 and later.

Declared in ATSLayoutTypes.h.

kATSStyleNoHinting

Specifies that Apple Type Services (ATS) should produce unhinted glyph outlines. The default behavior is for ATS to produce is hinted glyph outlines.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSStyleApplyAntiAliasing

Specifies that Apple Type Services should produce antialiased glyph images even if system preferences or Quartz 2D settings indicate otherwise.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSStyleNoAntiAliasing

Specifies that Apple Type Services should turn-off antialiasing glyph imaging even if system preferences or Quartz 2D settings indicate otherwise. This selector negates the kATSStyleApplyAntiAliasing selector if is set.

Available in OS X v10.2 and later.

Declared in ATSLayoutTypes.h.

kATSStyleAppleReserved

This selector is reserved by Apple. If you try to use it, you will get an invalid value error.

Available in OS X v10.0 and later.

Declared in ATSLayoutTypes.h.

kATSStyleApplyHints

Specifies that Apple Type Services should produce hinted glyph outlines. This selector is obsolete; do not use it. It is listed here only for backwards compatibility.

Available in OS X v10.0 and later.

Declared in ATSLayoutTypes.h.

Discussion

You can set style rendering attributes for a style object (ATSUStyle) by using the kATSUStyleRenderingOptionsTag attribute tag and calling the function ATSUSetAttributes. Style rendering options provide fine control over how a style is rendered.

Tab Positioning Options

Specify text positioning for ATSUI tab stops.

typedef UInt16 ATSUTabType;
enum {
   kATSULeftTab                  = 0,
   kATSUCenterTab                = 1,
   kATSURightTab                 = 2,
   kATSUDecimalTab               = 3,
   kATSUNumberTabTypes           = 4
};
Constants
kATSULeftTab

Specifies that the left side of the tabbed text should be flush against the tab stop.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

kATSUCenterTab

Specifies that the tabbed text should be centered on the tab stop.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

kATSURightTab

Specifies that the right side of the tabbed text should be flush against the tab stop.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

kATSUDecimalTab

Specifies that the decimal point of a value should be centered on the tab stop. To set a decimal tab, use the tag kATSULineDecimalTabCharacterTag. This tag specifies the current setting for the decimal separator, and affects the behavior of decimal tabs for a text layout (not an individual line). The default character that is used as a separator is set by the user in System Preferences.

Declared in ATSUnicodeTypes.h.

Available in Mac OS X version 10.3 and later.

kATSUNumberTabTypes

Specifies the number of valid tab types.

Available in OS X v10.2 and later.

Declared in ATSUnicodeTypes.h.

Discussion

You can use tab type constants to set a tab ruler. The default value is the user setting in System Preferences.

Text Buffer Convenience Constants

Refer to the beginning or end of a text buffer.

enum {
   kATSUFromTextBeginning = (unsigned long)xFFFFFFFF,
   kATSUToTextEnd = (unsigned long)xFFFFFFFF,
   kATSUFromPreviousLayout = (unsigned long)xFFFFFFFE,
   kATSUFromFollowingLayout      = (unsigned long)xFFFFFFFD
};
Constants
kATSUFromTextBeginning

Indicates that the range of text to be operated on should start at the beginning of the text layout object’s text buffer.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUToTextEnd

Indicates that the range of text to be operated on should span to the end of the text layout object’s text buffer.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUFromPreviousLayout

Used for bidirectional cursor movement between paragraphs in the functions ATSURightwardCursorPosition and ATSULeftwardCursorPosition.

Available in OS X v10.3 and later.

Declared in ATSUnicodeTypes.h.

kATSUFromFollowingLayout

Used for bidirectional cursor movement between paragraphs in the functions ATSURightwardCursorPostion and ATSULeftwardCursorPosition.

Available in OS X v10.3 and later.

Declared in ATSUnicodeTypes.h.

Discussion

Do not pass these constants to functions which do not explicitly state they will accept them.

ATSUI functions that draw, highlight, measure, or otherwise operate on text do so to a range of text, not the entire text buffer (unless you specify the entire buffer). You specify the beginning of this range with an edge offset of type UniCharArrayOffset, and demarcate the end of the range by indicating a length of type UniCharCount.

If you want the range to start at the beginning of the text buffer, you should pass the constant kATSUFromTextBeginning. If you want the range to span the end of the text buffer, you should pass the constant kATSUToTextEnd. If you want the range to span the entire text buffer, pass kATSUFromTextBeginning in conjunction with the constant kATSUToTextEnd. For bidirectional text, you can specify the previous layout by passing the constant kATSUFromPreviousLayout and the following layout by passing the constant kATSUFromFollowingLayout.

Unflattened Style Run Data Options

Specify options to use when unflattening ATSUI style run data.

typedef UInt32 ATSUUnflattenStyleRunOptions;
enum {
   kATSUUnflattenOptionNoOptionsMask = 0x00000000
};
Constants
kATSUUnflattenOptionNoOptionsMask

Specifies that no options are to be used.

Discussion

Additional options may be added in the future.

Vertical Character Types

Specify the glyph orientation of font tracking settings or a style run.

typedef UInt16 ATSUVerticalCharacterType;
enum {
   kATSUStronglyHorizontal = 0,
   kATSUStronglyVertical = 1
};
Constants
kATSUStronglyHorizontal

Specifies a horizontal orientation.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

kATSUStronglyVertical

Specifies a vertical orientation.

Available in OS X v10.0 and later.

Declared in ATSUnicodeTypes.h.

Discussion

You can pass a constant of type ATSUVerticalCharacterType to the functions ATSUCountFontTracking and ATSUGetIndFontTracking to specify the glyph orientation of font tracking settings, since font tracking settings differ depending upon glyph orientations.

You can also use one of these constants to set or obtain the glyph orientation of a style run; see the functions ATSUSetAttributes and ATSUGetAttribute, respectively.

Result Codes

The most common result codes returned by Apple Type Services for Unicode Imaging are listed below.

Result CodeValueDescription
kATSUInvalidTextLayoutErr -8790

The ATSUI text layout object is not initialized or is in an otherwise invalid state.

Available beginning with ATSUI 1.0.

kATSUInvalidStyleErr -8791

The ATSUI style object is not initialized or in an otherwise invalid state.

Available beginning with ATSUI 1.0.

kATSUInvalidTextRangeErr -8792

The text range extends beyond the limits of the text layout object’s text range.

Available beginning with ATSUI 1.0.

kATSUFontsMatched -8793

One or more characters cannot be rendered with the assigned font, but can be rendered with a substitute font from among those currently active.

Available beginning with ATSUI 1.0.

kATSUFontsNotMatched -8794

One or more characters can neither be rendered with the assigned font nor with any other currently active font.

Available beginning with ATSUI 1.0.

kATSUNoCorrespondingFontErr -8795

The font ID corresponds to an existing font that isn’t available to ATSUI.

Available beginning with ATSUI 1.0.

kATSUInvalidFontErr -8796

The font ID does not correspond to any installed font or ATSUI is unable to obtain the font data (as in the case of a protected font).

Available beginning with ATSUI 1.0.

kATSUInvalidAttributeValueErr -8797

The attribute value is invalid or undefined.

Available beginning with ATSIU 1.0.

kATSUInvalidAttributeSizeErr -8798

The allocated attribute value size is less than required.

Available beginning with ATSUI 1.0.

kATSUInvalidAttributeTagErr -8799

The tag is an ATSUI-reserved value or the wrong type of attribute tag (that is, a style run attribute tag instead of text layout attribute tag and vice versa).

Available beginning with ATSUI 1.0.

kATSUInvalidCacheErr -8800

Indicates an attempt to read style data from an invalid cache (that is, the format of the cached data does not match that used by ATSUI or the cached data is corrupt).

Available beginning with ATSUI 1.0.

kATSUNotSetErr -8801

The ATSUI style object’s attribute, font feature, font variation is not set; the ATSUI text layout object or single line’s attribute is not set; or a font name is not set.

Available beginning with ATSUI 1.0.

kATSUNoStyleRunsAssignedErr -8802

No style runs are assigned to the ATSUI text layout object.

Available beginning with ATSUI 1.1.

kATSUQuickDrawTextErr -8803

The QuickDraw function DrawText encountered an error rendering or measuring a line of text.

Available beginning with ATSUI 1.1.

kATSULowLevelErr -8804

Apple Type Services (ATS) encountered an error while performing an operation requested by ATSUI.

Available beginning with ATSUI 1.1.

kATSUNoFontCmapAvailableErr -8805

The 'CMAP' table cannot be accessed or synthesized for a font.

Available beginning with ATSUI 1.1.

kATSUNoFontScalerAvailableErr -8806

There is no font scaler available for a font.

Available beginning with ATSUI 1.1.

kATSUCoordinateOverflowErr -8807

The coordinate values passed to the function caused a coordinate overflow (greater than 32 KB).

Available beginning with ATSUI 1.1.

kATSULineBreakInWord -8808

The function ATSUBreakLine performed a line break within a word.

Available beginning with ATSUI 1.2.

kATSUBusyObjectErr -8809

An ATSUI object is being used by another thread.

Available in OS X v10.1 and later.

kATSUInvalidFontFallbacksErr -8900

The ATSUFontFallback object is not initialized or is otherwise in an in valid state.

Available in OS X v10.1 and later.

kATSUUnsupportedStreamFormatErr -8901

The data-flattening format is invalid or is not supported by this version of ATSUI.

Available in OS X v10.2 and later.

kATSUBadStreamErr -8902

The data is not formatted as specified by the data-flattening format constant, or the data is corrupt.

Available in OS X v10.2 and later.

kATSUOutputBufferTooSmallErr -8903

The output buffer is too small to contain the data output by the function.

Available in OS X v10.2 and later.

kATSUInvalidCallInsideCallbackErr -8904

Your callback is making a call that could cause an infinite recursion.

Available in OS X v10.2 and later.

kATSULastErr -8959

No ATSUI-related result codes may exceed this value. Result code values between kATSUInvalidTextLayoutErr and kATSULastErr are reserved.

Available beginning with ATSUI 1.0.

Gestalt Constants

You can check for version and feature availability information by using the ATSUI attribute and version selectors defined in the Gestalt Manager. For more information see Gestalt Manager Reference.