The Multilingual Text Engine (MLTE), which was introduced with Mac OS 9.0 as an alternative for TextEdit, profoundly simplified the task of handling muliti-styled text and, at the same time, provided many new features not provided by TextEdit. The main additional features are as follows:
Documents can be larger than 32KB (the TextEdit limit).
Tabs.
Text justification.
Ability to embed movie, sound, and graphics objects in documents.
Built-in support for:
Scroll bar creation and handling, including live scrolling and proportional scroll boxes.
Undo/redo (32 levels).
Printing.
Drag and drop.
The public clipboard, specifically, copying and pasting:
Plain text.
Plain text with style resources.
Unicode text.
Flattened Unicode style information.
Movies, graphics, and sound.
In-line input.
MLTE uses Apple Type Services for Unicode Imaging (ATSUI) to measure and draw text. ATSUI, which was introduced with Mac OS 8.6, replaced QuickDraw and the Script Manager as the low-level means of imaging and measuring text.
MLTE renders text into a rectangular frame. Applications can specify that lines be arbitrarily wide or auto-wrapped.
Global Layout Settings
The following are the main settings applying to the whole document:
Justification, which can be default, left, right, centre, full, or forced full.
Tab values.
Margins.
Auto-indent on or off.
Text auto-wrap on or off.
Read-only status on or off.
Line direction.
Undoable and Re-doable Actions
The following actions are undoable and re-doable:
Typing.
Cut, paste. and clear.
Change font, and font size, style and colour.
Justification.
Drag and drop move and copy.
Selection Behaviour
Within an MLTE document, a single-click defines an insertion point. (Recall from Chapter 21 that an insertion point is, in effect, a selection containing zero characters.) A double-click selects a word, and a triple-click selects a line.
File Types
MLTE supports saving and opening files of the following types:
A new type introduced with MLTE called Textension ('txtn'). This should be the preferred type for media-rich documents that can contain movies, graphics, and sound.
Text ('TEXT'), with or without style information. Style information may be saved as either 'styl' resources or 'MPSR' resources. If 'styl' resources are used , documents can have text in an unlimited number of styles; however, tabs will not be saved. If 'MPSR' resources are used , only the first style in the document will be saved.
Plain Unicode text ('utxt').
Movie ('MooV'), sound ('sfil' and 'AIFF'), and picture ('PICT').
Working With MLTE
Initialising and Terminating MLTE
TXNInitTextension should be called at program start to initialise the Textension library:
kTXNSystemDefaultEncoding is the encoding preferred by MLTE and the system. This is Unicode if ATSUI is present, as it will be on Mac OS 8.6 and later.)
iDefaultFonts
Number of default fonts designated.
iUsageFlags
Specifies whether movies, sound, and/or graphics should be supported. Relevant constants are:
At program termination, you should call TXNTerminateTextension to close the Textension library and perform other clean-up actions.
Allocating and Deleting a TXNObject
Ordinarily, to create a new document, you create a new window and then pass a reference to that window in a call to TXNNewObject. TXNNewObject creates a new TXNObject, an object which contains private variables and functions required to handle text formatting:
OSStatus TXNNewObject(const FSSpec * iFileSpec, // Can be NULL
WindowRef iWindow,
Rect * iFrame, // Can be NULL
TXNFrameOptions iFrameOptions,
TXNFrameType iFrameType,
TXNFileType iFileType,
TXNPermanentTextEncodingType iPermanentEncoding,
TXNObject * oTXNObject,
TXNFrameID * oTXNFrameID,
TXNObjectRefcon iRefCon);
iFileSpec
Pointer to file system specification structure. The file is read in, and its contents displayed, after the TXNObject is allocated. If NULL is passed in this parameter, the document will be empty at start.
iWindow
Reference to the window to be attached to the TXNObject, and in which the document will be displayed.
iFrame
The area of the window in which the document's contents are to be displayed. Passing NULL in this parameter sets the frame to equate to the window's port rectangle.
iFrameOptions
The options supported by this frame. The principal relevant constants are:
kTXNShowWindowMask Show window before TXNNewObject returns.
kTXNWantHScrollBarMask Include horizontal scroll bar.
kTXNWantVScrollBarMask Include vertical scroll bar.
kTXNNoSelectionMask Do not display
insertion point.
If you specify kTXNTextFile, and want style information to be saved, you can specify whether that information should be saved in a 'styl' resource or an 'MPSR' resource when calling the function TXNSave (see below).
iPermanentEncoding
The encoding the application considers text to be in. Relevant constants are:
kTXNSystemDefaultEncoding Encoding preferred by MLTE and the
system. (This is Unicode if ATSUI is
present.)
KTXNMacOSEncoding Incoming and outgoing text to be in
traditional MacOS encoding.
kTXNUnicodeEncoding Incoming and outgoing text to be in
Unicode, even on systems that do not
have ATSUI.
oTXNObject
On output, a pointer to a TXNObject.
oTXNFrameID
On output, a unique ID for the frame.
iRefCon
Reference constant for use by the application.
If TXNNewObject is called with NULL passed in the iWindow parameter, a window can later be attached to the TXNObject by a call to the function TXNAttachObjectToWindow.
A previously allocated TXNObject and its associated data structures may be deleted by a call to the function TXNDeleteObject.
Setting and Getting Global Layout Settings
As previously stated, certain layout settings (for example, justification, tabs, and margins) apply to the whole TXNObject, that is, the whole document. These layout settings are referred to as control information. You can set control information by calling TXNSetTXNObjectControls:
An array of TXNControlData structures containing the control information being set. The TXNControlData structure, and its associated structures, are as follows:
The only background type available with Version 1.1 of MLTE is a colour. TXNBackgroundData is a union so that it can be expanded in the future to support other background types, such as pictures.
Setting and Getting Type Attributes
You can set type attributes such as text size, style and colour by calling TXNSetTypeAttributes:
The number of elements in the iAttributes array, that is, the number of attributes being set.
iAttributes
An array of TXNTypeAttributes structures specifying the attribute being set and the data, or pointer to the data, that will set the attribute. Values less than or equal to sizeof(UInt32) are passed by value. Values greater than sizeof(UInt32) are passed by pointer. The TXNTypeAttributes structure, and its main associated structure, are as follows:
The offset at which to begin setting the attributes. If the requirement is to apply the attributes to the current selection, pass kTXNUseCurrentSelection in this parameter.
iEndOffset
The offset at which to end setting the attributes. This parameter is ignored if kTXNUseCurrentSelection is passed in the iStartOffset parameter.
When your application detects a mouse-down in the menu bar or a Command-key combination, it typically adjusts its menus, enabling and disabling menu items as appropriate. If your application contains menus which allow the user to set type attributes, it must also prepare those menus for display by checkmarking and un-checkmarking items as appropriate.
Using a Size menu as an example, if the current selection (whether it be an empty or non-empty selection) contains text which is all of a single size, the menu item corresponding to that size, and only that menu item, should be checkmarked before the menu is displayed. However, if the selection contains text in two or more sizes, all menu items should be un-checkmarked. It is thus necessary to examine the selection to determine whether it contains a continuous size run or multiple sizes.
You can examine the current selection to determine whether font size, style, and colour are continuous by calling TXNGetContinuousTypeAttributes:
On output, the relevant bit, or bits, of this parameter can be examined to determine whether the associated attribute, or attributes, is/are continuous. For example, if size is continuous, bit 1 will be set. The relevant constants are:
Number of elements in the ioTypeAttributes array, that is, the number of attributes being examined.
ioTypeAttributes
An array of TXNTypeAttributes structures (see above). On input, the tag field in each structure specifies the attribute to be examined. On output, if the attribute is continuous, the dataValue or dataPtr field of the data field will contain a value, or a pointer to data, which can be used to determine which menu item should be checkmarked.
Functions Relevant to Events
The following functions are relevant to event handling:
Function
Description
TXNClick
Processes clicks in the content region, handling text selection, scrolling, drag and drop, and playing movies and sound.
TXNUpdate
Handles update events, redrawing the contents of the window. Calls BeginUpdate and EndUpdate.
TXNForceUpdate Forces an update event to be generated, thus forcing the contents of the window to be redrawn.
TXNDraw
Similar to TXNUpdate, except that BeginUpdate and EndUpdate are not called. Should be used, in lieu of TXNUpdate, for a window that contains multiple TXNObjects or some graphic element.
TXNActivate
In MLTE, activation is a two-step process. TXNActivate performs the first step, which has to do with activating or deactivating the scroll bars.
When true is passed in the TXNScrollBarState parameter, the scroll bars are activated, even when text input (selection and typing) has been defeated by TXNFocus (see below). When false is passed in the TXNScrollBarState parameter, the scroll bars are deactivated.
TXNFocus
The second step in the activation process has to do with activating text input (selection and typing).
When true is passed in the iBecomingFocused parameter, text input is activated. When false is passed in the iBecomingFocused parameter text input is deactivated.
TXNAdjustCursor
Handles cursor shape-changing. If the cursor is over a text area, it is set to the I-beam shape. If it is over a scrollbar, a movie, graphic, or a sound, or outside the frame, it is set to the arrow shape.
Not relevant in applications using the Carbon event model.
TXNZoomWindow
Handles mousedowns in the zoom box.
GrowWindow
Handles mouse-downs in the size box.
TXNGetSleepTicks
Gets the appropriate sleep time.
Note that, in Carbon applications, calling TXNKeyDown on receipt of key events is not necessary, since MLTE handles the event itself without any assistance on the part of your application. Note also that:
When the Classic event model is used, it is not possible to filter key events because the event is sent to MLTE before WaitNextEvent delivers it to your application.
When the Carbon event model is used, key events are sent through the Carbon event system before they are sent to MLTE. This means that you can filter key events by, for example, installing a handler for the kEventUnicodeForKeyEvent event kind (kEventClassTextInput event class).
Functions Relevant to the File Menu
The following functions are relevant to your application's File menu:
Function
Description
TXNSave
Saves the contents of a document to a file of a specified file type (for example, Textension, text, or Unicode text). The data fork of the file must be open and its file reference number passed in the iDataReference parameter.
For files of type text, if style information is also to be saved, the resource fork of the file must also be open and its file reference number passed in the iResourceReference parameter (The iResourceReference parameter is ignored when the Textension file type is specified.) kTXNMultipleStylesPerTextDocumentResType passed in the iResType parameter causes style information be saved to a 'style' resource. To specify that style information be saved to an 'MPSR' resource, pass kTXNSingleStylePerTextDocumentResType in the iResType parameter.
TXNSave does not move the file mark before writing to a file. This allows you to write private data first (if required), followed by the data written by TXNSave.
TXNRevert
Reverts to the last saved version of the document or, if the document has never been saved, reverts to an empty document.
TXNPageSetup
Displays the Page Setup dialog and reformats the text if settings are changed by the user.
TXNPrint
Displays the Print dialog and prints the document.
TXNGetChangeCount
Returns the number of times the document has been changed since the last save or, for new documents which have not yet been saved, since the document was created. Useful for determining whether the Save and Revert items should be enabled or disabled.
TXNDataSize
Returns the size in bytes of the characters in the document. Useful for determining if the Save As, Page Setup and Print items should be enabled or disabled.
Functions Relevant to the Edit Menu
The following functions are relevant to your application's Edit menu:
Function
Description
TXNCanUndo
Returns true if the last action is undoable, in which case the Undo item should be enabled.
TXNCanRedo
Returns true if the last action is re-doable, in which case the Redo item should be enabled.
TXNUndo
Undoes the last action.
TXNRedo
Re-does the last action.
TXNCut
Cuts the current selection to the MLTE private scrap.
TXNCopy
Copies the current selection to the MLTE private scrap.
TXNPaste
Pastes the MLTE private scrap to the document.
TXNClear
Clears the current selection.
TXNSelectAll
Selects everything in a frame.
TXNIsSelectionEmpty
Returns false if the current selection is not empty, in which case the Cut, Copy, and Clear items should be enabled.
TXNIsScrapPastable
Returns true if the current MLTE scrap is pastable, in which case the Paste item should be enabled.
TXNConvertToPublicScrap
Converts the MLTE private scrap to the public clipboard.
Note that, in Carbon applications, this function should not be called on suspend events. Typically, it should be called immediately after TXNCut and TXNCopy.
TXNDataSize
Returns the size in bytes of the characters in the document. Useful for determining if the Select All item should be enabled or disabled.
Note that, in Carbon applications, there is no need to call TXNConvertFromPublicScrap to convert the public clipboard to the MLTE private scrap. In Carbon applications, MLTE automatically keeps the public scrap and private scrap synchronised.
More on TXNCanUndo and TXNCanRedo
When TXNCanUndo and TXNCanRedo return true, they also return in their oTXNActionKey parameters an action key which can be used by your application to load an indexed string describing the undoable or re-doable action. The Undo and Redo items should be set to this string using SetMenuItemText. The following are the main action key constants:
MLTE contains functions which greatly simplify the task of creating and managing the Font menu.
The TXNNewFontMenuObject function may be used to create a hierarchical Font menu. A reference to the (empty) Font menu, the menu ID, and the starting ID for the sub-menus are passed in the first three parameters, and a pointer to a TXNFontMenuObject is returned in the fourth parameter. The starting ID for the sub-menus must be 160 or higher.
To prepare the Font menu for display when the user clicks in the menu bar, you should simply call TXNPrepareFontMenu, which checkmarks and un-checkmarks items in the Font menu as appropriate.
A call to TXNDoFontMenuSelection, with the TXNFontMenuObject obtained by the call to TXNNewFontMenuObject passed in the second parameter and the menu ID and chosen menu item passed in the third and fourth parameters, sets the chosen font and changes the current selection to that font.
At program termination, you should call TXNDisposeFontMenuObject to dispose of the TXNFontMenuObject and its menu handle.
Setting Data
You can replace a specified range with data by calling TXNSetData: