Carbon


TXNNewObject

Header: MacTextEditor.h Carbon status: Supported

Creates a new text object of type TXNObject. A text object is an opaque structure that handles text formatting at a document level.

OSStatus TXNNewObject (
    const FSSpec *iFileSpec, 
    WindowRef iWindow, 
    Rect *iFrame, 
    TXNFrameOptions iFrameOptions, 
    TXNFrameType iFrameType, 
    TXNFileType iFileType, 
    TXNPermanentTextEncodingType iPermanentEncoding, 
    TXNObject *oTXNObject, 
    TXNFrameID *oTXNFrameID, 
    TXNObjectRefcon iRefCon
);
Parameter descriptions
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. If you are working with a text object that has embedded data (that is, graphics, sound, or movie data mixed with text data), you should first call TXNNewObject with iFileSpec set to NULL. After the text object is created you can use the TXNSetDataFromFile function to read the file with embedded data into the text object. If you do not pass NULL and the file contains embedded data, the nontext data will not be read properly into the text object.

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 is used as the frame. If you do not want to fill the entire window, you use this to specify the area to fill.

iFrameOptions

A “Frame Option Masks” value of type TXNFrameOptions. This specifies the options you want the frame to support. For example, if you want to support scroll bars and a grow box, you specify frame options like this:

iFrameOptions = kTXNWantHScrollBarMask | kTXNWantVScrollBarMask | kTXNDrawGrowIconMask;

iFrameType

A “Supported Frame Types” value of type TXNFrameType.

iFileType

A “Supported File Types” value of type TXNFileType. You should specify the primary file type. If you use kTextensionTextFile, files are saved in a private format. If you want saved files to be plain text files, you should specify kTXNTextFile, then use the iframeOptions parameter to specify whether the plain text files should be saved with ‘MPSR’ or ‘styl’ resources.

iPermanentEncoding

A “Text Encoding Preferences” value of type TXNPermanentTextEncodingType. The application assumes text is in this encoding.

oTXNObject

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

oTXNFrameID

A pointer to a variable of type TXNFrameID. On return, the unique ID for the frame. However, in MLTE version 1.1 and earlier, this value is always set to 0.

iRefCon

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

function result

A result code.

DISCUSSION

For each document, a new text object is allocated and returned by the TXNNewObject function. 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.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.


© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)