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

Next Page > Hide TOC

Multilingual Text Engine Reference

Framework
Carbon/Carbon.h
Declared in
HITextViews.h
MacTextEditor.h

Overview

Multilingual Text Engine (MLTE) is an API that allows your application to provide Carbon-compliant Unicode text editing. This document is relevant for anyone who is writing an application that needs to display static Unicode text or provide Unicode-compliant text editing fields. You can also use MLTE if your application provides text editing support within a full-size window. For more information about basic text processing and using MLTE, see the document “Handling Unicode Text Editing with MLTE.”

Carbon fully supports the Multilingual Text Engine, and Apple recommends that you adopt Multilingual Text Engine as a replacement for TextEdit.

Functions by Task

Displaying Static Text

Initializing and Terminating MLTE

Working With MLTE Objects

Responding to Events

Working With HITextView

Editing Data

Managing Fonts and Font Menus

Managing Layout and Formatting

Managing Selections

Controlling the Frame and Window

Searching

Managing Files

Printing

Supporting Drag and Drop

Keeping Track of User Actions

Managing Spell Checking As You Type

Working with the Contextual Menu

Working With UPP Pointers for MLTE Callback Functions

Not Recommended

This section lists functions that are not recommended and you should no longer use. The Carbon Porting Notes for each function provide information on what you should do in place of using the function.

Unsupported Functions

This section lists functions that are not supported and cannot be called in Mac OS X.

Functions

DisposeTXNActionNameMapperUPP

Disposes of the universal procedure pointer (UPP) to your action name mapper callback function.

void DisposeTXNActionNameMapperUPP (
   TXNActionNameMapperUPP userUPP
);

Parameters
userUPP

The TXNActionNameMapperUPP that is to be disposed of.

Discussion

See the callback TXNActionNameMapperProcPtr for more information.

Availability
Declared In
MacTextEditor.h

DisposeTXNContextualMenuSetupUPP

Disposes of the universal procedure pointer (UPP) to your contextual menu setup callback function.

void DisposeTXNContextualMenuSetupUPP (
   TXNContextualMenuSetupUPP userUPP
);

Parameters
userUPP

The TXNContextualMenuSetupUPP that is to be disposed of.

Discussion

See the callback TXNContextualMenuSetupProcPtr for more information.

Availability
Declared In
MacTextEditor.h

DisposeTXNFindUPP

Disposes of the universal procedure pointer (UPP) to your find callback function.

void DisposeTXNFindUPP (
   TXNFindUPP userUPP
);

Discussion

See the callback TXNFindProcPtr for more information.

Availability
Declared In
MacTextEditor.h

DisposeTXNScrollInfoUPP

Disposes of the universal procedure pointer (UPP) to your scrolling callback function.

void DisposeTXNScrollInfoUPP (
   TXNScrollInfoUPP userUPP
);

Discussion

See the callback TXNScrollInfoProcPtr for more information.

Availability
Declared In
MacTextEditor.h

HITextViewCopyBackgroundColor

Obtains the background color of the view.

OSStatus HITextViewCopyBackgroundColor (
   HIViewRef inTextView,
   CGColorRef *outColor
);

Parameters
inTextView

The HITextView associated with the text object whose background color you want to copy.

outColor

A CGColorRef representing the color or pattern that is used for drawing the background of the text view. If the returned CGColorRef is not NULL, it is retained on return. You are responsible for releasing this CGColorRef when you are no longer referencing it. If the returned value is NULL, the background is not drawn.

Return Value

A result code. See “MLTE Result Codes.”

Availability
Declared In
HITextViews.h

HITextViewCreate

Creates an HITextView that is initially invisible.

OSStatus HITextViewCreate (
   const HIRect *inBoundsRect,
   OptionBits inOptions,
   TXNFrameOptions inTXNFrameOptions,
   HIViewRef *outTextView
);

Parameters
inBoundsRect

The bounding box of the view. Pass NULL, if you want to initialize the bounds of the view to 0.

