ADC Home > Reference Library > Reference > Carbon > Text & Fonts > TextEdit Reference (Not Recommended) >

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

TEHandle

Defines a handle to a TextEdit record pointer.

typedef TEPtr* TEHandle;

Availability
Declared In
TextEdit.h

TEIntHook

Defines a data type for a TextEdit integer hook.

typedef  short TEIntHook;

Availability
Declared In
TextEdit.h

TEPtr

Defines a pointer to a TextEdit record.

typedef TTERec* TEPtr;

Availability
Declared In
TextEdit.h

TERec

Stores display and editing information for TextEdit.

struct TERec {
   Rect destRect;
   Rect viewRect;
   Rect selRect;
   short lineHeight;
   short fontAscent;
   Point selPoint;
   short selStart;
   short selEnd;
   short active;
   WordBreakUPP wordBreak;
   TEClickLoopUPP clickLoop;
   long clickTime;
   short clickLoc;
   long caretTime;
   short caretState;
   short just;
   short teLength;
   Handle hText;
   long hDispatchRec;
   short clikStuff;
   short crOnly;
   short txFont;
   StyleField txFace;
   short txMode;
   short txSize;
   GrafPtr inPort;
   HighHookUPP highHook;
   CaretHookUPP caretHook;
   short nLines;
   short lineStarts[16001];
};
typedef struct TERec TERec;
typedef TERec * TEPtr;

Fields
destRect

The destination rectangle, in local coordinates.

viewRect

The view rectangle, in local coordinates.

selRect

The selection rectangle, whose boundaries are defined in local coordinates. This value is the current selection range or insertion point.

lineHeight

The vertical spacing of lines of text. Vertical spacing may be fixed or it may vary from line to line, depending upon specific text attributes. If the value of lineHeight is greater than 0, this field specifies the fixed vertical distance from the ascent line of one line of text down to the ascent line of the next.

If the value of lineHeight is less than 1, then this field specifies the vertical distance from the ascent line of one line of text down to the ascent line of the next calculated independently for each line, based on the maximum value for any individual character attribute on that line.

fontAscent

The font ascent line. If the value of fontAscent is greater than 0, this field specifies how far above the base line the pen is positioned to begin drawing the caret or highlighting.

For single-spaced text, this is the height of the text in pixels (the height of the tallest characters in the font from the base line). If the value of fontAscent is less than 1, this field specifies the font ascent calculated independently for each line, based on maximum value for any individual character attribute on that line.

selPoint

The point selected with the mouse, in the local coordinates of the current graphics port. The assembly-language offset for this field is named teSelPoint.

selStart

The byte offset of the beginning of a selection range. Note that byte offset 0 refers to the first byte in the text buffer.

selEnd

The byte offset of the end of a selection range. To include that byte, this value must be 1 greater than the position of the last byte offset of the text.

active

This field is used internally by TextEdit. It is set when an edit structure is activated through TEActivate and then reset when the edit structure is rendered inactive through TEDeactivate. To ensure future compatibility, use TEActivate or TEDeactivate to access this field.

wordBreak

A universal procedure pointer to the structure’s word selection break function. This function determines the word that is highlighted when the user double-clicks in the text and the position at which text is wrapped at the end of a line.

clickLoop

A universal procedure pointer to the click loop function.The specified click loop function is called repeatedly by the TEClick function as long as the mouse button is held down within the text.

clickTime

This field is for internal use only.

clickLoc

This field is for internal use only.

caretTime

This field is for internal use only.

caretState

This field is for internal use only.

just

The type of text alignment: default (according to primary line direction), left, center, or right.

teLength

The number of bytes in the text to be edited. For two-byte systems, potentially twice the number of characters. Initially set to zero. The maximum length is 32767 bytes.

hText

A handle to the text. Initially, it points to a zero-length block of text in the heap.

hDispatchRec

A handle to the TextEdit dispatch structure. This field is for internal use only; do not modify this field, or copy it to another edit structure. Each edit structure has its own dispatch structure. Attempting to use the dispatch structure of one edit structure with another edit structure can cause TextEdit to crash.

clikStuff

