Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

TextEdit Reference (Not Recommended)

Framework
Carbon/Carbon.h
Declared in
TSMTE.h
TextEdit.h

Important: The information in this document is obsolete and should not be used for new development.

Overview

TextEdit was originally designed to handle editable text items in dialog boxes and other parts of the Mac OS system software. Although TextEdit was enhanced to provide more text-handling support, especially in its handling of multi-script text, it retained some of its original limitations. TextEdit was never intended to manipulate lengthy documents or text requiring more than rudimentary formatting.

TextEdit has been deprecated for deployment targets Mac OS X version 10.4 and later. The replacement API is Multilingual Text Engine (MLTE). MLTE offers additional features such as Unicode text editing, document-wide tabs, full justification of text, support for more than 32 KB of text, built-in scroll bar handling, built-in printing support, support for inline input, support for the advanced font features of Apple Type Services for Unicode Imaging (ATSUI), and support for multiple levels of undo.

You should use MLTE to replace TextEdit functions in your existing applications. With MLTE, you can significantly reduce the number of lines in your code because MLTE handles most of the low-level tasks you had to code in the past. MLTE provides a quick and easy solution for static display of Unicode text and for creating Unicode-compliant text-editing fields within an application. For more information, see Handling Unicode Text Editing With MLTE.

Functions by Task

Activating and Deactivating an Edit Structure

Using Additional TextEdit Features

Checking, Setting, and Replacing Styles

Customizing TextEdit

Displaying and Scrolling Text

Initializing TextEdit, Creating an Edit Structure, and Disposing of an Edit Structure

Managing the TextEdit Private Scrap

Modifying the Text of an Edit Structure

Setting and Getting an Edit Structure’s Text and Character Attribute Information

Setting the Caret and Selection Range

Using Byte Offsets and Corresponding Points

Handling TSM Dialogs

Working With UPPs for TextEdit Callback Functions

Callbacks

CaretHookProcPtr

Defines a pointer to a caret-hook callback.

typedef void (*CaretHookProcPtr) (
   const Rect * r,
   TEPtr pTE
);

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

void CaretHookProcPtr (
   const Rect * r,
   TEPtr pTE
);

Availability
Declared In
TextEdit.h

DrawHookProcPtr

Defines a pointer to a draw-hook callback.

typedef void (*DrawHookProcPtr) (
   unsigned short textOffset,
   unsigned short drawLen,
   void * textBufferPtr,
   TEPtr pTE,
   TEHandle hTE
);

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

void DrawHookProcPtr (
   unsigned short textOffset,
   unsigned short drawLen,
   void * textBufferPtr,
   TEPtr pTE,
   TEHandle hTE
);

Availability
Declared In
TextEdit.h

EOLHookProcPtr

Defines a pointer to an EOL-hook callback.

typedef Boolean (*EOLHookProcPtr) (
   char theChar,
   TEPtr pTE,
   TEHandle hTE
);

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

Boolean EOLHookProcPtr (
   char theChar,
   TEPtr pTE,
   TEHandle hTE
);

Availability
Declared In
TextEdit.h

HighHookProcPtr

Defines a pointer to a high-hook callback.

typedef void (*HighHookProcPtr) (
   const Rect * r,
   TEPtr pTE
);

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

void HighHookProcPtr (
   const Rect * r,
   TEPtr pTE
);

Availability
Declared In
TextEdit.h

HitTestHookProcPtr

Defines a pointer to a hit-test hook callback.

typedef Boolean (*HitTestHookProcPtr) (
   unsigned short styleRunLen,
   unsigned short styleRunOffset,
   unsigned short slop,
   void * textBufferPtr,
   TEPtr pTE,
   TEHandle hTE,
   unsigned short * pixelWidth,
   unsigned short * charOffset,
   Boolean * pixelInChar
);

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

Boolean HitTestHookProcPtr (
   unsigned short styleRunLen,
   unsigned short styleRunOffset,
   unsigned short slop,
   void * textBufferPtr,
   TEPtr pTE,
   TEHandle hTE,
   unsigned short * pixelWidth,
   unsigned short * charOffset,
   Boolean * pixelInChar
);

Availability
Declared In
TextEdit.h

NWidthHookProcPtr

Defines a pointer to a width-hook callback.

typedef unsigned short (*NWidthHookProcPtr) (
   unsigned short styleRunLen,
   unsigned short styleRunOffset,
   short slop,
   short direction,
   void * textBufferPtr,
   short * lineStart,
   TEPtr pTE,
   TEHandle hTE
);

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

unsigned short NWidthHookProcPtr (
   unsigned short styleRunLen,
   unsigned short styleRunOffset,
   short slop,
   short direction,
   void * textBufferPtr,
   short * lineStart,
   TEPtr pTE,
   TEHandle hTE
);