inOptions

Reserved for future use; you must pass 0.

inTXNFrameOptions

The frame options you want to set for the text view.

outTextView

On output, points to the newly-created text view.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

An HITextView is an MLTE text view that can be embedded in the HIView hierarchy. The view can be embedded in an HIScrollView if you want scroll bars and can also be used in a composited window. For more information on HIView, see the document Introducing HIView, available from the Apple Developer Documentation website.

When you call the function HITextViewCreate to create a text view, an MLTE text object (TXNObject) is allocated and attached to the text view. You can extract the text object by calling the function HITextViewGetTXNObject. You can supply the extracted text object as a parameter to many of the MLTE functions that take a text object as a parameter. However, not all MLTE functions that take a text object can operate on an MLTE object that comes from an HITextView. In general, you cannot use MLTE functions that may alter the geometry of the object or explicitly invoke drawing. If you do, the function returns the result code kTXNDisabledFunctionalityErr.

The following MLTE functions return an error if you pass a text object that comes from an HITextView:

Availability
Declared In
HITextViews.h

HITextViewGetTXNObject

Obtains the text object associated with an HITextView.

TXNObject HITextViewGetTXNObject (
   HIViewRef inTextView
);

Parameters
inTextView

The HITextView associated with the text object you want to retrieve.

Return Value

Returns the text object associated with the given view.

Discussion

You can supply the extracted text object as a parameter to many of the MLTE functions that take a text object as a parameter. However, not all MLTE functions that take a text object can operate on an MLTE object that comes from an HITextView. In general, you cannot use MLTE functions that may alter the geometry of the object or explicitly invoke drawing. If you do, the function returns the result code kTXNDisabledFunctionalityErr. See HITextViewCreate for a list of the functions that return an error if you pass a text object that comes from an HITextView.

Availability
Declared In
HITextViews.h

HITextViewSetBackgroundColor

Sets the background color of the view.

OSStatus HITextViewSetBackgroundColor (
   HIViewRef inTextView,
   CGColorRef inColor
);

Parameters
inTextView

The HITextView whose background color is to be set.

inColor

A CGColorRef representing the color or pattern that is to fill the background of the text view. The CGColorRef is retained by this function. If the text view already contains a background color, it is released prior to the new color being retained. If inColor is NULL, the background of the text view will not draw.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

This function allows you to provide alpha.

Availability
Declared In
HITextViews.h

InvokeTXNActionNameMapperUPP

Calls your action name mapper callback function.

CFStringRef InvokeTXNActionNameMapperUPP (
   CFStringRef actionName,
   UInt32 commandID,
   void *inUserData,
   TXNActionNameMapperUPP userUPP
);

Parameters
actionName

The action name.

commandID

The command ID of the menu item that is to be mapped.

iUserData

A pointer to user-defined data that will be passed to your action name mapper callback.

userUPP

The callback function that is to be called. For more information, see NewTXNActionNameMapperUPP.

Return Value

A CFStringRef.

Availability
Declared In
MacTextEditor.h

InvokeTXNContextualMenuSetupUPP

Calls your contextual menu setup callback function.

void InvokeTXNContextualMenuSetupUPP (
   MenuRef iContextualMenu,
   TXNObject object,
   void *inUserData,
   TXNContextualMenuSetupUPP userUPP
);

Parameters
iContextualMenu

The contextual menu.

object

The TXNObject for which the contextual menu is to be displayed.

iUserData

A pointer to user-defined data that will be passed to your contextual menu setup callback.

userUPP

The callback function that is to be called. For more information, see NewTXNContextualMenuSetupUPP.

Availability
Declared In
MacTextEditor.h

InvokeTXNFindUPP

Calls your find callback function.

OSStatus InvokeTXNFindUPP (
   const TXNMatchTextRecord *matchData,
   TXNDataType iDataType,
   TXNMatchOptions iMatchOptions,
   const void *iSearchTextPtr,
   TextEncoding encoding,
   TXNOffset absStartOffset,
   ByteCount searchTextLength,
   TXNOffset *oStartMatch,
   TXNOffset *oEndMatch,
   Boolean *ofound,
   URefCon refCon,
   TXNFindUPP userUPP
);