This field is for internal use only. TextEdit sets this field to reflect whether the most recent mouse-down event occurred on the leading or trailing edge of a glyph. TextEdit uses this value in determining a caret position.

crOnly

A value specifying whether or not text wraps at the right edge of the destination rectangle. If crOnly is positive, text does wrap. Otherwise, new lines are displayed only at Carriage Returns.

If crOnly is negative, new lines are specified explicitly by Return characters only; text does not wrap at the edge of the destination rectangle. (This is useful in an application similar to a programming-language editor, where you may not want a single line of code to be split onto two lines.

txFont

The font of all the text in the edit structure, if the txSize field of this edit structure ≥ 0. If you change this value, the entire text of this edit structure has the new characteristic when it is redrawn also remember to change the lineHeight and fontAscent fields.

If the txSize field is –1, this field combines with txFace to hold a handle to the associated style structure.

txFace

The character attributes of all the text in an edit structure, if the txSize field of this edit structure ≥ 0. If you change this value, the entire text of this edit structure has the new characteristic when it is redrawn also, remember to change the lineHeight and fontAscent fields as well.

If the txSize field is –1, this field combines with txFont to hold a handle to the associated style structure.

txMode

The pen mode of all the text in the edit structure. If you change this value, the entire text of this edit structure has the new characteristic when it is redrawn; also, remember to change the lineHeight and fontAscent fields as well.

txSize

Depending on its value, txSize either contains the point size of all of the text or it acts as a flag indicating whether or not there is associated character attribute information. If txSize ≥ 0, this is a monostyled edit structure, that is, all text is set in a single font, size, and face, and the value of txSize is the size of the text. If txSize is –1, the edit structure contains associated character attribute information and the txFont and txFace fields combine to form a handle to the style structure.

inPort

A pointer to the graphics port associated with this edit structure.

highHook

A pointer to the function that deals with text highlighting. In assembly language, the highHook field is located at the offset teHiHook.

caretHook

A pointer to the function that controls the appearance of the caret. In assembly language, the caretHook field is located at the offset teCarHook.

nLines

The number of lines in the text.

lineStarts

An array containing the character position of the first character in each line. It is declared to have 16001 elements to comply with Pascal range checking. This is a dynamic data structure, having only as many elements as needed. TextEdit calculates these values internally, so do not change the elements of the lineStarts array. Because this data structure grows and shrinks, the size of the edit structure changes.

Discussion

The edit structure, defined by the TERec data type, stores the display and editing information for TextEdit. Along with various subsidiary data structures, the style structure, defined by the TEStyleRec data type, stores the character attribute information for the text of the edit structure.

The edit structure contains display, storage, styling, and other information. Although some fields are used differently for multistyled edit structures and monostyled edit structures, the structure of an edit structure is the same whether the text is multistyled or monostyled.

Availability
Declared In
TextEdit.h

TERecalcUPP

Defines a universal procedure pointer (UPP) to a recalculation callback.

typedef TERecalcProcPtr TERecalcUPP;

Discussion

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

Availability
Declared In
TextEdit.h

TEStyleRec

Stores the character attribute information for the text of a multistyled edit structure.

struct TEStyleRec {
   short nRuns;
   short nStyles;
   STHandle styleTab;
   LHHandle lhTab;
   long teRefCon;
   NullStHandle nullStyle;
   StyleRun runs[8001];
};
typedef struct TEStyleRec TEStyleRec;
typedef TEStyleRec * TEStylePtr;

Fields
nRuns

The number of style runs in the text.

nStyles

The number of distinct sets of character attributes used in the text; this forms the size of the style table.

styleTab

A handle to the style table.

lhTab

A handle to the line height table.

teRefCon

A reference constant for use by applications. The application can use this 32-bit field to suit its needs.

nullStyle

A handle to the style scrap structure used to store the character attribute information for a null selection.

runs

A table of style runs that is of indefinite length.

Discussion

The style structure stores the character attribute information for the text of a multistyled edit structure. If an edit structure has associated character attribute information, its txFont and txFac e fields combine to hold a style handle, of type TEStyleHandle, to its style structure. The text is divided into style runs, summarized in the style run table, of type StyleRun, which is part of the style structure. Each entry in the style run table gives the starting character position of a run and an index into the style table, of type TEStyleTable.

The style table element pointed to by the style run index describes the character attributes for that run.

To determine the length of a run, you subtract its start position from that of the next entry in the style run table. A dummy entry at the end of the style run table delimits the length of the last run; its start position is equal to the overall number of characters in the text, plus 1. The TEStyleRec data type defines the style structure.

The style run table, defined by the StyleRun data type, is an array that contains the boundaries of each style run and an index to its character attribute information in the style element array. The style table, defined by the TEStyleTable data type, contains one entry for each distinct set of character attributes used in the text of the edit structure.

Availability
Declared In
TextEdit.h

TEStyleTable

Defines and array of style elements.

typedef STElement TEStyleTable[1777];

Availability
Declared In
TextEdit.h

TextStyle

Contains text style information.

struct TextStyle {
   short tsFont;
   StyleField tsFace;
   short tsSize;
   RGBColor tsColor;
};
typedef struct TextStyle TextStyle;
typedef TextStyle * TextStylePtr;

Fields
tsFont

The font family number.

tsFace

The character style (bold, italic, plain, and so forth).

tsSize

The text size in points.

tsColor

The RGB (red, green, blue) color.

tsColor
Discussion

Text style structures, which are passed as variables or reference parameters, are used for communicating character attribute information between the application and several TextEdit functions, such as TEContinuousStyle and TEReplaceStyle. They carry the same information as the style element structures in the style table, but without the reference count, line height, and font ascent.

Availability
Declared In
TextEdit.h

TextWidthHookUPP

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

typedef TextWidthHookProcPtr TextWidthHookUPP;

Discussion

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

Availability
Declared In
TextEdit.h

TSMDialogPeek

Defines a data type for a TSM dialog pointer.

typedef TSMDialogPtr TSMDialogPeek;

Availability
Declared In
TSMTE.h

TSMDialogPtr

Defines a pointer to a TSM dialog record.

typedef TSMDialogRecord* TSMDialogPtr;

Availability
Declared In
TSMTE.h

TSMDialogRecord

Contains information for a TSM dialog record.

struct TSMDialogRecord {
   DialogRecord        fDialog;
   TSMDocumentID       fDocID;
   TSMTERecHandle      fTSMTERecH;
   long                fTSMTERsvd[3];
};
typedef struct TSMDialogRecord  TSMDialogRecord;

Availability
Declared In
TSMTE.h

TSMTEPostUpdateUPP

Defines a universal procedure pointer (UPP) to a post-update callback.

typedef TSMTEPostUpdateProcPtr TSMTEPostUpdateUPP;

Discussion

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

Availability
Declared In
TSMTE.h

TSMTEPreUpdateUPP

Defines a universal procedure pointer (UPP) to a pre-update callback.

typedef TSMTEPreUpdateProcPtr TSMTEPreUpdateUPP;

Discussion

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

Availability
Declared In
TSMTE.h

TSMTERec

Defines a TSMTE record structure.

struct TSMTERec {
   TEHandle textH;
   TSMTEPreUpdateUPP preUpdateProc;
   TSMTEPostUpdateUPP postUpdateProc;
   long updateFlag;
   long refCon;
};
typedef struct TSMTERec TSMTERec;
typedef TSMTERec * TSMTERecPtr;

Availability
Declared In
TSMTE.h

TSMTERecHandle

Defines a handle to a TSMTE record pointer.

typedef TSMTERecPtr * TSMTERecHandle;

Availability
Declared In
TSMTE.h

WidthHookUPP

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

typedef WidthHookProcPtr WidthHookUPP;

Discussion

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

Availability
Declared In
TextEdit.h

Constants

Auto Idling Flag

Enables automatic idling in an event loop.

enum {
   teFIdleWithEventLoopTimer = 7
};

Auto Scroll Constant

Specifies automatic scrolling

enum {
   kTSMTEAutoScroll = 1
};

Do Text Selectors

Specify constants for identifying TEDoTextSelectors.

enum {
   teFind = 0,
   teHighlight = 1,
   teDraw = -1,
   teCaret = -2
};

Find Word Identification Constants

Specify constants for identifying the routine that called FindWord.

enum {
   teWordSelect = 4,
   teWordDrag = 8,
   teFromFind = 12,
   teFromRecal = 16
};

Hook Constants

Specify offsets into the TEDispatchRec data structure.

enum {
   EOLHook = 0,
   DRAWHook = 4,
   WIDTHHook = 8,
   HITTESTHook = 12,
   nWIDTHHook = 24,
   TextWidthHook = 28
};

Inline Input Flag

Specifies to use inline input service.

enum {
   teFUseTextServices = 4
};

Constants
teFUseTextServices

Use inline input service. This flag is no longer in use.

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

Signature and Interface Constants

Specify a TSM TextEdit signature or interface.

enum {
   kTSMTESignature = 'tmTE',
   kTSMTEInterfaceType = 'tmTE'
};

Style Mode Constants

Used to set and replace style modes.

enum {
   fontBit = 0,
   faceBit = 1,
   sizeBit = 2,
   clrBit = 3,
   addSizeBit = 4,
   toggleBit = 5
};

Text Alignment Constants

Specify justification (word alignment) styles.

enum {
   teJustLeft = 0,
   teJustCenter = 1,
   teJustRight = -1,
   teForceLeft = -2,
   teFlushDefault = 0,
   teCenter = 1,
   teFlushRight = -1,
   teFlushLeft = -2
};

Constants
teFlushDefault

Align according to primary line direction

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

teCenter

Centered for all scripts

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

teFlushRight

Right aligned for all scripts

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

teFlushLeft

Left aligned for all scripts

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

Discussion

You can use these constants to specify the text alignment through the align parameter of the TESetAlignment and TETextBox functions. For compatibility, the previous names of these constants ( teJustLeft , teJustCenter , teJustRight , and teForceLeft ) are still supported.

Text Custom Hook Constants

Specify a selector for a TextEdit hook function.

enum {
   intEOLHook = 0,
   intDrawHook = 1,
   intWidthHook = 2,
   intHitTestHook = 3,
   intNWidthHook = 6,
   intTextWidthHook = 7,
   intInlineInputTSMTEPreUpdateHook = 8,
   intInlineInputTSMTEPostUpdateHook = 9
};

Constants
intEOLHook

End-of-line hook

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

intDrawHook

Draw hook

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

intWidthHook

Width measurement hook

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

intHitTestHook

Hit test hook

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

intNWidthHook

New width measurement hook

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

intTextWidthHook

Text width measurement hook (low-memory global width measurement hook)

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

intInlineInputTSMTEPreUpdateHook

Specifies a TSMTEPreUpdateProcPtr callback.

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

intInlineInputTSMTEPostUpdateHook

Specifies a TSMTEPostUpdateProcPtr callback.

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

Discussion

To specify a default TextEdit hook function with a customized function, you specify one of the following constants as the value of the which parameter to the TECustomHook function.

Text Feature Action Constants

Specify the action to be performed on a feature.

enum {
   teBitClear = 0,
   teBitSet = 1,
   teBitTest = -1
};

Constants
teBitClear

Disables the specified feature

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

teBitSet

Enables the specified feature. If teBitTest returns teBitSet, the feature is enabled; if it returns teBitClear, it is disabled.

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

teBitTest

Returns the current setting of the specified feature

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

Discussion

To specify the action to be performed on a feature, you specify one of these constants as the value of the action parameter to the TEFeatureFlag function.

To test for the availability of these features, you can call the Gestalt function with the gestaltTextEditVersion selector. A result of gestaltTE4 or greater returned in the response parameter indicates that outline highlighting and text buffering are available. A result of gestaltTE5 or greater returned in the response parameter indicates that the two inline input features are available.

Version Notes

The inline input features are also available on version 6.0.7 systems with non-Roman script systems installed. However, there is no Gestalt constant that indicates this availability.

Text Feature Constants

Specify feature or bit definitions for the function TEFeatureFlag.

enum {
   teFAutoScroll = 0,
   teFTextBuffering = 1,
   teFOutlineHilite = 2,
   teFInlineInput = 3,
   teFUseWhiteBackground = 4,
   teFUseInlineInput = 5,
   teFInlineInputAutoScroll = 6
};

Constants
teFAutoScroll

Automatic scrolling. You can use the TEFeatureFlag function to turn automatic scrolling on and off as an alternative to calling TEAutoView. The effect is the same.

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

teFTextBuffering

Text buffering. The teFTextBuffering selector enables or disables text buffering for performance improvements of 2-byte scripts. This is a global buffer, as opposed to the TEKey function’s internal 2-byte buffer, and it is used across all active edit structures.

Exercise care when you enable the text-buffering capability in more than one active structure; otherwise, the bytes that are buffered from one edit structure may appear in another edit structure.

Ensure that buffering is not turned off in the middle of processing a 2-byte character. To guarantee the integrity of your structure, it is important that you wait for an idle event before you disable buffering or enable buffering in a second edit structure.

When text buffering is enabled, ensure that the TEIdle function is called before any pause of more than a few ticks—for example, before the Event Manager function WaitNextEvent. A possibility of a long delay before characters appear on the screen exists, especially in non-Roman systems. If you do not call TEIdle, the characters can end up in the edit structure of another application.

If text buffering is enabled on a non-Roman script system and the keyboard has changed, TextEdit flushes the text of the current script from the buffer before bringing characters of the new script into the buffer.

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

teFOutlineHilite

Outline highlighting. The teFOutlineHilite selector specifies outline highlighting as the feature for which an action is to be performed. If a highlighted region exists in an edit structure and the window is inactive, then the highlighted region is outlined or framed.

In the case that outline highlighting is enabled and the current selection range is an insertion point, the caret is then drawn in a gray pattern so that it appears dimmed. To do the framing and caret dimming, TextEdit temporarily replaces the current address in the highHook and caretHook fields of the edit structure, redraws the caret or the highlighted region, and then immediately restores the hooks to their previous addresses.

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

teFInlineInput

Inline input. You must deactivate an edit structure (using TEDeactivate) before changing the state of the feature bits or any fields in the edit structure.

In the future, other text services may use this same mechanism. If you follow the guidelines specified here, your application should also work with future text services. When an inline edit session begins, inline input also sets the teFInlineInput bit to provide the following features so that inline input works correctly with TextEdit: disabling font and keyboard synchronization, forcing a multiple-line selection to be highlighted line by line using a separate rectangle for each line rather than using a minimum number of rectangles for optimization, and highlighting a line only to the edge of the text rather than beyond the text to the edge of the view rectangle.

The teFInlineInput bit is cleared by inline input when an inline session ends. Use the teFInlineInput constant in the feature parameter of TEFeatureFlag to include these features in your application even when inline input is not installed. Be careful about changing the state of this bit if the teFUseTextServices bit is set. Again, the edit structure should always be deactivated before you change the state of the teFInlineInput bit. If you clear the teFUseTextServices bit and you set the teFInlineInput bit, inline input is disabled, but your application retains the features listed above.

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

Discussion

To identify or adjust a feature, you specify one of these constants as the value of the feature parameter to the TEFeatureFlag function.

Text Styling Constants

Specify character attributes.

enum {
   doFont = 1,
   doFace = 2,
   doSize = 4,
   doColor = 8,
   doAll = 15,
   addSize = 16,
   doToggle = 32
};

Constants
doFont

Sets the font family ID

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

doFace

Sets the character style

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

doSize

Sets the type size

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

doColor

Sets the color

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

doAll

Sets all attributes

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

addSize

Increases or decreases the current type size

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

doToggle

Modifies the mode

Available in Mac OS X v10.0 and later.

Declared in TextEdit.h.

Discussion

You can use these constants (singly or in combination) to specify character attributes, through the mode parameter of the TEContinuousStyle , TESetStyle , and TEReplaceStyle functions.

Result Codes

In addition to noErr, the most common result code returned by TextEdit is listed below.

Result CodeValueDescription
noScrapErr -100

Scrap does not exist (not initalized).

Available in Mac OS X v10.0 and later.



Next Page > Hide TOC

© 2003, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-13)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.