Availability
Declared In
TextEdit.h

TEClickLoopProcPtr

Defines a pointer to a click-loop callback.

typedef Boolean (*TEClickLoopProcPtr) (
   TEPtr pTE
);

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

Boolean TEClickLoopProcPtr (
   TEPtr pTE
);

Availability
Declared In
TextEdit.h

TEDoTextProcPtr

Defines a pointer to a do-text callback.

typedef void (*TEDoTextProcPtr) (
   TEPtr pTE,
   unsigned short firstChar,
   unsigned short lastChar,
   short selector,
   GrafPtr * currentGrafPort,
   short * charPosition
);

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

void TEDoTextProcPtr (
   TEPtr pTE,
   unsigned short firstChar,
   unsigned short lastChar,
   short selector,
   GrafPtr * currentGrafPort,
   short * charPosition
);

Availability
Declared In
TextEdit.h

TEFindWordProcPtr

Defines a pointer to a find-word callback.

typedef void (*TEFindWordProcPtr) (
   unsigned short currentPos,
   short caller,
   TEPtr pTE,
   TEHandle hTE,
   unsigned short * wordStart,
   unsigned short * wordEnd
);

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

void TEFindWordProcPtr (
   unsigned short currentPos,
   short caller,
   TEPtr pTE,
   TEHandle hTE,
   unsigned short * wordStart,
   unsigned short * wordEnd
);

Availability
Declared In
TextEdit.h

TERecalcProcPtr

Defines a pointer to a recalculation callback.

typedef void (*TERecalcProcPtr) (
   TEPtr pTE,
   unsigned short changeLength,
   unsigned short * lineStart,
   unsigned short * firstChar,
   unsigned short * lastChar
);

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

void TERecalcProcPtr (
   TEPtr pTE,
   unsigned short changeLength,
   unsigned short * lineStart,
   unsigned short * firstChar,
   unsigned short * lastChar
);

Availability
Declared In
TextEdit.h

TextWidthHookProcPtr

Defines a pointer to a width-hook callback.

typedef unsigned short (*TextWidthHookProcPtr) (
   unsigned short textLen,
   unsigned short textOffset,
   void * textBufferPtr,
   TEPtr pTE,
   TEHandle hTE
);

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

unsigned short TextWidthHookProcPtr (
   unsigned short textLen,
   unsigned short textOffset,
   void * textBufferPtr,
   TEPtr pTE,
   TEHandle hTE
);

Availability
Declared In
TextEdit.h

TSMTEPostUpdateProcPtr

Defines a pointer to a post-update callback.

typedef void (*TSMTEPostUpdateProcPtr) (
   TEHandle textH,
   long fixLen,
   long inputAreaStart,
   long inputAreaEnd,
   long pinStart,
   long pinEnd,
   long refCon
);

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

void TSMTEPostUpdateProcPtr (
   TEHandle textH,
   long fixLen,
   long inputAreaStart,
   long inputAreaEnd,
   long pinStart,
   long pinEnd,
   long refCon
);

Availability
Declared In
TSMTE.h

TSMTEPreUpdateProcPtr

Defines a pointer to a pre-udate callback.

typedef void (*TSMTEPreUpdateProcPtr) (
   TEHandle textH,
   long refCon
);

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

void TSMTEPreUpdateProcPtr (
   TEHandle textH,
   long refCon
);

Availability
Declared In
TSMTE.h

WidthHookProcPtr

Defines a pointer to a width-hook callback.

typedef unsigned short (*WidthHookProcPtr) (
   unsigned short textLen,
   unsigned short textOffset,
   void * textBufferPtr,
   TEPtr pTE,
   TEHandle hTE
);

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

unsigned short WidthHookProcPtr (
   unsigned short textLen,
   unsigned short textOffset,
   void * textBufferPtr,
   TEPtr pTE,
   TEHandle hTE
);

Availability
Declared In
TextEdit.h

Data Types

CaretHookUPP

Defines a universal procedure pointer (UPP) to a caret-hook callback.

typedef CaretHookProcPtr CaretHookUPP;

Discussion

For more information, see the description of the CaretHookUPP () callback function.

Availability
Declared In
TextEdit.h

Chars

Defines an array of characters.

typedef  char Chars[32001];

Availability
Declared In
TextEdit.h

CharsPtr

Defines a data type for a character pointer.

typedef char* CharsPtr;

Availability
Declared In
TextEdit.h

CharsHandle

Defines a handle to a character pointer.

typedef CharsPtr* CharsHandle;

Availability
Declared In
TextEdit.h

DrawHookUPP