Return Value

A result code. See “MLTE Result Codes.”

Discussion

You can call an invoke function rather than calling your routine directly if you want to support code portability across compiler targets. See the callback TXNFindProcPtr for parameter descriptions and other information.

Availability
Declared In
MacTextEditor.h

InvokeTXNScrollInfoUPP

Calls your scrolling callback function.

void InvokeTXNScrollInfoUPP (
   SInt32 iValue,
   SInt32 iMaximumValue,
   TXNScrollBarOrientation iScrollBarOrientation,
   SRefCon iRefCon,
   TXNScrollInfoUPP userUPP
);

Discussion

You can call an invoke function rather than calling your routine directly if you want to support code portability across compiler targets. See the callback TXNScrollInfoProcPtr for parameter descriptions and other information.

Availability
Declared In
MacTextEditor.h

NewTXNActionNameMapperUPP

Creates a new universal procedure pointer (UPP) to an action name mapper callback function.

TXNActionNameMapperUPP NewTXNActionNameMapperUPP (
   TXNActionNameMapperProcPtr userRoutine
);

Parameters
userRoutine

The action name mapper callback function for which a UPP is to be created.

Return Value

A universal procedure pointer.

Discussion

See the callback TXNActionNameMapperProcPtr for more information.

Availability
Declared In
MacTextEditor.h

NewTXNContextualMenuSetupUPP

Creates a new universal procedure pointer (UPP) to a contextual menu setup callback function.

TXNContextualMenuSetupUPP NewTXNContextualMenuSetupUPP (
   TXNContextualMenuSetupProcPtr userRoutine
);

Parameters
userRoutine

The contextual menu setup callback function for which a UPP is to be created.

Return Value

A universal procedure pointer.

Discussion

For more information, see the callback TXNContextualMenuSetupProcPtr.

Availability
Declared In
MacTextEditor.h

NewTXNFindUPP

Creates a new universal procedure pointer (UPP) to a find callback function that uses your criteria for matching.

TXNFindUPP NewTXNFindUPP (
   TXNFindProcPtr userRoutine
);

Return Value

A universal procedure pointer.

Discussion

See the callback TXNFindProcPtr for more information.

Availability
Declared In
MacTextEditor.h

NewTXNScrollInfoUPP

Creates a new universal procedure pointer (UPP) to a scrolling callback function.

TXNScrollInfoUPP NewTXNScrollInfoUPP (
   TXNScrollInfoProcPtr userRoutine
);

Return Value

A universal procedure pointer.

Discussion

See the callback TXNScrollInfoProcPtr for more information.

Availability
Declared In
MacTextEditor.h

TXNAdjustCursor

Obtains the current cursor position and draws the cursor in a form appropriate to the content over which it is placed.

void TXNAdjustCursor (
   TXNObject iTXNObject,
   RgnHandle ioCursorRgn
);

Parameters
iTXNObject

The text object that identifies the text area for which MLTE should adjust the cursor.

ioCursorRgn

A handle to a region created by your application. Pass NULL if you do not want TXNAdjustCursor to provide information about the cursor position to your application. If you do want to obtain the cursor’s current position, pass a valid region handle in this parameter. If you pass a valid region handle and the cursor is over the text area or its scroll bars, on return TXNAdjustCursor sets the region to a 2-pixel by 2-pixel square, centered on the cursor’s hot spot. If the cursor is not over the text area or its scroll bars, or if you have passed NULL, TXNAdjustCursor does not adjust the input value.

Discussion

If the cursor is over a text area, TXNAdjustCursor sets the cursor to an I-beam. If the cursor is over graphics, a sound file, a movie, a scroll bar, or outside of a window, TXNAdjustCursor sets the cursor to an arrow. Before you call the TXNAdjustCursor function, you should make sure that the window belongs to your application.

