Inside Macintosh: More Macintosh Toolbox /

Chapter 7 - Translation Manager

Writing a Translation Extension

A translation extension is a component that works with Macintosh Easy Open to provide data recognition and translation capabilities. Because a translation extension is a component, it must be able to respond to the required request codes sent by the Component Manager. In addition, a translation extension can

• communicate its translation capability to Macintosh Easy Open
• identify the formats of specific documents and scraps
• translate documents and scraps

Translation extensions can identify and translate files, scraps, or both. You specify whether a translation extension handles files or scraps by setting bits in the component flags field in the component resource (see "Creating a Translation Extension" beginning on page 7-19 for details).

IMPORTANT

The information in this section describes how to write translation extensions. If you simply want to make your application compatible with Macintosh Easy Open, see "Using the Translation Manager" beginning on page 7-10. If your application needs to determine dynamically which file types it can open, see "Writing Application Translation Extensions" beginning on page 7-35.

Macintosh Easy Open and the Translation Manager specify file and scrap formats using the FileType and ScrapType data types:

TYPE
   FileType                = OSType;   {file types}
   ScrapType               = ResType;  {scrap types}

The ScrapType data type describes the format of data in memory. In general, the scrap types used by Macintosh Easy Open are identical to scrap types used by the Scrap Manager. There is, however, one notable exception. Macintosh Easy Open defines a new scrap type, 'stxt', to describe styled text. A scrap having format 'stxt' is formed by appending the text (as contained in a scrap of format 'TEXT') to the style information (as contained in a scrap of format 'styl'). This is necessary to have a single scrap to pass to your scrap translation extension.

The FileType data type describes the format of a file. Often, but not always, the format of a file's data can be identified by inspecting the file's type, as maintained in the hierarchical file system catalog file (hereafter called the file's catalog type). For purposes of translation, however, it is sometimes necessary to use a more specific identification. For example, some developer might revise an application but retain the existing file type for documents the application creates. This could cause problems for translation extensions, which might be able to translate a specific version of the application's data format but not later ones. Similarly, some applications that create files on Macintosh computers (such as electronic mail programs or disk-mounting utilities) often use standard file types (such as 'TEXT' or 'BINA') as the default new file type. Once again, your translation extension needs more information about the actual format of the data in the file before it can translate it to some other format.

To avoid problems with using a file's catalog type as the only indication of the file's data format, Macintosh Easy Open and the Translation Manager allow you to define a translation file type. As just indicated, the catalog file type is often sufficient as the translation file type. However, Macintosh Easy Open always gives your translation extension the opportunity to inspect a particular file to see whether its catalog file type is in fact sufficient for translation purposes. If your extension can identify a more specific format, it should return that information to Macintosh Easy Open. (Ideally, application developers should assign catalog file types that can be used as translation file types.)

The rest of this section describes how to create a file translation extension. You create a scrap translation extension in like fashion, substituting the scrap data types for the corresponding file data types.

---

Subtopics

Creating a Translation Extension

Dispatching to Translation Extension-Defined Routines

Creating a Translation List

Identifying Files

Translating Files

Writing Application Translation Extensions