ADC Home > Reference Library > Reference > Carbon > Text & Fonts > Multilingual Text Engine Reference >

< Previous PageNext Page > Hide TOC

Deprecated Multilingual Text Engine Functions

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

Deprecated in Mac OS X v10.2

TXNSetViewRect

Sets the rectangle that describes the current view into the document; changes the amount of text that is viewable. (Deprecated in Mac OS X v10.2. Use TXNSetFrameBounds or TXNSetRectBounds instead.)

Not recommended.

void TXNSetViewRect (
   TXNObject iTXNObject,
   const Rect *iViewRect
);

Parameters
iTXNObject

The text object for the current text area.

iViewRect

On input, points to a rectangle that describes the new view of the document.

Discussion

The TXNSetViewRect function does not change where a line of text wraps. Line wrapping is controlled by the TXNSetFrameBounds function.

Availability
Declared In
MacTextEditor.h

Deprecated in Mac OS X v10.3

TXNActivate

Sets the state of the scroll bars so they are drawn correctly in response to activate events. (Deprecated in Mac OS X v10.3. Use TXNSetScrollbarState instead.)

Not recommended.

OSStatus TXNActivate (
   TXNObject iTXNObject,
   TXNFrameID iTXNFrameID,
   TXNScrollBarState iActiveState
);

Parameters
iTXNObject

The text object that identifies the document to be activated.

iTXNFrameID

The frame ID of the document that is to be activated. You obtain a frame ID from TXNNewObject when you create a text object.

iActiveState

A value that indicates the state of the scroll bars. See Scroll Bar States for a description of possible values. If you pass the kScrollBarsAlwaysActive constant, the scroll bars are always active, whether or not the frame’s text area currently has keyboard focus. Passing kScrollBarsAlwaysActive can be useful for a window such as a dialog box that may contain multiple text areas, each of which may have a scrollable frame. If you pass kScrollBarsSyncWithFocus, MLTE synchronizes the activity state of the scroll bars with the focus state of the frame. Therefore, only when the frame has keyboard focus does it have active scroll bars. A value of kScrollBarsSyncWithFocus is the default and is typically recommended if you have only one frame per window.

Return Value

A result code. See “MLTE Result Codes.” TXNActivate returns a parameter error if you pass an invalid text object or frame ID.

Discussion

You typically call TXNActivate in response to an activate event. If the text object was previously inactive, TXNActivate removes any visual indication of its prior inactive state (such as a dimmed or framed selection area or inactive scroll bars). Before you call the TXNActivate function, you should make sure that the window belongs to your application.

The TXNActivate function does not change the keyboard focus. This means your application can have a text area that is not focused, but in which the scroll bars are active. This lets application users scroll the inactive text without changing the focus from another text area.

If you want to display a text area that has both keyboard focus and active scroll bars, you must call the TXNFocus function immediately before you call the TXNActivate function. Note that MLTE does not retain information about keyboard focus. So if, for example, you set the keyboard focus on a text area and the window containing the text area becomes deactivated, you must call the TXNFocus function when the window becomes activated again.

Availability
Declared In
MacTextEditor.h

TXNAttachObjectToWindow

Attaches a text object to a window. (Deprecated in Mac OS X v10.3. Use TXNAttachObjectToWindowRef instead.)

Not recommended.

OSStatus TXNAttachObjectToWindow (
   TXNObject iTXNObject,
   GWorldPtr iWindow,
   Boolean iIsActualWindow
);

Parameters
iTXNObject

The text object with which you want to associate the window.

iWindow

A pointer to the graphics port to which the object should be attached. The graphics port may be a window (WindowRef) or a generic graphics port (CGrafPtr, GWorldPtr). If it is a window, note that you must typecast the window reference to a GWorldPtr data type.

iIsActualWindow

A Boolean value. Pass true if the iWindow parameter you passed refers to a Window Manager window (WindowRef), not a generic graphics port. Pass false if the iWindow parameter you passed does not refer to a window. If you pass false, MLTE never calls window-specific functions such as InvalRect or BeginUpdate for this text object, and it is your program’s responsibility to handle any window-related functionality.

Return Value

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

Discussion

You may create a text object without an associated window pointer by passing NULL in the iWindow parameter of the TXNNewObject function. However, if you do so, you must call the TXNAttachObjectToWindow function to associate a window with that object before you call any other MLTE function.