You can pass the region handle returned by the TXNAdjustCursor function in the ioCursorRgn parameter to the WaitNextEvent function; this ensures that you receive mouse-moved events if the cursor moves outside that region. If you then receive a mouse-moved event, you can call TXNAdjustCursor again to ensure that the cursor type is appropriate to its new position. Alternately, to ensure that the cursor is adjusted correctly, you can simply call TXNAdjustCursor with every event that your application receives.

Availability
Declared In
MacTextEditor.h

TXNAttachObjectToWindowRef

Attaches a text object to a window.

OSStatus TXNAttachObjectToWindowRef (
   TXNObject iTXNObject,
   WindowRef iWindowRef
);

Parameters
iTXNObject

The text object with which you want to associate the window. You can call the function TXNCreateObject to allocate a text object.

iWindowRef

A WindowRef that specifies the window to which you want to attach the text object.

Return Value

A result code. See “MLTE Result Codes.” Returns paramErr if the text object that you pass is invalid.

Availability
Declared In
MacTextEditor.h

TXNBeginActionGroup

Starts an action group.

OSStatus TXNBeginActionGroup (
   TXNObject iTXNObject,
   CFStringRef iActionGroupName
);

Parameters
iTXNObject

The text object for which an action group is to be started.

iActionGroupName

A client-supplied string that is to be used to describe the action group.

Return Value

A result code. See “MLTE Result Codes.” The error kTXNOperationNotAllowedErr is returned if an undo action group has already been started but has not yet terminated.

Discussion

Every supported edit action after TXNBeginActionGroup is called is added to the group untilTXNCanUndoAction is called. When MLTE receives an undo or redo command, it treats all actions added to the group as a single operation to undo or redo. Nesting of groups is not allowed. Calling TXNBeginActionGroup twice without calling TXNCanUndoAction in between results in an error. If an action group is active, TXNCanUndoAction and TXNCanRedoAction return false.

Availability
Declared In
MacTextEditor.h

TXNCanRedoAction

Indicates whether an action can be redone.

Boolean TXNCanRedoAction (
   TXNObject iTXNObject,
   CFStringRef *oActionName
);

Parameters
iTXNObject

The text object having an action that is to be queried.

oActionName

On input, a pointer a CFStringRef that, on return, contains the name of the action that can be redone, if there is one. The returned string is either a string defined by MLTE or the string that you passed to TXNBeginActionGroup to create a new action group. You are responsible for retaining and releasing the string. Pass NULL if you don’t want to receive the name of the action.

Return Value

A Boolean whose value is true if the last action can be redone; you should enable the Redo item in the Edit menu, if there is one. If this function returns false, the last action cannot be redone and you should not enable the Redo item in the Edit menu.

Discussion

This function tells the client whether the current item on the undo stack is redoable and is usually used to determine whether the Redo item in the Edit menu should be enabled. This function optionally obtains the action name that should be used in the Redo item. When the current undo item is an action group, the string used to name the group is returned. For information on action groups, see TXNBeginActionGroup and TXNEndActionGroup.

Availability
Declared In
MacTextEditor.h

TXNCanUndoAction

Indicates whether an action can be undone.

Boolean TXNCanUndoAction (
   TXNObject iTXNObject,
   CFStringRef *oActionName
);

Parameters
iTXNObject

The text object having an action that is to be queried.

oActionName

On input, a pointer a CFStringRef that, on return contains the name of the action that can be undone, if there is one. The returned string is either a string defined by MLTE or the string that you passed to TXNBeginActionGroup to create a new action group. You are responsible for retaining and releasing the string. Pass NULL if you don’t want to receive the name of the action.

Return Value

A Boolean whose value is true if the last action can be undone; you should enable the Undo item in the Edit menu, if there is one. If this function returns false, the last action cannot be undone and you should not enable the Undo item in the Edit menu.

Discussion

