Inside Macintosh: More Macintosh Toolbox /

Chapter 7 - Translation Manager

Using the Translation Manager

Most applications benefit from the services of Macintosh Easy Open automatically if they use the standard Macintosh system software (such as the Standard File Package, the Edition Manager, and the Scrap Manager) to open files or exchange data with other applications. If the appropriate translators are present on a particular computer, Macintosh Easy Open implicitly translates file and scrap formats into those supported by your application. To facilitate this translation, however, you should

• Make your application stationery-aware. When Macintosh Easy Open passes
  your application a translated document, the document's stationery bit is set if your application is stationery-aware. The user should be prompted to save any changes to the translated document under a new name when closing the document.
• Add a resource of type 'open' to your application. This resource indicates what file types your application can open. See "Declaring the File Types Your Application Can Open" on page 7-13 for complete details.
• Add a resource of type 'kind' to your application. This resource allows the Finder to display custom kind strings in its windows. See "Declaring Custom Kind Strings" beginning on page 7-14 for complete details.
• Add a resource of type 'dctb' to your application if it uses custom Standard File Package file-opening dialog boxes. This resource allows the Standard File Package to display the enhanced small color icons in its dialog boxes. See the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials for information on creating resources of type 'dctb'.
• Avoid using a file filter function as the only method of specifying file types when calling the Standard File Package routines StandardGetFile and CustomGetFile (or the original SFGetFile and SFPGetFile). Instead of a file filter function (or in addition to it), you should use the typeList parameter to specify file types to list in the file-opening dialog box. Alternatively, you can pass the special value kUseOpenResourceTypes in the numTypes parameter to have the file types read from your application's 'open' resource. See "Using File-Opening Dialog Boxes" on page 7-15 for more details.
• Use the Scrap Manager properly:
  • Put formats on the scrap in order of fidelity.
  • Get formats from the scrap in the order that your application can best interpret.
  • Don't call GetScrap unless the user has just pasted, because doing so may cause a lengthy translation.
  • Be able to put the popular scrap formats (such as 'styl') on the scrap.
  • Don't rely on the offset parameter returned by GetScrap. It is undefined after implicit translation.

• Avoid using 'TEXT' as a file type of a document your application creates unless the document contains plain ASCII text intended to be viewed by the user as plain text.
• Use file types that accurately indicate the format type of the documents your application creates. When you revise your application and make extensive changes to the file format of a document, previous versions of your application will not be able to read the document. In this case, you should assign a different file type to the new format.

If your application does not use the Standard File Package to allow the user to select files to open, you can use the Translation Manager to make your application compatible with Macintosh Easy Open. See "Translating Files Explicitly" on page 7-17 for details.

---

Subtopics

Checking for the Translation Manager

Declaring the File Types Your Application Can Open

Declaring Custom Kind Strings

Using File-Opening Dialog Boxes

Translating Files Explicitly