Availability
Declared In
MacTextEditor.h

TXNConvertFromPublicScrap

Converts the Clipboard content to the private MLTE scrap. (Deprecated in Mac OS X v10.3. This function isn't needed in Mac OS X.)

Not recommended.

OSStatus TXNConvertFromPublicScrap (
   void
);

Return Value

A result code. See “MLTE Result Codes.”

Discussion

You should call the TXNConvertFromPublicScrap function after another application has modified the contents of the Clipboard. Calling the TXNConvertFromPublicScrap function ensures that the contents of the system Clipboard are available to your application. Typically, when you receive a resume event, you call the Scrap Manager function GetCurrentScrap to determine whether the Clipboard content has been modified. If so, you should then call TXNConvertFromPublicScrap.

Special Considerations

The function TXNConvertFromPublicScrap is no longer needed in Mac OS X version 10.2 and later. Calling the function TXNPaste automatically handles conversion from public scrap.

Availability
Declared In
MacTextEditor.h

TXNConvertToPublicScrap

Converts the private MLTE scrap content to the Clipboard. (Deprecated in Mac OS X v10.3. This function isn't needed in Mac OS X.)

Not recommended.

OSStatus TXNConvertToPublicScrap (
   void
);

Return Value

A result code. See “MLTE Result Codes.”

Availability
Declared In
MacTextEditor.h

TXNDraw

Redraws the text area, including any scroll bars associated with the text frame. (Deprecated in Mac OS X v10.3. Use the TXNDrawObject .)

Not recommended.

void TXNDraw (
   TXNObject iTXNObject,
   GWorldPtr iDrawPort
);

Parameters
iTXNObject

The text object whose text is to be redrawn.

iDrawPort

A value of type GWorldPtr. Pass a valid pointer or NULL. If you pass NULL, the TXNDraw function redraws the text area into the port that is currently associated with the text object. If you pass a valid pointer instead of NULL, TXNDraw redraws the text area into the specified port, and does not update the selection. You should pass NULL if you want to draw on the screen but pass a valid pointer if you want to take a snapshot of the screen to save or print.

Discussion

You can call the TXNDraw function in response to an update event for a window that contains multiple text objects or other graphic elements. If necessary, your application is also responsible for calling the Window Manager functions BeginUpdate and EndUpdate in response to the update event.

If there is nothing in your window except a single MLTE text object, you should call the TXNUpdate function to redraw the area instead of calling TXNDraw. The TXNUpdate f unction draws everything in the frame, and you do not have to call the Window Manager functions BeginUpdate and EndUpdate yourself.

Availability
Declared In
MacTextEditor.h

TXNGetRectBounds

Obtains the values for the current view, destination, and text rectangles. (Deprecated in Mac OS X v10.3. Use TXNGetHIRect instead.)

Not recommended.

OSStatus TXNGetRectBounds (
   TXNObject iTXNObject,
   Rect *oViewRect,
   TXNLongRect *oDestinationRect,
   TXNLongRect *oTextRect
);

Parameters
iTXNObject

The text object for the current text area.

oViewRect

On output, a pointer to the Rect data structure that contains the coordinates for the view rectangle. If you do not want to obtain this structure, pass NULL. The view rectangle specifies the area of the text you see. Scroll bars are drawn inside the view rectangle.

oDestinationRect

On output, a pointer to the TXNLongRect data structure that contains the coordinates for the destination rectangle. If you do not want to obtain this structure, pass NULL. The destination rectangle controls how text is laid out.

oTextRect

On output, a pointer to the TXNLongRect data structure that contains the coordinates for the text rectangle. If you do not want to obtain this structure, pass NULL. The text rectangle is the smallest rectangle needed to contain the current text. MLTE calculates the text rectangle by measuring each line of text. So this can be slow performance. The width of the text rectangle is the width of the longest line in the text.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

You need only to pass pointers for the rectangles for which you want to obtain coordinates.

Availability
Declared In
MacTextEditor.h

TXNIsObjectAttachedToSpecificWindow

Determines whether a text object is attached to a specified window. (Deprecated in Mac OS X v10.3. Use TXNGetWindowRef instead.)

Not recommended.

OSStatus TXNIsObjectAttachedToSpecificWindow (
   TXNObject iTXNObject,
   WindowRef iWindow,
   Boolean *oAttached
);

Parameters
iTXNObject

The text object that identifies the document you want to check.

iWindow

A reference to the window against which to check attachment.

oAttached

On output, true if the text object is attached to the specified window; false otherwise.

Return Value

A result code. See “MLTE Result Codes.”

Availability
Declared In
MacTextEditor.h

TXNIsObjectAttachedToWindow

Checks to see if a text object is attached to a window. (Deprecated in Mac OS X v10.3. Use TXNGetWindowRef instead.)

Not recommended.

Boolean TXNIsObjectAttachedToWindow (
   TXNObject iTXNObject
);

Parameters
iTXNObject

The text object that identifies the document you want to check.

Return Value

A Boolean value; returns true if the object is attached.

Discussion

You can call this before you call the TXNAttachObjectToWindow function to make sure the text object is not already attached to a window. If you pass NULL in the iWindow parameter of TXNNewObject you create a text object without an associated window pointer.

Availability
Declared In
MacTextEditor.h

TXNNewObject

Creates a new MLTE text object which is an opaque structure that handles text formatting at the document level. (Deprecated in Mac OS X v10.3. Use TXNCreateObject instead.)

Not recommended.

OSStatus TXNNewObject (
   const FSSpec *iFileSpec,
   WindowRef iWindow,
   const Rect *iFrame,
   TXNFrameOptions iFrameOptions,
   TXNFrameType iFrameType,
   TXNFileType iFileType,
   TXNPermanentTextEncodingType iPermanentEncoding,
   TXNObject *oTXNObject,
   TXNFrameID *oTXNFrameID,
   TXNObjectRefcon iRefCon
);

Parameters
iFileSpec

A pointer to a variable of type FSSpec. If you pass NULL you start with an empty document. Otherwise, the contents of the file to which iFileSpec points are read into the object. The referenced file must consist entirely of data that MLTE can read ('TEXT', 'RTF ', 'utxt', or 'txtn'). If the referenced file contains your application’s private data and data that MLTE can read, you should call the TXNNewObject function with the iFileSpec parameter set to NULL. Once TXNNewObject creates the text object, your application can read the private data into the text object by calling the TXNSetDataFromFile function.

iWindow

A reference to the window in which the document will be displayed. This parameter can be NULL. If it is NULL, you must attach a window or graphics port to the text object by using the TXNAttachObjectToWindow function.

iFrame

A pointer to a variable of type Rect. If you pass NULL, the window’s portRect rectangle is used as the frame. If you do not want to fill the entire window, you use the iFrame parameter to specify the area to fill.

iFrameOptions

A value that specifies the options you want the frame to support. See Frame Option Masks for a description of possible values.

If you want to create a read-only document, you need to pass the option kTXNReadOnlyMask. Note that this option puts the text object into a state that does not allow user input. However, your application can put data into the text object by calling the function TXNSetData. If you want the text object set into a more restrictive read-only state that does not allow user input or your application to put data into the text object programmatically, you need to call the function TXNSetTXNObjectControls, passing the tag kTXNIOPrivilegesTag. If you choose to set the text object into this restrictive state, you will get an error if you try to call the function TXNSetData on the text object. (In this case, you can change the text object to a less restrictive state by calling TXNSetTXNObjectControls, passing the tag kTXNNoUserIOTag.)

iFrameType

A value that specifies the frame type of the text object. See Supported Frame Types for a description of possible values.

iFileType

A value that specifies the file type of the text object. See Supported File Types for a description of possible values. You should specify the primary file type. If you use the kTXNTextensionFile constant, files are saved in a custom format. If you want saved files to be plain text files, you should specify the kTXNTextFile constant, then use the iframeOptions parameter to specify whether the plain text files should be saved with kTXNSingleStylePerTextDocumentResType or kTXNMultipleStylesPerTextDocumentResType resources.

iPermanentEncoding

A value that specifies the encoding in which the document is saved. See Text Encoding Preferences for a description of possible values.

oTXNObject

A pointer to a structure of type TXNObject. On return, this points to the opaque text object data structure allocated by the function. You need to pass this object to most MLTE functions.

oTXNFrameID

On return, a pointer to the unique ID for the text object’s frame. However, in MLTE version 1.1 and earlier, the frame ID is always set to 0.

iRefCon

A value of type TXNObjectRefcon. You can define how to use this for your application. You can set this to any value and retrieve it later.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

For each document, a new text object is allocated by the TXNNewObject function and returned in the oTXNObject parameter. The object is allocated only if no errors occur, including errors that may occur when reading a file. If there is an error during the allocation process, MLTE frees the text object.

If you are writing a text editing application, you may want to call the TXNNewObject function when the application launches (a new document will be displayed) and whenever the user selects New from the File menu.

Many MLTE functions require you to pass a text object; some functions also require the frame ID supplied back to your application in the oTXNFrameID parameter of TXNNewObject.

Because of how MLTE uses Carbon events internally, the window in which the document is displayed must have the standard event handlers installed. You can do this in one of the following ways:

Availability
Declared In
MacTextEditor.h

TXNOffsetToPoint

Gets the local coordinates of the point that corresponds to a specified offset of a text object. (Deprecated in Mac OS X v10.3. Use TXNOffsetToHIPoint instead.)

Not recommended.

OSStatus TXNOffsetToPoint (
   TXNObject iTXNObject,
   TXNOffset iOffset,
   Point *oPoint
);

Parameters
iTXNObject

The text object for which you want to obtain the local coordinates of a point.

iOffset

An offset value.

oPoint

On return, a pointer to the local coordinates of the point that corresponds to the value of the iOffset parameter.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

Offsets in MLTE are always character offsets.

Availability
Declared In
MacTextEditor.h

TXNPointToOffset

Gets the offset value that corresponds to a point in local coordinates. (Deprecated in Mac OS X v10.3. Use TXNHIPointToOffset instead.)

Not recommended.

OSStatus TXNPointToOffset (
   TXNObject iTXNObject,
   Point iPoint,
   TXNOffset *oOffset
);

Parameters
iTXNObject

The text object for which you want to obtain an offset value.

iPoint

The local coordinates of a point.

oOffset

On return, a pointer to the offset that corresponds to the value of the iPoint parameter.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

Offsets in MLTE are always character offsets.

Availability
Declared In
MacTextEditor.h

TXNSetDataFromFile

Replaces a range of data with the contents of a file. (Deprecated in Mac OS X v10.3. Use TXNSetDataFromCFURLRef instead.)

Not recommended.

OSStatus TXNSetDataFromFile (
   TXNObject iTXNObject,
   SInt16 iFileRefNum,
   OSType iFileType,
   ByteCount iFileLength,
   TXNOffset iStartOffset,
   TXNOffset iEndOffset
);

Parameters
iTXNObject

The text object that identifies the document in which you want to replace data.

iFileRefNum

The file reference obtained when you opened the file.

iFileType

The file type of the file from which you are getting data. MLTE supports 'RTF ' as well as the file types specified by the constants described in Supported File Types.

iFileLength

A value that specifies how much data should be read. This parameter is ignored if the file type is the custom file format (represented by the constant kTXNTextensionFile) that MLTE supports. This parameter is useful when your application uses MLTE to read data that is embedded in your application’s private file. If you want MLTE to deal with the entire file, set the iFileLength parameter to a value of kTXNEndOffset.

iStartOffset

The starting position at which to insert the file into the document. You can use the TXNGetSelection function to get the absolute offsets of the current selection. If you want to replace the entire document, then set the iStartOffset parameter to 0.

iEndOffset

The ending position of the range being replaced by the file. You can use the TXNGetSelection function to get the absolute offsets of the current selection.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

Your application must open the data fork of the file and set the iStartOffset parameter to the appropriate value before you call the TXNSetDataFromFile function. If you want to embed MLTE data within private data or other MLTE data, you must set the file position to the appropriate position.

Offsets in MLTE are always character offsets.

Availability
Declared In
MacTextEditor.h

TXNSetRectBounds

Set the view rectangle and/or the destination rectangle. (Deprecated in Mac OS X v10.3. Use TXNSetHIRectBounds instead.)

Not recommended.

void TXNSetRectBounds (
   TXNObject iTXNObject,
   const Rect *iViewRect,
   const TXNLongRect *iDestinationRect,
   Boolean iUpdate
);

Parameters
iTXNObject

The text object for the current text area.

iViewRect

A pointer to a Rect data structure that contains the new coordinates for the view rectangle. If you do not want to change the view rectangle pass NULL.

iDestinationRect

A pointer to a TXNLongRect data structure that contains the new coordinates for the destination rectangle. If you do not want to change the destination rectangle pass NULL.

iUpdate

Pass true if you want the text and location of the scroll bars recalculated and redrawn; otherwise pass false.

Discussion

You can specify coordinates for one or both rectangles. The view rectangle controls the text you see. The destination rectangle controls how text is laid out. Scroll bars are drawn inside the view rectangle.

If you set the iViewRect parameter to a location not currently represented by the scroll bar and you pass NULL for the iDestinationRect parameter, it becomes impossible to scroll to the left bounds of the destination rectangle. If you want to position the view rectangle inside the destination rectangle, you should supply a custom scrolling callback. See TXNScrollInfoProcPtr.

Availability
Declared In
MacTextEditor.h

TXNTerminateTextension

Closes the MLTE library. (Deprecated in Mac OS X v10.3. This function is no longer needed.)

Not recommended.

void TXNTerminateTextension (
   void
);

Availability
Declared In
MacTextEditor.h

Deprecated in Mac OS X v10.4

DisposeTXNActionKeyMapperUPP

Disposes of the universal procedure pointer (UPP) to your action key mapping callback function. (Deprecated in Mac OS X v10.4. Use TXNActionNameMapperProcPtr instead.)

Not recommended.

void DisposeTXNActionKeyMapperUPP (
   TXNActionKeyMapperUPP userUPP
);

Discussion

See the callback TXNActionKeyMapperProcPtr for more information.

Availability
Declared In
MacTextEditor.h

InvokeTXNActionKeyMapperUPP

Calls your action key mapping callback function. (Deprecated in Mac OS X v10.4. Use TXNActionNameMapperProcPtr instead.)

Not recommended.

CFStringRef InvokeTXNActionKeyMapperUPP (
   TXNActionKey actionKey,
   UInt32 commandID,
   TXNActionKeyMapperUPP userUPP
);

Return Value

See the Base Services documentation for a description of the CFStringRef data type.

Discussion

See the callback TXNActionKeyMapperProcPtr for more information.

Availability
Declared In
MacTextEditor.h

NewTXNActionKeyMapperUPP

Creates a new universal procedure pointer (UPP) to a callback function that uses your criteria for mapping actions. (Deprecated in Mac OS X v10.4. Use TXNActionNameMapperProcPtr instead.)

Not recommended.

TXNActionKeyMapperUPP NewTXNActionKeyMapperUPP (
   TXNActionKeyMapperProcPtr userRoutine
);

Return Value

A universal procedure pointer.

Discussion

See the callback TXNActionKeyMapperProcPtr for more information.

Availability
Declared In
MacTextEditor.h

TXNCanRedo

Returns whether the most recently undone action is redoable and indicates the type of action that can be redone. (Deprecated in Mac OS X v10.4. Use TXNCanRedoAction instead.)

Not recommended.

Boolean TXNCanRedo (
   TXNObject iTXNObject,
   TXNActionKey *oTXNActionKey
);

Parameters
iTXNObject

The text object for the document you want to examine.

oTXNActionKey

A pointer to a value of type TXNActionKey. On return, this value specifies the action that can be redone. See Action Constants for a description of possible values. You can use this information to customize the Redo menu item for the specific action to be redone. For example, if the value obtained by TXNCanRedo is kTXNTypingAction, you can map that value to a string that reads “Redo Typing” on a system localized for U.S. English. MLTE does not perform the mapping your program is responsible for mapping the key to the appropriate localized string you want displayed to the user. Pass NULL if you do not want to obtain this information.

Return Value

A Boolean value. If true, the last command is redoable; otherwise the last command cannot be redone.

Discussion

You can call the TXNCanRedo function to determine whether the Redo item in the Edit menu should be enabled.

Availability
Declared In
MacTextEditor.h

TXNCanUndo

Returns whether the most recent action is undoable and provides a value that indicates the type of action than can be undone. (Deprecated in Mac OS X v10.4. Use TXNCanUndoAction instead.)

Not recommended.

Boolean TXNCanUndo (
   TXNObject iTXNObject,
   TXNActionKey *oTXNActionKey
);

Parameters
iTXNObject

The text object for the document you want to examine.

oTXNActionKey

A pointer to a value of type TXNActionKey. On return, this value identifies the action that can be undone. See Action Constants for a description of possible values. You can use this information to customize the Undo menu item for the specific action to be undone. For example, if the value obtained by TXNCanUndo is kTXNTypingAction, you can map that value to a string that reads “Undo Typing” on a system localized for U.S. English. MLTE does not perform such a mapping your program is responsible for mapping the key to the appropriate localized string you want displayed to the user. Pass NULL if you do not wish to obtain this information.

Return Value

A Boolean value. If true, the last command is undoable; otherwise the last command cannot be undone.

Discussion

You can call TXNCanUndo to determine whether the Undo item in the Edit menu should be enabled.

Availability
Declared In
MacTextEditor.h

TXNClearActionChangeCount

Resets the specified action counters to zero. (Deprecated in Mac OS X v10.4. Use TXNClearCountForActionType instead.)

Not recommended.

OSStatus TXNClearActionChangeCount (
   TXNObject iTXNObject,
   TXNCountOptions iOptions
);

Parameters
iTXNObject

The text object whose action counter you want to reset.

iOptions

The TXNCountOptions to use when resetting the count. See Action Count Masks for information on the options you can supply.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

You can use this function to clear the action counters as needed for your application.

Availability
Declared In
MacTextEditor.h

TXNGetActionChangeCount

Retrieves the number of times the specified action or actions have occurred since the count was initialized or cleared. (Deprecated in Mac OS X v10.4. Use TXNGetCountForActionType instead.)

Not recommended.

OSStatus TXNGetActionChangeCount (
   TXNObject iTXNObject,
   TXNCountOptions iOptions,
   ItemCount *oCount
);

Parameters
iTXNObject

The text object whose action count you want to retrieve.

iOptions

The TXNCountOptions to use when retrieving the count. See Action Count Masks for information on the options you can supply.

oCount

On return, a pointer to the action count.

Return Value

A result code. See “MLTE Result Codes.”

Availability
Declared In
MacTextEditor.h

TXNGetFontDefaults

Makes a copy of the font descriptions for a given text object. (Deprecated in Mac OS X v10.4.)

OSStatus TXNGetFontDefaults (
   TXNObject iTXNObject,
   ItemCount *ioCount,
   TXNMacOSPreferredFontDescription oFontDefaults[]
);

Parameters
iTXNObject

The text object for the document whose default font settings you want to copy.

ioCount

A pointer to a value of type ItemCount. You need to call the TXNGetFontDefaults function twice (see Discussion). The first time you call the function, pass NULL. On return, the ioCount parameter specifies the number of font descriptions associated with the text object. The second time you call TXNGetFontDefaults, on return the ioCount parameter points to the number of font descriptions in the iFontDefaults array.

iFontDefaults

An array of TXNMacOSPreferredFontDescription structures to be filled. You need to call the TXNGetFontDefaults function twice (see Discussion). The first time you call the function pass NULL. The second time you call TXNGetFontDefaults, you can initialize the iFontDefaults array to have the number of elements specified by the ioCount parameter. Then on return, the iFontDefaults parameter contains the font descriptions for the text object.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

You need to call this function twice: once to get the number of font default descriptions (returned in the ioCount parameter), and the second time to get the font default data.

Availability
Declared In
MacTextEditor.h

TXNSave

Saves the contents of the document as the file type you specify. (Deprecated in Mac OS X v10.4. Use TXNWriteRangeToCFURL instead.)

Not recommended.

OSStatus TXNSave (
   TXNObject iTXNObject,
   TXNFileType iType,
   OSType iResType,
   TXNPermanentTextEncodingType iPermanentEncoding,
   const FSSpec *iFileSpecification,
   SInt16 iDataReference,
   SInt16 iResourceReference
);

Parameters
iTXNObject

The text object for the active document.

iType

The file type to which the text object should be saved. The type must be kTXNTextensionFile, kTXNTextFile, or kTXNUnicodeTextData. See Supported File Types for more information on file type constants.

iResType

The type of resource that should be used to save the style information if the file is being saved as plain text. This parameter is ignored for file types that are not plain text.

iPermanentEncoding

The encoding in which to save the document. If the internal encoding used by MLTE does not match the requested encoding type, the text is translated by the Conversion Manager.

iFileSpecification

A pointer to a variable that specifies the location of the file. This parameter is retained and used in calls to the TXNRevert function. It is not retained once the text object is deleted or disposed of.

iDataReference

The data fork reference number of the open file.

iResourceReference

The resource fork reference number of the open file. This parameter is ignored if the file type is not kTXNTextFile. You can save text without style information by passing -1 for this parameter.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

You must first open the file to which you want to save the document. If you are saving the file as plain text and the application has specified a resource type in which to save style attributes, then you must also open the file’s resource fork.

MLTE does not move the marker before writing the file. You must make sure the file marker of the opened file is at the position where you want data to be written. Typically, this is position 0, but you can specify any valid file position. This behavior lets you write private data, followed by data that is written by MLTE, which can subsequently be followed by more private data or even another MLTE file.

Availability
Declared In
MacTextEditor.h

TXNSetDataFromCFURLRef

Replaces a range of data with the contents of a file. (Deprecated in Mac OS X v10.4. Use TXNReadFromCFURL instead.)

Not recommended.

OSStatus TXNSetDataFromCFURLRef (
   TXNObject iTXNObject,
   CFURLRef iURL,
   TXNOffset iStartOffset,
   TXNOffset iEndOffset
);

Parameters
iTXNObject

The text object that identifies the document in which you want to replace data. You can either call the function TXNCreateObject to allocate a text object or you can call the function HITextViewGetTXNObject to obtain the text object associated with an HITextView.

iURL

A reference to the Core Foundation URL that specifies the file which contains the data you want to add to the object.

iStartOffset

The starting position at which to insert the file into the document. If you want to replace the current selection, set the iStartOffset parameter to kTXNUseCurrentSelection. If you want to replace the entire document, set the iStartOffset parameter to 0. Offsets in MLTE are always character offsets.

iEndOffset

The ending position of the range being replaced by the file. You can use the TXNGetSelection function to get the absolute offsets of the current selection. Offsets in MLTE are always character offsets.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

Your application must open the file and set the iStartOffset parameter to the appropriate value before you call the TXNSetDataFromCFURLRef function. If you want to embed MLTE data within private data or other MLTE data, you must set the file position to the appropriate position.

In the (now deprecated) function TXNNewObject your could pass a file reference and MLTE supported functionality to revert back to the original file reference. When you call the function TXNSetDataFromCFURLRef, MLTE saves the CFURLRef. If you change the contents of the text object and then call the function TXNRevert, the document reverts to the contents specified by the saved CFURLRef.

Availability
Declared In
MacTextEditor.h

TXNSetFontDefaults

Specifies the font descriptions for each script used in a text object. (Deprecated in Mac OS X v10.4.)

OSStatus TXNSetFontDefaults (
   TXNObject iTXNObject,
   ItemCount iCount,
   const TXNMacOSPreferredFontDescription iFontDefaults[]
);

Parameters
iTXNObject

The text object for the document whose fonts you want to specify.

iCount

The number of font descriptions in the iFontDefaults array.

iFontDefaults

An array of TXNMacOSPreferredFontDescription structures that contain the font description you want to use for each script.

Return Value

A result code. See “MLTE Result Codes.”

Availability
Declared In
MacTextEditor.h

Deprecated in Mac OS X v10.5

TXNDisposeFontMenuObject

Disposes of a Font menu object. (Deprecated in Mac OS X v10.5.)

OSStatus TXNDisposeFontMenuObject (
   TXNFontMenuObject iTXNFontMenuObject
);

Parameters
iTXNFontMenuObject

The Font menu object which you want to dispose of.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

The TXNDisposeFontMenuObject function releases the specified Font menu object from memory. Note that TXNDisposeFontMenuObject does not dispose of the main Font menu handle that is associated with the Font menu object. You are responsible for disposing of the Font menu handle after calling TXNDisposeFontMenuObject. However, TXNDisposeFontMenuObject does dispose of any submenus that MLTE creates to support Apple Type Services for Unicode Imaging (ATSUI) fonts.

A good time to call the TXNDisposeFontMenuObject function is when your application quits (that is usually when your application no longer needs the Font menu). You can dispose of the Font menu object as part of a “terminate” function you create to do cleanup and termination tasks.

Availability
Declared In
MacTextEditor.h

TXNDoFontMenuSelection

Changes the font of the current selection. (Deprecated in Mac OS X v10.5.)

OSStatus TXNDoFontMenuSelection (
   TXNObject iTXNObject,
   TXNFontMenuObject iTXNFontMenuObject,
   SInt16 iMenuID,
   SInt16 iMenuItem
);

Parameters
iTXNObject

The text object that contains the current selection.

iTXNFontMenuObject

The Font menu object that identifies the current Font menu.

menuID

The menu ID of the selected menu. You should supply the high 16 bits of the long word obtained from the Menu Manager function MenuSelect. You must pass the menu ID because the Font menu may have hierarchical submenus.

menuItem

A value that identifies the selected menu item. You should supply the low 16 bits of the long word obtained from the Menu Manager function MenuSelect.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

When you receive a mouse-down event in a menu used in your application, you typically call the Menu Manager function MenuSelect to determine which menu and menu item the user has chosen. After calling the MenuSelect function, you should check whether the mouse-down event occurred in a menu specific to your application, other than the standard menus such as File, Edit, and Font. If the mouse-down event did not occur in a menu specific to your application, you should pass the IDs of the menu and menu item to the TXNDoFontMenuSelection function. If the value you supply in the iMenuID parameter identifies the Font menu or one of its submenus, TXNDoFontMenuSelection changes the font of the currently selected text to the font that the user selects.

Availability
Declared In
MacTextEditor.h

TXNGetFontMenuHandle

Gets the Font menu handle that belongs to a Font menu object. (Deprecated in Mac OS X v10.5.)

OSStatus TXNGetFontMenuHandle (
   TXNFontMenuObject iTXNFontMenuObject,
   MenuRef *oFontMenuHandle
);

Parameters
iTXNFontMenuObject

A Font menu object.

fontMenuHandle

A pointer to a menu handle. On return, a pointer to the Font menu created when the Font menu object was created. MLTE makes a copy of the menu handle. Your application should not dispose of the menu handle until it disposes of the Font menu object by calling the TXNDisposeFontMenuObject.

Return Value

A result code. See “MLTE Result Codes.”

Availability
Declared In
MacTextEditor.h

TXNNewFontMenuObject

Creates a new Font menu object. (Deprecated in Mac OS X v10.5.)

OSStatus TXNNewFontMenuObject (
   MenuRef iFontMenuHandle,
   SInt16 iMenuID,
   SInt16 iStartHierMenuID,
   TXNFontMenuObject *oTXNFontMenuObject
);

Parameters
iFontMenuHandle

A value of type MenuRef obtained by calling the Menu Manager functions CreateNewMenu, NewMenu, CreateMenuFromNib, or GetMenu. Before calling TXNNewFontMenuObject, initialize the menuData field of the handle to specify the menu title, in Pascal string format. You must make sure the string is localized appropriately.

iMenuID

The menu ID of the Font menu.

iStartHierMenuID

The first MenuID to use if any hierarchical menus need to be created. This function calls SetMenuItemHierarchicalID to create hierarchical menus, so the value of this parameter must follow the rules for that function. On systems less than Mac OS 8.5, the submenuID must be less than 255. For systems after Mac OS 8.5, the range can be as large as large 32767. However, it is important to remember that TXNNewFontMenuObject only uses iStartHierMenuID as a starting ID when adding hierarchical menus. Therefore provide plenty of room to increment this value. For example, on a system less than Mac OS 8.5, start at 175. On systems after than Mac OS 8.5, do not use a value more than 32000.

oTXNFontMenuObject

A pointer to a structure of type TXNFontMenuObject. On return, a new Font menu object.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

A good time to call the TXNNewFontMenuObject function is when you are preparing to display your menu bar. This function fills the Font menu with font names. Later, you can pass the Font menu object along with a text object to the TXNDoFontMenuSelection function which handles all aspects of user interaction with the Font menu.

Availability
Declared In
MacTextEditor.h

TXNPrepareFontMenu

Prepares a Font menu for display. (Deprecated in Mac OS X v10.5.)

OSStatus TXNPrepareFontMenu (
   TXNObject iTXNObject,
   TXNFontMenuObject iTXNFontMenuObject
);

Parameters
iTXNObject

The text object that identifies the document with the Font menu you want to prepare. Pass NULL to display an inactive menu (dimmed).

iTXNFontMenuObject

A Font menu object.

Return Value

A result code. See “MLTE Result Codes.”

Discussion

You should call the TXNPrepareFontMenu function just before your application opens the Font menu for your user. If the text object’s current selection is a single font, MLTE places a check mark next to the menu item for that font.

Availability
Declared In
MacTextEditor.h

< Previous PageNext Page > Hide TOC

© 2000, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-19)

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.