Defines a universal procedure pointer (UPP) to a draw-hook callback.

typedef DrawHookProcPtr DrawHookUPP;

Discussion

For more information, see the description of the DrawHookUPP () callback function.

Availability
Declared In
TextEdit.h

EOLHookUPP

Defines a universal procedure pointer (UPP) to an EOL-hook callback.

typedef EOLHookProcPtr EOLHookUPP;

Discussion

For more information, see the description of the EOLHookUPP () callback function.

Availability
Declared In
TextEdit.h

HighHookUPP

Defines a universal procedure pointer (UPP) to a high-hook callback.

typedef HighHookProcPtr HighHookUPP;

Discussion

For more information, see the description of the HighHookUPP () callback function.

Availability
Declared In
TextEdit.h

HitTestHookUPP

Defines a universal procedure pointer (UPP) to a hit-test hook callback.

typedef HitTestHookProcPtr HitTestHookUPP;

Discussion

For more information, see the description of the HitTestHookUPP () callback function.

Availability
Declared In
TextEdit.h

LHHandle

Defines a handle to a line-height table pointer.

typedef LHPtr *     LHHandle;

Availability
Declared In
TextEdit.h

LHElement

Contains height and ascent information.

struct LHElement {
   short lhHeight;
   short lhAscent;
};
typedef struct LHElement LHElement;
typedef LHElement * LHPtr;

Fields
lhHeight

The line height, in points. This is the maximum value for any individual character attribute in the line.

lhAscent

The font ascent, in points; this is the maximum value for any individual character attribute in a line.

Discussion

The line-height table, defined by the LHTable data type, provides an array of line heights to hold the vertical spacing information for a given edit structure. It also contains line ascent information. The null style structure, defined by the NullStRec data type, contains the null scrap which is used to store character attribute information for a null selection.

The line height table holds vertical spacing information for the text of an edit structure. This table parallels the lineStarts array in the edit structure itself. Its length equals the edit structure’s nLines field plus 1 for a dummy entry at the end, just as the lineStarts array ends with a dummy entry that has the same value as the length of the text. The table’s contents are recalculated whenever the line starting values are themselves recalculated with the TECalText function or whenever an editing action causes recalibration.

The line height table is used only if the lineHeight and fontAscent fields in the edit structure are negative; positive values in those fields specify fixed vertical spacing, overriding the information in the table. The line height table is of type LHTable, which is an array of elements of LHElement.

Availability
Declared In
TextEdit.h

LHTable

Defines an array of line-height elements.

typedef LHElement LHTable[8001];

Availability
Declared In
TextEdit.h

NullStHandle

Defines a handle to a null scrap record pointer.

typedef NullStPtr *      NullStHandle;

Availability
Declared In
TextEdit.h

NullStRec

Contains the null scrap.

struct NullStRec {
   long teReserved;
   StScrpHandle nullScrap;
};
typedef struct NullStRec NullStRec;
typedef NullStRec * NullStPtr;

Fields
teReserved

This field is reserved for future expansion.

nullScrap

A handle to the style scrap structure.

Discussion

The NullSTRec data type defines the null style structure.

The null style structure contains the null scrap, which is used to store the character attribute information for a null selection (insertion point). A number of functions either write this character attribute information to the null scrap or read it from this scrap (to be applied to inserted text). The null scrap is created and initialized when an application calls TEStyleNew to create a multistyled edit structure. The null scrap is retained for the life of the edit structure; it is destroyed when TEDispose destroys the edit structure and releases the memory allocated for it.

Availability
Declared In
TextEdit.h

NWidthHookUPP

Defines a universal procedure pointer (UPP) to a width-hook callback.

typedef NWidthHookProcPtr NWidthHookUPP;

Discussion

For more information, see the description of the NWidthHookUPP () callback function.

Availability
Declared In
TextEdit.h

ScrpSTElement

Contains the scrap style table.

struct ScrpSTElement {
   long scrpStartChar;
   short scrpHeight;
   short scrpAscent;
   short scrpFont;
   StyleField scrpFace;
   short scrpSize;
   RGBColor scrpColor;
};
typedef struct ScrpSTElement ScrpSTElement;
typedef ScrpSTElement ScrpSTTable[1601];

Fields
scrpStartChar

The offset to the beginning of a style structure in the scrap.

scrpHeight

The line height. You can determine the line height and the font ascent using the QuickDraw function GetFontInfo.

scrpAscent

The font ascent. See scrpHeight.

scrpFont

The font family ID.

scrpFace

The character style (such as plain, bold, underline).

scrpSize

The size, in points.

scrpColor

The RGB (red, green, blue) color for the style scrap.

Discussion

