Retired Document

Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.

QuickDraw Text Reference (Not Recommended)

Framework	ApplicationServices/ApplicationServices.h
Declared in	Quickdraw.h QuickdrawText.h

Overview

You can use the QuickDraw text routines to measure and draw text ranging in complexity from a single glyph to a line of justified text containing multiple languages and styles. In addition to measuring and drawing text, the QuickDraw text routines also help you to determine which characters to highlight and where to position the caret to mark the insertion point. These routines translate pixel locations into byte offsets and vice versa.

To understand the routines described in this document, it is helpful to be familiar with the other parts of QuickDraw. It is also helpful to be familiar with the Font Manager, because of the close relationship between QuickDraw and the Font Manager. To understand the tasks involved in text layout, you should also be acquainted with the Text Utilities and the Script Manager.

Carbon supports the majority of QuickDraw Text.

Functions by Task

Determining the Caret Position, and Selecting and Highlighting Text

Drawing Text

Laying Out a Line of Text

Measuring Text

Setting Text Characteristics

Truncating Strings and Breaking Lines

Working With Universal Procedure Pointers

Callbacks

StyleRunDirectionProcPtr

Defines a pointer to a style run direction callback function that calculates, for a style run identified by number, the direction of that style run.

typedef Boolean (*StyleRunDirectionProcPtr)
(
   short styleRunIndex,
   void * dirParam
);

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

Boolean StyleRunDirectionProcPtr (
   short styleRunIndex,
   void * dirParam
);

Parameters

styleRunIndex: A value that identifies the style run whose direction is needed.
dirParam: A pointer to an application-defined parameter block that contains the font and script information for each style run in the text. The contents of this parameter block are used to determine the direction of the style run. Because of the relationship between the font family ID and the script code, the font family ID can be used to determine the text direction.

Return Value

A Boolean value that is TRUE for right-to-left text direction, FALSE for left-to-right.

Discussion

To fill the ordering array (type FormatOrder) for style runs on a line, the GetFormatOrder function calls MyStyleRunDirectionCallback for each style run numbered from firstFormat to lastFormat. GetFormatOrder passes MyStyleRunDirectionCallback a number identifying the style run in storage order, and a pointer to the parameter information block, dirParam, that contains the font and style information for the style run. Given dirParam and a style run identifier, the application-defined MyStyleRunDirectionCallback function should be able to determine the style run direction.

You should store your style run information in a way that makes it convenient for MyStyleRunDirectionCallback. One obvious way to do this is to declare a structure type for style runs that allows you to save things like font style, font family ID, script number, and so forth. You then can store these structures in an array. When the time comes for GetFormatOrder to fill the ordering array, MyStyleRunDirectionCallback can consult the style run array for direction information for each of the numbered style runs in turn.

For more information, see GetFormatOrder.

When you provide the Component Manager with a pointer to your function, you should use a universal procedure pointer (UPP). The definition of the UPP data type for your file identification function is as follows:

typedef (StyleRunDirectionProcPtr) StyleRunDirectionUPP;

Before using your style run direction callback function, you must first create a new universal procedure pointer to it, using the NewStyleRunDirectionUPP function, as shown here:

StyleRunDirectionUPP MyStyleRunDirectionUPP;

MyStyleRunDirectionUPP = StyleRunDirectionUPP(&MyStyleRunDirectionCallback)

You then pass MyStyleRunDirectionUPP to the function GetFormatOrder. If you wish to call your own callback function, you can use the InvokeStyleRunDirectionUPP function:

direction = InvokeStyleRunDirectionUPP(styleRunIndex, &paramInfo, MyStyleRunDirectionUPP)

When you are finished using your callback function, you should dispose of the universal procedure pointer associated with it, using the DisposeStyleRunDirectionUPP function.

DisposeStyleRunDirectionUPP(MyStyleRunDirectionUPP);

Availability

Available in OS X v10.0 through OS X v10.6.

Declared In

QuickdrawText.h

Data Types

FontInfo

Contains font metric information.

struct FontInfo {
   short ascent;
   short descent;
   short widMax;
   short leading;
};
typedef struct FontInfo FontInfo;

Fields

ascent: The measurement, in pixels, from the baseline to the ascent line of the font.
descent: The measurement, in pixels, from the baseline to the descent line of the font.
widMax: The width, in pixels, of the largest glyph in the font.
leading: The measurement, in pixels, from the descent line to the ascent line below it.

