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

< Previous PageNext Page > Hide TOC

Legacy Documentclose button

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

Deprecated TextEdit Reference (Not Recommended) Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

DisposeCaretHookUPP

Disposes of a universal procedure pointer (UPP) to a caret-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeCaretHookUPP (
   CaretHookUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeDrawHookUPP

Disposes of a universal procedure pointer (UPP) to a draw-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeDrawHookUPP (
   DrawHookUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeEOLHookUPP

Disposes of a universal procedure pointer (UPP) to an EOL-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeEOLHookUPP (
   EOLHookUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeHighHookUPP

Disposes of a universal procedure pointer (UPP) to a high-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeHighHookUPP (
   HighHookUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeHitTestHookUPP

Disposes of a universal procedure pointer (UPP) to a hit-test hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeHitTestHookUPP (
   HitTestHookUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeNWidthHookUPP

Disposes of a universal procedure pointer (UPP) to a width-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeNWidthHookUPP (
   NWidthHookUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeTEClickLoopUPP

Disposes of a universal procedure pointer (UPP) to a click-loop callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeTEClickLoopUPP (
   TEClickLoopUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeTEDoTextUPP

Disposes of a universal procedure pointer (UPP) to a do-text callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeTEDoTextUPP (
   TEDoTextUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeTEFindWordUPP

Disposes of a universal procedure pointer (UPP) to a find-word callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeTEFindWordUPP (
   TEFindWordUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeTERecalcUPP

Disposes of a universal procedure pointer (UPP) to a recaluclation callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeTERecalcUPP (
   TERecalcUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeTextWidthHookUPP

Disposes of a universal procedure pointer (UPP) to a text-width-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeTextWidthHookUPP (
   TextWidthHookUPP userUPP
);

Availability
Declared In
TextEdit.h

DisposeTSMTEPostUpdateUPP

Disposes of a universal procedure pointer (UPP) to a post-update callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeTSMTEPostUpdateUPP (
   TSMTEPostUpdateUPP userUPP
);

Availability
Declared In
TSMTE.h

DisposeTSMTEPreUpdateUPP

Disposes of a universal procedure pointer (UPP) to a pre-update callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeTSMTEPreUpdateUPP (
   TSMTEPreUpdateUPP userUPP
);

Availability
Declared In
TSMTE.h

DisposeWidthHookUPP

Disposes of a universal procedure pointer (UPP) to a width-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void DisposeWidthHookUPP (
   WidthHookUPP userUPP
);

Availability
Declared In
TextEdit.h

GetTSMTEDialogDocumentID

Returns a TSM document ID for the specified dialog. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TSMDocumentID GetTSMTEDialogDocumentID (
   DialogRef dialog
);

Return Value

See the Text Services Manager documentation for a description of the TSMDocumentID data type.

Availability
Declared In
TSMTE.h

GetTSMTEDialogTSMTERecHandle

Returns a handle to a TSM record for the specified dialog. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TSMTERecHandle GetTSMTEDialogTSMTERecHandle (
   DialogRef dialog
);

Return Value

See the description of the TSMTERecHandle data type.

Availability
Declared In
TSMTE.h

InvokeCaretHookUPP

Calls a caret-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void InvokeCaretHookUPP (
   const Rect *r,
   TEPtr pTE,
   CaretHookUPP userUPP
);

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeDrawHookUPP

Calls a draw-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void InvokeDrawHookUPP (
   unsigned short textOffset,
   unsigned short drawLen,
   void *textBufferPtr,
   TEPtr pTE,
   TEHandle hTE,
   DrawHookUPP userUPP
);

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeEOLHookUPP

Calls an EOL-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

Boolean InvokeEOLHookUPP (
   char theChar,
   TEPtr pTE,
   TEHandle hTE,
   EOLHookUPP userUPP
);

Return Value

See the Mac Types documentation for a description of the Boolean data type.

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeHighHookUPP

Calls a high-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void InvokeHighHookUPP (
   const Rect *r,
   TEPtr pTE,
   HighHookUPP userUPP
);

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeHitTestHookUPP

Calls a hit-test hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

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

Return Value

See the Mac Types documentation for a description of the Boolean data type.

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeNWidthHookUPP

Calls a width-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

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

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeTEClickLoopUPP

Calls a click-loop callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

Boolean InvokeTEClickLoopUPP (
   TEPtr pTE,
   TEClickLoopUPP userUPP
);

Return Value

See the Mac Types documentation for a description of the Boolean data type.

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeTEDoTextUPP

Calls a do-text callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

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

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeTEFindWordUPP

Calls a find-word callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

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

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeTERecalcUPP

Calls a recalculation callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void InvokeTERecalcUPP (
   TEPtr pTE,
   unsigned short changeLength,
   unsigned short *lineStart,
   unsigned short *firstChar,
   unsigned short *lastChar,
   TERecalcUPP userUPP
);

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeTextWidthHookUPP

Calls a text-width-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

unsigned short InvokeTextWidthHookUPP (
   unsigned short textLen,
   unsigned short textOffset,
   void *textBufferPtr,
   TEPtr pTE,
   TEHandle hTE,
   TextWidthHookUPP userUPP
);

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

InvokeTSMTEPostUpdateUPP

Calls a post-update callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void InvokeTSMTEPostUpdateUPP (
   TEHandle textH,
   long fixLen,
   long inputAreaStart,
   long inputAreaEnd,
   long pinStart,
   long pinEnd,
   long refCon,
   TSMTEPostUpdateUPP userUPP
);

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TSMTE.h

InvokeTSMTEPreUpdateUPP

Calls a pre-update callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void InvokeTSMTEPreUpdateUPP (
   TEHandle textH,
   long refCon,
   TSMTEPreUpdateUPP userUPP
);

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TSMTE.h

InvokeWidthHookUPP

Calls a width-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

unsigned short InvokeWidthHookUPP (
   unsigned short textLen,
   unsigned short textOffset,
   void *textBufferPtr,
   TEPtr pTE,
   TEHandle hTE,
   WidthHookUPP userUPP
);

Discussion

You should not need to use this function, as the system invokes your callback for you.

Availability
Declared In
TextEdit.h

IsTSMTEDialog

Checks to see if the specified dialog is a TSMTE dialog. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

Boolean IsTSMTEDialog (
   DialogRef dialog
);

Return Value

See the Mac Types documentation for a description of the Boolean data type.

Availability
Declared In
TSMTE.h

NewCaretHookUPP

Creates a new universal procedure pointer (UPP) to a caret-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

CaretHookUPP NewCaretHookUPP (
   CaretHookProcPtr userRoutine
);

Return Value

See the description of the CaretHookUPP data type.

Availability
Declared In
TextEdit.h

NewDrawHookUPP

Creates a new universal procedure pointer (UPP) to a draw-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

DrawHookUPP NewDrawHookUPP (
   DrawHookProcPtr userRoutine
);

Return Value

See the description of the DrawHookUPP data type.

Availability
Declared In
TextEdit.h

NewEOLHookUPP

Creates a new universal procedure pointer (UPP) to an EOL-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

EOLHookUPP NewEOLHookUPP (
   EOLHookProcPtr userRoutine
);

Return Value

See the description of the EOLHookUPP data type.

Availability
Declared In
TextEdit.h

NewHighHookUPP

Creates a new universal procedure pointer (UPP) to a high-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

HighHookUPP NewHighHookUPP (
   HighHookProcPtr userRoutine
);

Return Value

See the description of the HighHookUPP data type.

Availability
Declared In
TextEdit.h

NewHitTestHookUPP

Creates a new universal procedure pointer (UPP) to a hit-test hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

HitTestHookUPP NewHitTestHookUPP (
   HitTestHookProcPtr userRoutine
);

Return Value

See the description of the HitTestHookUPP data type.

Availability
Declared In
TextEdit.h

NewNWidthHookUPP

Creates a new universal procedure pointer (UPP) to a width-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

NWidthHookUPP NewNWidthHookUPP (
   NWidthHookProcPtr userRoutine
);

Return Value

See the description of the NWidthHookUPP data type.

Availability
Declared In
TextEdit.h

NewTEClickLoopUPP

Creates a new universal procedure pointer (UPP) to a click-loop callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TEClickLoopUPP NewTEClickLoopUPP (
   TEClickLoopProcPtr userRoutine
);

Return Value

See the description of the TEClickLoopUPP data type.

Availability
Declared In
TextEdit.h

NewTEDoTextUPP

Creates a new universal procedure pointer (UPP) to a do-text callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TEDoTextUPP NewTEDoTextUPP (
   TEDoTextProcPtr userRoutine
);

Return Value

See the description of the TEDoTextUPP data type.

Availability
Declared In
TextEdit.h

NewTEFindWordUPP

Creates a new universal procedure pointer (UPP) to a find-word callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TEFindWordUPP NewTEFindWordUPP (
   TEFindWordProcPtr userRoutine
);

Return Value

See TEFindWordUPP for a description of the TEFindWordUPP data type.

Availability
Declared In
TextEdit.h

NewTERecalcUPP

Creates a new universal procedure pointer (UPP) to a recalculation callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TERecalcUPP NewTERecalcUPP (
   TERecalcProcPtr userRoutine
);

Return Value

See the description of the TERecalcUPP data type.

Availability
Declared In
TextEdit.h

NewTextWidthHookUPP

Creates a new universal procedure pointer (UPP) to a text-width-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TextWidthHookUPP NewTextWidthHookUPP (
   TextWidthHookProcPtr userRoutine
);

Return Value

See the description of the TextWidthHookUPP data type.

Availability
Declared In
TextEdit.h

NewTSMTEPostUpdateUPP

Creates a new universal procedure pointer (UPP) to a post-update callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TSMTEPostUpdateUPP NewTSMTEPostUpdateUPP (
   TSMTEPostUpdateProcPtr userRoutine
);

Return Value

See TSMTEPostUpdateUPP for a description of the TSMTEPostUpdateUPP data type.

Availability
Declared In
TSMTE.h

NewTSMTEPreUpdateUPP

Creates a new universal procedure pointer (UPP) to a pre-update callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TSMTEPreUpdateUPP NewTSMTEPreUpdateUPP (
   TSMTEPreUpdateProcPtr userRoutine
);

Return Value

See the description of the TSMTEPreUpdateUPP data type.

Availability
Declared In
TSMTE.h

NewWidthHookUPP

Creates a new universal procedure pointer (UPP) to a width-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

WidthHookUPP NewWidthHookUPP (
   WidthHookProcPtr userRoutine
);

Return Value

See the description of the WidthHookUPP data type.

Availability
Declared In
TextEdit.h

SetTSMTEDialogDocumentID

Sets the document ID for the specified dialog. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void SetTSMTEDialogDocumentID (
   DialogRef dialog,
   TSMDocumentID documentID
);

Availability
Declared In
TSMTE.h

SetTSMTEDialogTSMTERecHandle

Sets a handle to a TSMTE record for the specified dialog. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void SetTSMTEDialogTSMTERecHandle (
   DialogRef dialog,
   TSMTERecHandle tsmteRecHandle
);

Availability
Declared In
TSMTE.h

TEActivate

Activates the specified edit structure. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEActivate (
   TEHandle hTE
);

Parameters
hTE

A handle to the specified edit structure.

Discussion

When your application receives notification of an activate event, it can call the TEActivate function, which activates an edit structure and highlights the selection range. If the selection range is an insertion point, TEActivate simply displays a caret there. Call this function every time the Event Manager function WaitNextEvent reports that the window containing the edit structure has become active.

If you do not call TEActivate before you call TEClick, TEIdle, or TESetSelect, the selection range is not highlighted, or, if the selection range is set to an insertion point, a caret is not displayed at the insertion point. However, if you have turned on outline highlighting through the TEFeatureFlag function for the edit structure, the text of the selection range is framed or a dimmed or an unblinking caret is displayed at the insertion point.

Availability
Declared In
TextEdit.h

TEAutoView

Enables and disables automatic scrolling of the text in the specified edit structure. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEAutoView (
   Boolean fAuto,
   TEHandle hTE
);

Parameters
fAuto

A flag indicating whether to enable or disable automatic scrolling. A value of TRUE enables automatic scrolling; a value of FALSE disables automatic scrolling.

hTE

A handle to the edit structure for which automatic scrolling is to be enabled or disabled.

Discussion

The TEAutoView function does not actually scroll the text automatically: TESelView does. However, when fAuto is set to FALSE , a call to TESelView has no effect.

If there is a scroll bar associated with the edit structure, your application must manage scrolling of it. You can replace the default click loop function, which scrolls the text only, with a customized version that also updates the scroll bar.

You can also enable or disable automatic scrolling for an edit structure through the teFAutoScroll feature of the TEFeatureFlag function. For more information, see TEFeatureFlag.

Availability
Declared In
TextEdit.h

TECalText

Recalculates the beginnings of all lines of text in the specified edit structure. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TECalText (
   TEHandle hTE
);

Parameters
hTE

A handle to the edit structure whose text lines are to be recalculated.

Discussion

The TECalText function updates elements of the lineStarts array in an edit structure. Call TECalText if you’ve changed the destination rectangle, the hText field, or any other property of the edit structure that pertains to line breaks and the number of characters per line—for example, font, size, style, and so on.

Availability
Declared In
TextEdit.h

TEClick

Controls placement and highlighting of the selection range as determined by mouse events. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEClick (
   Point pt,
   Boolean fExtend,
   TEHandle h
);

Parameters
pt

The mouse location in local coordinates at the time the mouse button was pressed, obtainable from the event structure (in global coordinates).

fExtend

A flag denoting the state of the Shift key at the time of the click as indicated by the Event Manager. If the Shift key was held down at the time of the click to extend the selection, pass a value of TRUE.

h

A handle to the edit structure whose text is displayed in the view rectangle where the click occurred.

Discussion

Call TEClick whenever a mouse-down event occurs in the view rectangle of the edit structure and the window associated with that edit structure is active. The TEClick function keeps control until the mouse button is released. Use the QuickDraw function GlobalToLocal to convert the global coordinates of the mouse location given in the event structure to the local coordinate system for pt.

The TEClick function removes highlighting of the old selection range unless the selection range is being extended. If the mouse moves, meaning that a drag is occurring, TEClick expands or shortens the selection range accordingly a character at a time. In the case of a double-click, the word where the cursor is positioned becomes the selection range.

Availability
Declared In
TextEdit.h

TEContinuousStyle

Determines whether a given character attribute is continuous over the current selection range. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

Boolean TEContinuousStyle (
   short *mode,
   TextStyle *aStyle,
   TEHandle hTE
);

Parameters
mode

On input, a pointer to a selector specifying the attributes to be checked. On output, mode identifies only those attributes determined to be continuous over the selection range. Possible values for the mode parameter are defined in “Text Styling Constants.”

aStyle

On input, a pointer to a text style structure. On output, this structure contains the values for the mode attributes determined to be continuous over the selection.

hTE

A handle to the edit structure containing the selected text whose attributes are to be checked. If the value of hTE is a handle to a monostyled edit structure, TEContinuousStyle returns the set of character attributes that are consistent for the entire structure.

Return Value

TRUE if all of the attributes to be checked are continuous; FALSE if none or some are continuous. See the Mac Types documentation for a description of the Boolean data type.

Discussion

This function does not modify the text selection. If the current selection range is an insertion point, TEContinuousStyle first checks the null scrap. If the null scrap contains character attributes, then they are used based on the value of the mode parameter. Otherwise, if the null scrap is empty, TEContinuousStyle returns the attributes of the character preceding the insertion point. The TEContinuousStyle function always returns TRUE in this case, and each field of the text style structure is set if the corresponding bit in the mode parameter is set.

Note that fields in the text style structure specified by aStyle are only valid if the corresponding bits are set in the mode variable.

How the tsFace field of the aStyle structure is used requires some consideration. For example, if TEContinuousStyle returns a mode parameter that contains doFace and the text style structure tsFace field is bold, it means that the selected text is all bold, but may contain other text styles, such as italic, as well. Italic does not apply to all of the selected text, or it would have been included in the tsFace field. If the tsFace field is an empty set, then all of the selected text is plain.

Availability
Declared In
TextEdit.h

TECopy

Copies the text selection range from the edit structure, leaving the selection range intact. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TECopy (
   TEHandle hTE
);

Parameters
hTE

A handle to the edit structure containing the text to be copied.

Discussion

The TECopy function copies the text to the private scrap. For text of a monostyled edit structure, the text is written to the private scrap only. For text of a multistyled edit structure, the text is written to the TextEdit private scrap, the character attribute information is written to the TextEdit style scrap, and both are written to the Scrap Manager’s desk scrap. Anything previously in the private scrap is deleted before the copied text is written to it.

For both multistyled and monostyled text, if the selection range is an insertion point, TECopy empties the TextEdit private scrap. When the selection range is an insertion point and the text is multistyled, TECopy has no effect on the null scrap, the style scrap, or the Scrap Manager’s desk scrap.

Availability
Declared In
TextEdit.h

TECustomHook

Replaces a default TextEdit hook function with a customized function and returns the address of the replaced function. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TECustomHook (
   TEIntHook which,
   UniversalProcPtr *addr,
   TEHandle hTE
);

Parameters
which

The hook whose default function is to be replaced.

addr

On input, the address of your customized function.

On output, the addr parameter contains the address of the function that was previously installed in the field identified by the which parameter. This address is returned so that you can daisy-chain functions.

hTE

A handle to the edit structure to be modified.

Discussion

The TECustomHook function lets you alter the behavior of TextEdit to better suit your application’s requirements and those of the script systems installed. If you replace a default hook function with a customized version that you write in a high-level language, such as Pascal or C, you need to provide assembly-language glue code that utilizes the registers for your high-level language function.

The end-of-line hook, width measurement hook, new width measurement hook, text width measurement hook, draw hook, and hit test hook fields are hook fields in the TextEdit dispatch structure. The which parameter identifies the hook whose default function is to be replaced. You use the constants described in “Text Custom Hook Constants” to specify a value for this parameter.

Certain precautions are critical in replacing default functions. Before placing the address of your function in the TextEdit dispatch structure, strip the addresses, using the Operating System Utilities StripAddress function, to guarantee that your application is 32-bit clean.

Before replacing a TextEdit function with a customized one, determine whether more than one script system is installed, and if so, ensure that your customized function accommodates all of the installed script systems. This avoids the problem of your customized function producing results that are incompatible with the Script Manager.

Availability
Declared In
TextEdit.h

TECut

Removes the current selection range from the text of the designated edit structure, redrawing the text as necessary. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TECut (
   TEHandle hTE
);

Parameters
hTE

A handle to the edit structure containing the text to be cut.

Discussion

For monostyled text, the TECut function writes the cut text to the private scrap.

For multistyled text, TECut writes the cut text to the private scrap and its character attributes to the style scrap it also writes both to the Scrap Manager’s desk scrap. For multistyled text, the TECut function removes the character attributes from the style structure’s style table when the text is cut.

For both monostyled and multistyled text, if the selection range is an insertion point, TextEdit deletes everything from the private scrap. When the selection range is an insertion point and the text is multistyled, TECut has no effect on the style scrap or the Scrap Manager’s desk scrap.

Availability
Declared In
TextEdit.h

TEDeactivate

Deactivates the specified edit structure. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEDeactivate (
   TEHandle hTE
);

Parameters
hTE

A handle to the specified edit structure.

Discussion

When the activate event flag is set to deactivate the window, your application can call the TEDeactivate function, which changes an edit structure’s status from active to inactive and removes the selection range highlighting or the caret.

However, if you turned on outline highlighting through the TEFeatureFlag function for the edit structure, the text of the selection range is framed or a dimmed or an unblinking caret is displayed at the insertion point when the structure is deactivated.

Call this function every time the Event Manager function WaitNextEvent reports that the window containing the edit structure has become inactive.

Availability
Declared In
TextEdit.h

TEDelete

Removes the selected range of text from the designated edit structure, redrawing the remaining text as necessary. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEDelete (
   TEHandle hTE
);

Parameters
hTE

A handle to the edit structure containing the text to be deleted.

Discussion

When the TEDelete function deletes a selected range of text, it does not transfer the text to either the private scrap or the Scrap Manager’s desk scrap.

For multistyled structures, when you use TEDelete to delete a selected range of text, the associated character attributes are saved in the null scrap to be applied to characters entered after the text is deleted. When the user clicks in some other area of the text, the character attributes are removed from the null scrap. You can use TEDelete to implement the Clear command. The TEDelete function recalculates line starts and line heights.

Availability
Declared In
TextEdit.h

TEDispose

Removes a specified edit structure and releases all memory associated with it. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEDispose (
   TEHandle hTE
);

Parameters
hTE

A handle to the edit structure for which the allocated memory should be released.

Discussion

Call the TEDispose function only when you’re completely through with an edit structure.

Note that if your program retains a handle to text associated with the edit structure that you are destroying with TEDispose , the handle becomes invalid because the TEDispose function disposes of it, as well as the dispatch structure handle. If the structure is multistyled, TEDispose also disposes all of the style-related handles: STHandle, LHHandle, STScrpHandle, nullSTHandle, and TEStyleHandle.

To continue to refer to the text after you’ve destroyed the edit structure, you need to make a copy of the handle in the hText field of the edit structure using the Operating System Utilities HandToHand function before you call TEDispose.

In addition to disposing of the edit structure, the edit structure handle, and the dispatch structure handle, the TEDispose function destroys the null scrap associated with the edit structure and releases the memory used for it.

Availability
Declared In
TextEdit.h

TEFeatureFlag

Turns a specified feature on or off or returns the current status of that feature. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

short TEFeatureFlag (
   short feature,
   short action,
   TEHandle hTE
);

Parameters
feature

The feature for which the action is to be performed. See “Text Feature Constants” for a description of the available values.

action

A selector stipulating that the feature, specified by the feature parameter, is to be turned on or off, or that the current status of the feature is to be returned. See “Text Feature Action Constants” for a description of the available values.

hTE

A handle to the edit structure for which the action should be performed.

Return Value

The status of the specified feature (if the selector is set to teBitTest).

Discussion

You can use the TEFeatureFlag function to check the status of additional TextEdit features—automatic scrolling, outline highlighting, and text buffering—and to enable or disable the feature. You can also use this function to disable inline input in a particular edit structure and to enable several features that have been provided so that inline input works correctly with TextEdit.

Availability
Declared In
TextEdit.h

TEFromScrap

Copies the contents of the desk scrap to the TextEdit private scrap. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

OSErr TEFromScrap (
   void
);

Return Value

A result code. See “TextEdit Result Codes.”

Discussion

You use this function to move monostyled text across applications or between an application and a desk accessory.

Availability
Declared In
TextEdit.h

TEGetDoTextHook

Obtains a universal procedure pointer to your do-text-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TEDoTextUPP TEGetDoTextHook (
   void
);

Return Value

See the description of the TEDoTextUPP data type.

Availability
Declared In
TextEdit.h

TEGetFindWordHook

Obtains a universal procedure pointer to your set-find-word-hook callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TEFindWordUPP TEGetFindWordHook (
   void
);

Return Value

See the description of the TEFindWordUPP data type.

Availability
Declared In
TextEdit.h

TEGetHeight

Returns the total height of all of the lines in the text between and including the specified starting and ending lines. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

long TEGetHeight (
   long endLine,
   long startLine,
   TEHandle hTE
);

Parameters
endLine

The number of the last line of text whose height is to be included in the total height. You can specify a value that is greater than or equal to 1 for this parameter.

startLine

The number of the first line of text whose height is to be included in the total height. You can specify a value that is greater than or equal to 1 for this parameter.

hTE

A handle to the edit structure containing the lines of text whose height is to be returned.

Return Value

The total height of all of the designated text lines.

Discussion

For monostyled text, the TEGetHeight function uses the value of the edit structure’s lineHeight field. For multistyled text, it uses the line height element (LHElement) of the line height table (LHTable). Note that TEGetHeight does not take into account the height of any blank lines at the end of the text. You need to consider this when scrolling text.

Availability
Declared In
TextEdit.h

TEGetHiliteRgn

Obtains the highlight region for the specified edit structure. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

OSErr TEGetHiliteRgn (
   RgnHandle region,
   TEHandle hTE
);

Return Value

A result code. See “TextEdit Result Codes.”

Availability
Declared In
TextEdit.h

TEGetOffset

Finds the byte offset of a character in an edit structure’s text that corresponds to the specified point. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

short TEGetOffset (
   Point pt,
   TEHandle hTE
);

Parameters
pt

A point in the displayed text of the specified edit structure.

hTE

A handle to the edit structure containing the text.

Return Value

The byte offset of the character at the specified point. In the case of a 2-byte character, the function returns the byte offset of the first byte.

Discussion

The TEGetOffset function works for both monostyled and multistyled edit structures.

Availability
Declared In
TextEdit.h

TEGetPoint

Determines the point that corresponds to the specified byte offset of a character and returns the coordinates of that point. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

Point TEGetPoint (
   short offset,
   TEHandle hTE
);

Parameters
offset

A byte offset into the text buffer of an edit structure.

hTE

A handle to the edit structure containing the text.

Return Value

The coordinates of the point that corresponds to the specified byte offset. The TEGetPoint function returns a valid result even when the edit structure does not contain any text. The point returned is based on the values in the structure’s destination rectangle.

In the case of an offset being equal to a line end, which is also the start of the next line, TEGetPoint returns a point corresponding to the line start of the next line. In the case of a dual caret, the primary caret position, the one corresponding to the primary line direction, is returned.

See the Mac Types documentation for a description of the Point data type.

Discussion

The line height, taken either from the lineHeight field for a monostyled edit structure or from the line-height array, LHElement , for a multistyled edit structure, is also used to determine the vertical component. Both the text direction and the primary line direction are used to determine the horizontal component.

The TEGetPoint function works for both monostyled and multistyled edit structures.

Availability
Declared In
TextEdit.h

TEGetRecalcHook

Obtains a universal procedure pointer to your recalculation callback. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TERecalcUPP TEGetRecalcHook (
   void
);

Return Value

See the description of the TERecalcUPP data type.

Availability
Declared In
TextEdit.h

TEGetScrapHandle

Returns a handle to the TextEdit private scrap. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

Handle TEGetScrapHandle (
   void
);

Return Value

See the Mac Types documentation for a description of the Handle data type.

Availability
Declared In
TextEdit.h

TEGetScrapLength

Returns the size of the TextEdit private scrap, in bytes. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

long TEGetScrapLength (
   void
);

Return Value

The size of the TextEdit private scrap, in bytes.

Availability
Declared In
TextEdit.h

TEGetStyle

Gets character attributes for the specified text. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEGetStyle (
   short offset,
   TextStyle *theStyle,
   short *lineHeight,
   short *fontAscent,
   TEHandle hTE
);

Parameters
offset

The offset to the text whose character attributes you want to obtain.

theStyle

On output, points to a structure of type TextStyle that contains the character attributes for the current selection range.

lineHeight

A pointer to a value that specifies the line height.

fontAscent

A pointer to a value that specifies the font ascent.

hTE

A handle to the multistyled edit structure containing the text whose character attributes you want to obtain.

Availability
Declared In
TextEdit.h

TEGetStyleHandle

Returns the style handle stored in the designated edit structure’s txFont and txFace fields. The style handle points to the associated style structure, not to a copy of it. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TEStyleHandle TEGetStyleHandle (
   TEHandle hTE
);

Parameters
hTE

A handle to the multistyled edit structure containing the style handle to be returned.

Return Value

A handle to the style structure contained in the specified edit structure (of type TEStyleRec). Because only multistyled edit structures have style structures, TEGetStyleHandle returns NULL when used with a monostyled edit structure. See the description of the TEStyleHandle data type.

Discussion

To ensure future compatibility, your application should always use this function rather than manipulate the fields of the edit structure directly.

Availability
Declared In
TextEdit.h

TEGetStyleScrapHandle

Creates a style scrap structure, copies the character attributes associated with the current selection range into it, and returns a handle to it. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

StScrpHandle TEGetStyleScrapHandle (
   TEHandle hTE
);

Parameters
hTE

The handle to the edit structure containing the text selection range whose character attributes are to be copied.

Return Value

A handle to the created style scrap structure, or NULL if called with a handle to a monostyled structure. See the description of the StScrpHandle data type.

Discussion

The TEGetStyleScrapHandle function creates a style scrap structure of type StScrpRec and copies the character attributes associated with the current selection range of the designated edit structure into it. If the current selection range is an insertion point, TEGetStyleScrapHandle first checks the null scrap. If the null scrap contains character attributes, they are written to the newly created style scrap structure. If the null scrap is empty, the attributes associated with the character preceding the insertion point are copied to the style scrap structure.

The TEGetStyleScrapHandle function has no impact on the Scrap Manager’s desk scrap.

Availability
Declared In
TextEdit.h

TEGetText

Returns a handle to the text of the specified edit structure. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

CharsHandle TEGetText (
   TEHandle hTE
);

Parameters
hTE

A handle to the edit structure containing the text whose handle you want returned. You pass this handle as an input parameter.

Return Value

A handle to the text contained in the specified edit structure. See page 82 for a description of the CharsHandle data type.

Discussion

Given an edit structure that contains text, you can use the TEGetText function to get a handle to the text itself. The TEGetText function doesn’t make a copy of the text. Rather, it returns the handle to the text which is stored as a packed array of characters. (This handle belongs to TextEdit your application must not destroy it.) The teLength field of the edit structure contains the length of the text whose handle is returned.

The handle of type CharsHandle that is returned by TEGetText corresponds to the hText field of the TERec structure.

Availability
Declared In
TextEdit.h

TEIdle

When called repeatedly, displays a blinking caret at the insertion point, if any exists, in the text of the specified edit structure of an active window. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEIdle (
   TEHandle hTE
);

Parameters
hTE

A handle to the edit structure.

Discussion

You need to call TEIdle only when the window containing the text is active; the caret is blinked only then. TextEdit observes a minimum blink interval, initially set to 32 ticks. No matter how often you call TEIdle, the time between blinks is never less than the minimum interval. (The user can adjust the minimum interval setting with the General Controls control panel.)

To maintain a constant frequency of blinking, you need to call TEIdle at least once each time through your main event loop. Call it more than once if your application does an unusually large amount of processing each time through the loop.

Call the Event Manager’s GetCaretTime function to get the blink rate.

Availability
Declared In
TextEdit.h

TEInsert

Inserts the specified text immediately before the selection range or the insertion point in the text of the designated edit structure, redrawing the text as necessary. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEInsert (
   const void *text,
   long length,
   TEHandle hTE
);

Parameters
text

A pointer to the text to be inserted.

length

The number of characters to be inserted.

hTE

A handle to the edit structure containing the text buffer into which the new text is to be inserted.

Discussion

When you call the TEInsert function and a range of text is selected, TEInsert doesn’t affect the selection range. The TEInsert function does not check for a 32 KB limit, so your application must ensure that the inserted text does not exceed this text size limit of 32 KB. The TEInsert function recalculates line starts and line heights to adjust for the inserted text.

Availability
Declared In
TextEdit.h

TEKey

Replaces the selection range in the text of the specified edit structure with the input character and positions the insertion point just past the inserted character. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEKey (
   CharParameter key,
   TEHandle hTE
);

Parameters
key

The input character.

hTE

A handle to the edit structure in whose text the character is to be entered.

Discussion

The TextEdit function TEKey allows you to handle key-down events and enter text input through the keyboard. If the selection range is an insertion point, TEKey inserts the character. (Two-byte characters are passed one byte at a time.)

If the key parameter contains a backspace character, the selection range or the character immediately before the insertion point is deleted. When the primary line direction is right-to-left, the character to the right of the insertion point is deleted. When the primary line direction is left-to-right, the character to the left of the insertion point is deleted.

When the user deletes text up to the beginning of a set of character attributes, TEKey saves the attributes in the null scrap’s style scrap structure. The attributes are saved temporarily to be applied to characters inserted after the deletion. As soon as the user clicks in another area of the text, TEKey removes the attributes. TEKey redraws the text as necessary.

Call TEKey every time the Event Manager function WaitNextEvent reports a keyboard event that your application determines should be handled by TextEdit.

Because TEKey inserts every character passed in the key parameter, your application must filter all characters which aren’t actual text, such as keys typed in conjunction with the Command key.

Availability
Declared In
TextEdit.h

TENew

Creates and initializes a monostyled edit structure and allocates a handle to it. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TEHandle TENew (
   const Rect *destRect,
   const Rect *viewRect
);

Parameters
destRect

A pointer to the destination rectangle for the new edit structure, specified in the local coordinates of the current graphics port. This is the area in which text is laid out.

viewRect

A pointer to the view, or visible, rectangle for the new edit structure, specified in the local coordinates of the current graphics port. This is the area of the window in which text is actually displayed.

Return Value

A handle to the newly created edit structure. Your application needs to store the handle to the edit structure that is returned; many functions require it as an input parameter. See the description of the TEHandle data type.

Discussion

A monostyled edit structure is one in which all text is restricted to a single font, size, and style. Use the TENew function when the text is to be rendered in attributes that are consistent from character to character. Otherwise, use the TEStyleNew function.

Call TENew once for every edit structure you want allocated. Your application should store the handle to the edit structure that is returned; many functions require it as an input parameter. The edit structure assumes the drawing environment of the graphics port.

If your application contains more than one window where text editing occurs, you need to create an edit structure for each window.

Before this function is called, the window must be in the current graphics port.

Availability
Declared In
TextEdit.h

TENumStyles

Returns the number of character attribute changes contained in the specified range, counting one for the start of the range. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

long TENumStyles (
   long rangeStart,
   long rangeEnd,
   TEHandle hTE
);

Parameters
rangeStart

The beginning of the range of text for which the number of style runs (sets of character attributes) or changes is counted and returned.

rangeEnd

The end of the range of text for which the number of style runs (sets of character attributes) or changes is counted and returned.

hTE

A handle to the edit structure containing the range of text.

Return Value

The number of character attribute changes contained in the specified range. This does not necessarily represent the number of unique sets of attributes for the range, because some sets of attributes may be repeated. For monostyled edit structures, TENumStyles always returns 1.

Availability
Declared In
TextEdit.h

TEPaste

Replaces the edit structure’s selected text with the contents of the private scrap and leaves an insertion point after the inserted text. If the selection range is an insertion point, TEPaste inserts the contents of the private scrap there. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEPaste (
   TEHandle hTE
);

Parameters
hTE

A handle to the edit structure into which the text is to be pasted.

Discussion

When you call TEPaste, after it pastes the text from the private scrap, it redraws all of the text as necessary. If the private scrap is empty, TEPaste deletes the selection range. If you call TEPaste for a multistyled edit structure, it pastes only the text in the private scrap. In this case, TEPaste ignores any associated character attribute information stored in the style scrap; instead, it applies the character attributes of the first character of the selection range being replaced to the text. If the selection range is an insertion point, TEPaste applies the character attributes of the character preceding the insertion point.

Availability
Declared In
TextEdit.h

TEPinScroll

Scrolls the text within the view rectangle of the specified edit structure by the designated number of pixels. Scrolling stops when the last line of text is scrolled into view. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEPinScroll (
   short dh,
   short dv,
   TEHandle hTE
);

Parameters
dh

The distance in pixels that the text is to be scrolled horizontally. A positive value moves the text to the right; a negative value moves the text to the left.

dv

The distance in pixels that the text is to be scrolled vertically. A positive value moves the text down; a negative value moves the text up.

hTE

A handle to the edit structure whose text is to be scrolled.

Discussion

The TEPinScroll function updates the text on the screen automatically to reflect the new scroll position, as does the TEScroll function. The destination rectangle is offset by the amount scrolled. When the edit structure is longer than the text it contains, TEPinScroll displays up to the last line of text inclusive, and not beyond it.

Availability
Declared In
TextEdit.h

TEReplaceStyle

Replaces any character attributes in the current selection range that match the specified existing character attributes with the specified new character attributes. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEReplaceStyle (
   short mode,
   const TextStyle *oldStyle,
   const TextStyle *newStyle,
   Boolean fRedraw,
   TEHandle hTE
);

Parameters
mode

A selector that specifies which attributes to replace. It corresponds to any additive combination of the “Text Styling Constants” for font, character style, type size, color, and so forth.

oldStyle

A pointer to a text style structure that specifies the current character attributes to search for in the selected text.

newStyle

A pointer to a text style structure that specifies the new attributes to be set. This structure contains the character attributes to be applied to the current selection range based on the value of mode.

fRedraw

A flag that specifies whether or not TextEdit should immediately redraw the text to reflect the attribute changes. A value of FALSE delays redrawing until another event forces the update. A value of TRUE causes the text to be redrawn immediately using the new character attributes.

hTE

A handle to the multistyled edit structure containing the text selection whose character attributes are to be changed.

Discussion

The TEReplaceStyle function replaces any attribute in the current selection range that matches the attribute specified by oldStyle with that given by newStyle. Only the character attributes specified by mode are affected.

Attribute changes are made directly to the style elements (STElement) within the style table itself (TEStyleTable). If you specify the value doAll for the mode parameter, newStyle replaces oldStyle outright. The TEReplaceStyle function has no effect on a monostyled edit structure.

Availability
Declared In
TextEdit.h

TEScrapHandle

Returns a handle to the TextEdit private scrap. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

Handle TEScrapHandle (
   void
);

Return Value

A handle to the TextEdit private scrap. See the Mac Types documentation for a description of the Handle data type.

Availability
Declared In
TextEdit.h

TEScroll

Scrolls the text within the view rectangle of the specified edit structure by the designated number of pixels. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEScroll (
   short dh,
   short dv,
   TEHandle hTE
);

Parameters
dh

The distance in pixels that the text is to be scrolled horizontally. A positive value moves the text to the right; a negative value moves the text to the left.

dv

The distance in pixels that the text is to be scrolled vertically. A positive value moves the text down; a negative value moves the text up.

hTE

A handle to the edit structure whose text is to be scrolled.

Discussion

The TEScroll function updates the text on the screen automatically to reflect the new scroll position. The destination rectangle is offset by the amount scrolled. The TEScroll and TEPinScroll functions behave the same, except that TEPinScroll stops scrolling when the last line of text is scrolled into view.

Availability
Declared In
TextEdit.h

TESelView

Ensures, once automatic scrolling has been enabled by a call to the TEAutoView function or through the TEFeatureFlag function, that the selection range is visible, scrolling it into the view rectangle if necessary. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESelView (
   TEHandle hTE
);

Parameters
hTE

A handle to the edit structure containing the text selection range.

Discussion

The top left part of the selection range is scrolled into view. If the text is displayed in a rectangle that is not high enough, automatic scrolling can cause text to appear to flicker. If automatic scrolling is disabled, TESelView has no effect. For more information, see TEFeatureFlag.

Availability
Declared In
TextEdit.h

TESetAlignment

Sets the alignment of the specified text in an edit structure so that it is centered, right aligned, or left aligned, or aligned according to the line direction. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetAlignment (
   short just,
   TEHandle hTE
);

Parameters
just

The alignment for the specified text.The default value of the just field of the edit structure is teFlushDefault. This means that text alignment is based on the primary line direction which is set by default according to the system script.

For a description of the values you can use in this parameter, see “Text Alignment Constants.”

hTE

A handle to the edit structure containing the text.

Discussion

For languages that are read from right to left, text is right aligned by default. For languages that are read from left to right, text is left aligned by default. If you change the alignment, call the Window Manager function InvalRect after TESetAlignment to redraw the text with the new alignment.

TextEdit does not support justified alignment. To draw justified text, use the QuickDraw Text functions.

Availability
Declared In
TextEdit.h

TESetClickLoop

Installs the address of the application-supplied click loop function in the clikLoop field of the edit structure. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetClickLoop (
   TEClickLoopUPP clikProc,
   TEHandle hTE
);

Parameters
clikProc

A universal procedure pointer to the customized click loop function.

hTE

A handle to the edit structure whose clikLoop field is to be modified.

Discussion

The TESetClickLoop function lets you replace the default click loop function. The TEClick function repeatedly calls the function that the click loop field points to as long as the user holds down the mouse button within the text of the view rectangle. The default click loop function scrolls only the text. However, you can provide a customized click loop function that scrolls the text and the scroll bars in tandem.

If automatic scrolling is enabled, the default click loop function checks to see if the mouse has been dragged out of the view rectangle; if it has, the function scrolls the text using TEPinScroll. The amount by which TEPinScroll scrolls the text vertically is determined by the lineHeight field of the edit structure for monostyled text and the LHTable for multistyled text.

Availability
Declared In
TextEdit.h

TESetDoTextHook

Sets your do-text-hook callback to be used by TextEdit. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetDoTextHook (
   TEDoTextUPP value
);

Availability
Declared In
TextEdit.h

TESetFindWordHook

Sets your set-find-word-hook callback to be used by TextEdit. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetFindWordHook (
   TEFindWordUPP value
);

Availability
Declared In
TextEdit.h

TESetRecalcHook

Sets your recalculation callback to be used by TextEdit. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetRecalcHook (
   TERecalcUPP value
);

Availability
Declared In
TextEdit.h

TESetScrapHandle

Sets a handle to the TextEdit private scrap. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetScrapHandle (
   Handle value
);

Availability
Declared In
TextEdit.h

TESetScrapLength

Sets the size of the TextEdit private scrap to the specified number of bytes. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetScrapLength (
   long length
);

Parameters
length

The size of the private scrap, in bytes.

Availability
Declared In
TextEdit.h

TESetSelect

Sets the selection range (or denotes the insertion point) within the text of the specified edit structure. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetSelect (
   long selStart,
   long selEnd,
   TEHandle hTE
);

Parameters
selStart

The byte offset at the start of the text selection range. The selStart field can range from 0 to 32767.

If selStart equals selEnd, the new selection range is an insertion point, and a caret is displayed. If selEnd is anywhere beyond the last character of the text, TESetSelect uses the first position past the last character.

selEnd

The byte offset at the end of the text selection range. The selEnd field can range from 0 to 32767.

hTE

A handle to the edit structure.

Discussion

The TESetSelect function removes highlighting of the old selection range and highlights the new one.

When only the Roman script system is used, the selection range is always displayed and highlighted as a continuous range of text. However, when one or more script systems requiring mixed-directional display of text are installed, a continuous sequence of characters in memory may appear as a discontinuous selection when displayed.

Availability
Declared In
TextEdit.h

TESetStyle

Sets new character attributes, in the specified edit structure, for the current selection range. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetStyle (
   short mode,
   const TextStyle *newStyle,
   Boolean fRedraw,
   TEHandle hTE
);

Parameters
mode

A selector that specifies which character attributes are to be changed. The value for mode can be any additive combination of the mode constants for font, style, type size, color, and so forth. It corresponds to any additive combination of the “Text Styling Constants” for font, character style, type size, color, and so forth.

The value of mode specifies which existing character attributes are to be changed to the new character attributes specified by newStyle. If doToggle is specified along with doFace and if an attribute specified in the given newStyle parameter exists across the entire selected range of text, then TESetStyle removes that attribute. Otherwise, if the attribute doesn’t exist across the entire selection range, all of the selected text is set to include that character attribute.

newStyle

A pointer to a structure of type TextStyle that specifies the new attributes to be set. This structure contains the character attributes to be applied to the current selection range based on the value of mode.

fRedraw

A flag that specifies whether or not TextEdit should immediately redraw the affected text to reflect the new character attribute changes. A value of TRUE causes the text to be redrawn immediately. Line breaks, line heights, and line ascents are recalculated. A value of FALSE delays redrawing until another event forces the update.

If the fRedraw parameter is set to TRUE, TextEdit redraws the current selection range using the new character attributes, recalculating line breaks, line heights, and line ascents.

If the fRedraw parameter is set to FALSE, TextEdit does not redraw the text or recalculate line breaks, line heights, and line ascents. Consequently, when you call a function that uses any of this information, such as TEGetHeight (which returns a total height between two specified lines), it does not reflect the new character attributes set with TESetStyle. Instead, the function uses the information that was available before TESetStyle was called. To update this information, call the TECalText function. To be certain that the new information is always reflected, call TESetStyle with the fRedraw parameter set to TRUE.

hTE

A handle to the multistyled edit structure containing the selected text.

Discussion

The TESetStyle function has no effect on a monostyled structure.

If you call the TESetStyle function when the value of the selStart field of an edit structure equals the value of the selEnd field (specifying an insertion point), TextEdit stores the input character attributes in the null scrap structure pointed to by the null style handle.

Availability
Declared In
TextEdit.h

TESetStyleHandle

Sets an edit structure’s style handle, which is stored in the txFont and txFace fields. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetStyleHandle (
   TEStyleHandle theHandle,
   TEHandle hTE
);

Parameters
theHandle

The style handle to be set in the combined txFont and txFace fields of the specified edit structure.

hTE

A handle to the edit structure.

Discussion

The TESetStyleHandle function has no effect on monostyled edit structures.

Your application should always use TESetStyleHandle rather than manipulate the fields of the edit structure directly.

Availability
Declared In
TextEdit.h

TESetText

Incorporates a copy of the specified text into the designated edit structure. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TESetText (
   const void *text,
   long length,
   TEHandle hTE
);

Parameters
text

A pointer to the text to be copied and incorporated.

length

The number of characters in the text to be incorporated.

hTE

A handle to the edit structure into which the text is to be copied.

Discussion

The function TESetText lets you incorporate existing text into the text buffer of an edit structure. The function copies the specified text into the existing hText handle of the edit structure, resizing the buffer, if necessary it doesn’t bring in the original text. The copied text is wrapped to the destination rectangle, and its lineStarts and nLines fields are calculated accordingly. The selection range is set to an insertion point at the end of the incorporated text. The TESetText function does not display the copied text on the screen. To do this, call TEUpdate.

Availability
Declared In
TextEdit.h

TEStyleInsert

Inserts the specified text immediately before the selection range or the insertion point in the edit structure’s text and applies the specified character attributes to the text, redrawing the text if necessary. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEStyleInsert (
   const void *text,
   long length,
   StScrpHandle hST,
   TEHandle hTE
);

Parameters
text

A pointer to the text to be inserted.

length

The length, in bytes, of the text to be inserted.

hST

A handle to the style scrap structure containing the character attribute information to be applied to the inserted text.

hTE

A handle to the edit structure into which the text is to be inserted.

Discussion

You should create your own style scrap structure, specifying the character attributes to be inserted and applied to the text, and pass its handle to TEStyleInsert as the value of the hST parameter. The character attributes are copied directly into the style structure’s (TEStyleRec) style table.

The TEStyleInsert function does not affect the current selection range.

Availability
Declared In
TextEdit.h

TEStyleNew

Creates a multistyled edit structure and allocates a handle to it. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

TEHandle TEStyleNew (
   const Rect *destRect,
   const Rect *viewRect
);

Parameters
destRect

A pointer to the destination rectangle for the new edit structure, specified in the local coordinates of the current graphics port. This is the area in which text is laid out.

viewRect

A pointer to the view rectangle for the new edit structure, specified in the local coordinates of the current graphics port. This is the area of the window in which text is actually displayed.

Return Value

A handle to the newly created edit structure. Your application needs to store the handle to the edit structure that is returned; many functions require it as an input parameter. See the description of the TEHandle data type.

Discussion

A multistyled edit structure contains text whose attributes, including font, size, and style, can vary from character to character. Always use the TEStyleNew function to create an edit structure for text that uses varying character attributes. The TEStyleNew function sets the txSize, lineHeight, and fontAscent fields of the edit structure to –1, allocates a style structure, and stores a handle to the style structure in the txFont and txFace fields. The TEStyleNew function creates and initializes a null scrap that is used by TextEdit functions throughout the life of the edit structure.

Call TEStyleNew once for every edit structure you want allocated. Your application needs to store the handle to the edit structure that is returned; many functions require it as an input parameter.

If your application contains more than one window where text editing occurs, you need to create an edit structure for each window.

Before this function is called, the window must be in the current graphics port.

Availability
Declared In
TextEdit.h

TEStylePaste

Pastes text and its associated character attribute information from the desk scrap into the edit structure’s text at the insertion point—if the current selection range is an insertion point—or it replaces the current selection range. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEStylePaste (
   TEHandle hTE
);

Parameters
hTE

A handle to the edit structure into which the text is to be pasted.

Discussion

When you call TEStylePaste and there is no character attribute information associated with text in the desk scrap, TEStylePaste first checks the null scrap. If the null scrap contains character attribute information, this is used. If the null scrap is empty, TEStylePaste gives the text the same attributes as those of the first character of the replaced selection range or that of the preceding character if the selection is an insertion point.

For a monostyled edit structure, TEStylePaste pastes the text only; there is no associated character attribute information because all the text uses the same attributes.

Availability
Declared In
TextEdit.h

TETextBox

Draws the indicated text in a given rectangle, with the specified alignment. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TETextBox (
   const void *text,
   long length,
   const Rect *box,
   short just
);

Parameters
text

A pointer to the text to be drawn.

length

The number of bytes comprising the text.

box

A pointer to the rectangle where the text is to be drawn. The rectangle is specified in local coordinates (of the current graphics port) and must be at least as wide as the first character drawn. (A good rule of thumb is to make the rectangle at least 20 pixels wide.

just

The kind of justification (alignment) used for the specified text.

Discussion

The TETextBox function provides you with an easy way to display static text to a user. It creates its own monostyled edit structure, which it deletes when finished with it, so you cannot edit the text it draws. The TETextBox function breaks a line of text correctly. You can specify how text is aligned in the box using any of the “Text Alignment Constants.”

Availability
Declared In
TextEdit.h

TEToScrap

Copies the contents of the TextEdit private scrap to the desk scrap. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

OSErr TEToScrap (
   void
);

Return Value

A result code. See “TextEdit Result Codes.”

Discussion

You use the TEToScrap function to move monostyled text across applications or between an application and a desk accessory. Call the Scrap Manager function ZeroScrap to initialize the desk scrap or clear its contents before calling TEToScrap.

Availability
Declared In
TextEdit.h

TEUpdate

Draws the specified text within a given update rectangle. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEUpdate (
   const Rect *rUpdate,
   TEHandle hTE
);

Parameters
rUpdate

The update rectangle, given in the coordinates of the current graphics port, where the specified text is to be drawn.

hTE

A handle to the edit structure containing the text to be drawn.

Discussion

Call TEUpdate every time the Event Manager function WaitNextEvent reports an update event for a text editing window—after you call the Window Manager function BeginUpdate , and before you call the EndUpdate function. You also need to erase the update region with the EraseRect function. If you don’t, the caret can sometimes remain visible when the window is deactivated.

Availability
Declared In
TextEdit.h

TEUseStyleScrap

Assigns new character attributes to the specified range of text in the designated edit structure. (Deprecated in Mac OS X v10.4. Use Multilingual Text Engine instead; see Handling Unicode Text Editing With MLTE.)

void TEUseStyleScrap (
   long rangeStart,
   long rangeEnd,
   StScrpHandle newStyles,
   Boolean fRedraw,
   TEHandle hTE
);

Parameters
rangeStart

The offset of the first character in the text of the edit structure to which the character attributes are to be applied.

rangeEnd

The offset of the last character in the text of the edit structure to which the character attributes are to be applied.

newStyles

A handle to a style scrap structure. The style scrap structure contains the attributes to be applied to the specified range of text. If the value of newStyles is NULL, no action is performed. Each element in the style scrap structure contains a field that is the offset of the beginning of the element’s character attributes. This field (scrpStartChar) defines the boundaries for the scrap’s style runs.

Depending on the requirements of your application, you can create a style scrap structure directly and pass its handle to TEUseStyleScrap as the value of newStyles or you can use a style scrap structure created by TEGetStyleScrapHandle.

fRedraw

A flag that specifies whether TextEdit should immediately redraw the selection range using the new character attributes. If the fRedraw parameter is set to TRUE, the attributes are applied immediately to the specified range of text, and line breaks, line heights, and line ascents are recalculated. If fRedraw is set to FALSE, the new character attributes are not reflected in the view rectangle until the next update event occurs.

hTE

A handle to the edit structure containing the range of text to which the character attributes are to be applied. If the handle points to a monostyled edit structure (created using TENew), no action is performed.

Discussion

The TEUseStyleScrap function writes the character attribute information into the style structure’s style table and updates the style run table.

Regardless of whether the text is redrawn, the current selection range is not changed; if characters are highlighted before TEUseStyleScrap is called, they remain highlighted after it is called. However, if characters within the current selection range also fall within the specified range of text, they are rendered in the new character attributes when the text is redrawn.

The TEUseStyleScrap function applies the first element’s attributes to the characters from rangeStart up to the scrpStartChar field of the next element. The function terminates without error if it prematurely reaches the end of the range or if there are not enough scrap style elements to cover the whole range. In the latter case, the function applies the last set of character attributes in the style scrap structure to the remainder of the range.

Availability
Declared In
TextEdit.h

< Previous PageNext 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.