The style scrap structure contains the scrap style table. Unlike the main style table for an edit structure, the scrap style table may contain duplicate elements; the entries in the table correspond one-to-one with the style runs in the text. The scrpStartChar field of each entry gives the starting position for the run.

The scrpStyleTab data type defines the scrap style table data structure, which is an array of scrap style element structures. The ScrpSTElement data type defines each scrap style element structure.

Availability
Declared In
TextEdit.h

ScrpSTTable

Contains an array of scrap style elements.

typedef ScrpSTElement ScrpSTTable[1601];

Availability
Declared In
TextEdit.h

STElement

Contains one entry for each distinct set of character attributes used in the text of an edit structure.

struct STElement {
   short stCount;
   short stHeight;
   short stAscent;
   short stFont;
   StyleField stFace;
   short stSize;
   RGBColor stColor;
};
typedef struct STElement STElement;
typedef STElement * STPtr;

Fields
stCount

A reference count of character runs using this set of character attributes.

stHeight

The line height for this run, in points.

stAscent

The font ascent for this run, in points.

stFont

The font family ID.

stFace

The character style (bold, italic, and so forth). This field consists of two bytes. The low-order byte contains the character style. TextEdit uses the high bit (bit 15) of the high-order byte to store the style run direction: it uses 0 for left-to-right text, and 1 for right-to-left text.

stSize

The text size, in points.

stColor

The RGB (red, green, blue) color.

Discussion

The style table contains one entry for each distinct set of character attributes used in the text of an edit structure. Each entry is defined in a style element structure. The size of the table is given by the nStyles field of the style structure. There is no duplication; each set of character attributes appears exactly once in the table. A reference count tells how many times each set of attributes is used in the table. The TEStyleTable data type defines the style table. Th eSTElement data type defines the style element structure.

Availability
Declared In
TextEdit.h

STHandle

Defines a handle to a style table pointer.

typedef STPtr *     STHandle;

Availability
Declared In
TextEdit.h

StScrpHandle

Defines a handle to a scrap style table pointer.

typedef StScrpPtr *     StScrpHandle;

Availability
Declared In
TextEdit.h

StScrpRec

Contains information used by functions to store character attribute information temporarily.

struct StScrpRec {
   short scrpNStyles;
   ScrpSTTable scrpStyleTab;
};
typedef struct StScrpRec StScrpRec;
typedef StScrpRec * StScrpPtr;

Fields
scrpNStyles

The number of style runs (sets of character attributes) used in the text. This determines the size of the style table. When character attribute information is written to the null scrap, this field is set to 1; when the character attribute information is removed, this field is set to 0.

scrpStyleTab

The scrap style table containing an element for each style run (set of character attributes).

Discussion

The style scrap structure, defined by the StScrpRec data type, is used by functions to store character attribute information temporarily. The scrap style table, defined by the scrpStyleTab data type, is contained in the style scrap structure. The scrap style element structure, defined by the ScrpSTElement data type, contains the character attribute information for an element in the scrap style table. One scrap style element structure exists for each sequential attribute change in the associated text.

The style scrap is used for storing character attribute information associated with the current text selection or insertion point, character attribute information to be applied to text, or multistyled text that is cut or copied. When multistyled text is cut or copied, the character attribute information is written to both the style scrap and the desk scrap.

In most cases, the style scrap is created dynamically as needed by functions. However, a style scrap structure can be created directly without using the TEGetStyleScrapHandle function; the character attribute information written to it can be applied to inserted text through TEStyleInsert or to existing text through TEUseStyleScrap.

The format of the style scrap is defined by a style scrap structure of type STScrpRec.

Availability
Declared In
TextEdit.h

StyleRun

Contains information for a style run.

struct StyleRun {
   short startChar;
   short styleIndex;
};
typedef struct StyleRun StyleRun;

Fields
startChar

The starting character position.

styleIndex

The run’s index in the style table.

Availability
Declared In
TextEdit.h

TEClickLoopUPP

Defines a universal procedure pointer (UPP) to a click-loop callback.

typedef TEClickLoopProcPtr TEClickLoopUPP;

Discussion

For more information, see the description of the TEClickLoopUPP () callback function.

Availability
Declared In
TextEdit.h

TEDoTextUPP

Defines a universal procedure pointer (UPP) to a do-text callback.

typedef TEDoTextProcPtr TEDoTextUPP;

Discussion

For more information, see the description of the TEDoTextUPP () callback function.

Availability
Declared In
TextEdit.h

TEFindWordUPP

Defines a universal procedure pointer (UPP) to a find-word callback.

typedef TEFindWordProcPtr TEFindWordUPP;

Discussion

For more information, see the description of the TEFindWordUPP () callback function.

Availability
Declared In
TextEdit.h