This function is usually used to determine whether the Undo item in the Edit menu should be enabled and to obtain the action name that should be used in that item. When the last action is an action group, the string used to name the group is returned.

If you have asked MLTE to handle updating for the Redo and Undo commands in the Edit menu, you should call TXNSetActionNameMapper after calling TXNCanUndoAction so that MLTE can call back to get the correct strings for those items.

Availability
Declared In
MacTextEditor.h

TXNClear

Deletes the current selection.

OSStatus TXNClear (
   TXNObject iTXNObject
);

Parameters
iTXNObject

The text object for the current text area.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

To remove a selected object from a text area, a user can either press the Delete key or choose Clear from the Edit menu. Before you call the TXNClear function, you can use the TXNIsSelectionEmpty function to determine whether any text is selected. Unlike the function TXNCut, the TXNClear function does not add the deleted selection to the private MLTE scrap.

Availability
Declared In
MacTextEditor.h

TXNClearCountForActionType

Sets the counter for the specified action type to zero.

OSStatus TXNClearCountForActionType (
   TXNObject iTXNObject,
   CFStringRef iActionTypeName
);

Parameters
iTXNObject

The text object having one or more counters that are to be set to zero.

iActionTypeName

The action type for which the counter is to be set to zero. This parameter can be a string that was passed to TXNBeginActionGroup or one of the constants described inAction Constants.

Return Value

A result code. See “MLTE Result Codes.”

Availability
Declared In
MacTextEditor.h

TXNClick

Processes a mouse-down event in a window’s content area. 

void TXNClick (
   TXNObject iTXNObject,
   const EventRecord *iEvent
);

Parameters
iTXNObject

The text object in which the mouse-down event occurred.

iEvent

A pointer to the event record that contains the mouse-down event to process.

Discussion

When you pass the event to the TXNClick function, it responds to the user’s action by scrolling, selecting text, playing a sound or movie, handling a drag–and-drop operation, or responding to a double- or triple-click, as appropriate. Before you call TXNClick, you should make sure that the front window belongs to your application.

Availability
Declared In
MacTextEditor.h

TXNCopy

Copies the current selection to the private MLTE scrap.

OSStatus TXNCopy (
   TXNObject iTXNObject
);

Parameters
iTXNObject

The text object for the current text area.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

You can use the TXNCopy function to respond to a user-requested copy action. Before you call TXNCopy, you can use the TXNIsSelectionEmpty function to determine whether any text is selected.

The TXNCopy function copies the current selection to the MLTE scrap. In a Carbon application, the Scrap Manager automatically converts your application’s private scrap to the Clipboard so it is available to other applications. In a Classic application, you must call the function TXNConvertToPublicScrap after you call TXNCopy.

Availability
Declared In
MacTextEditor.h

TXNCopyTypeIdentifiersForRange

Obtains an array of universal type identifiers for a TXNObject.

OSStatus TXNCopyTypeIdentifiersForRange (
   TXNObject iTXNObject,
   TXNOffset iStartOffset,
   TXNOffset iEndOffset,
   CFArrayRef *oTypeIdentifiersForRange
);

Parameters
iTXNObject

The text object.

iStartOffset

The starting offset in iTXNObject.

iEndOffset

The ending offset in iTXNObject.

oTypeIdentifiersForRange

A pointer to a CFArrayRef. On return, the array contains the list of universal type identifiers that MLTE supports. Each entry in the array is a CFStringRef.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

Some file formats support limited embedding of data when writing to disk, and use attachments, such as Rich Text Format (RTF), instead.

Use this function to get a list of universal type identifiers that can be used when calling TXNWriteRangeToCFURL to write the object out to disk with no data loss. Note that support for new document formats could be added in the future.

Availability
Declared In
MacTextEditor.h

TXNCountRunsInRange

Obtains a count of the style runs in a range of data.

OSStatus TXNCountRunsInRange (
   TXNObject iTXNObject,
   TXNOffset iStartOffset,
   TXNOffset iEndOffset,