Discussion

The FontInfo data type defines a font information structure. The GetFontInfo function uses the font information structure to return measurement information based on the font of the current graphics port. If the current font has an associated font, as do Arabic and Hebrew, GetFontInfo returns information based on both fonts. The font information structure contains the ascent, the descent, the width of the largest glyph, and the leading for a given font. The StdTxMeas function also uses a structure of type FontInfo to return information about the current font.

Availability

Available in OS X v10.0 and later.

Declared In

Quickdraw.h

FormatOrder

Contains and array of display orders for style runs.

typedef  FormatOrder[1];

Discussion

The GetFormatOrder function fills the supplied format order array with the display order of each style run.

Availability

Available in OS X v10.0 through OS X v10.6.

Declared In

QuickdrawText.h

StyleRunDirectionUPP

Defines a universal procedure pointer to a style run direction callback.

typedef StyleRunDirectionProcPtr StyleRunDirectionUPP;

Discussion

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

Availability

Available in OS X v10.0 through OS X v10.6.

Declared In

QuickdrawText.h

Constants

Caret Direction Constants

Specify a caret position.

enum {
   leftCaret = 0,
   rightCaret = -1,
   kHilite = 1
};

Constants

leftCaret

Place caret for left-to-right text direction.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

rightCaret

Place caret for right-to-left text direction.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

kHilite

Specifies that the caret position should be determined according to the primary line direction, based on the value of SysDirection.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

Discussion

You can use these constants to specify a value for direction, as used in the CharToPixel function.

Truncation Status Values

Returned as result codes for the functions TruncString and TruncText.

enum {
   notTruncated = 0,
   truncated = 1,
   truncErr = -1,
   smNotTruncated = 0,
   smTruncated = 1,
   smTruncErr = -1
};

Constants

notTruncated

Specifies that truncation is not necessary.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

truncated

Specifies that truncation was performed.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

truncErr

Specifies a general error occurred.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smNotTruncated

Specifies that truncation is not necessary. This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smTruncated

Specifies that truncation was performed. This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smTruncErr

Specifies a general error occurred. This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

Style Line Break Values

Specify a line break.

typedef SInt8 StyledLineBreakCode;
enum {
   smBreakWord = 0,
   smBreakChar = 1,
   smBreakOverflow = 2
};

Constants

smBreakWord

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smBreakChar

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smBreakOverflow

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

Obsolete Caret Placement Values

Specify where to place a caret.

enum {
   smLeftCaret = 0,
   smRightCaret = -1,
   smHilite = 1
};

Constants

smLeftCaret

Specifies to place caret for left block. This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smRightCaret

Specifies to place caret for right block. This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smHilite

Specifies the direction is TESysJust. This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

Style Run Position Constants

Specify style run positions.

typedef short JustStyleCode;
enum {
   onlyStyleRun = 0,
   leftStyleRun = 1,
   rightStyleRun = 2,
   middleStyleRun = 3,
   smOnlyStyleRun = 0,
   smLeftStyleRun = 1,
   smRightStyleRun = 2,
   smMiddleStyleRun = 3
};

Constants

onlyStyleRun

This is the only style run on the line.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

leftStyleRun

This is the leftmost of multiple style runs on the line.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

rightStyleRun

This is the rightmost of multiple style runs on the line

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

middleStyleRun

The line and this one is interior: neither leftmost nor rightmost.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smOnlyStyleRun

This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smLeftStyleRun

This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smRightStyleRun

This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smMiddleStyleRun

This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

Discussion

Use one of the following constants (defined as type JustStyleCode) in the styleRunPosition parameter for PortionLine DrawJustified, MeasureJustified, CharToPixel, and PixelToChar.

txFlag Constants

Specify constants for txFlags.

enum {
   tfAntiAlias = 1 << 0,
   tfUnicode = 1 << 1
};

Constants

tfAntiAlias

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

tfUnicode

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

Discussion

These used to be the pad field after txFace.

Truncation Positions

Specify where to truncate a string.

typedef  TruncCode;
enum {
   truncEnd = 0,
   truncMiddle = 0x4000,
   smTruncEnd = 0,
   smTruncMiddle = 0x4000
};

Constants

truncEnd

Truncate at end.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

truncMiddle

Truncate in middle.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smTruncEnd

Truncate at end. This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

smTruncMiddle

Truncate in middle. This is obsolete.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawText.h.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.