Inside Macintosh: More Macintosh Toolbox /

Chapter 7 - Translation Manager

This chapter describes how you can use the Translation Manager to direct the translation of documents from one format to another. This chapter also gives an overview of Macintosh Easy Open. Macintosh Easy Open uses the Translation Manager to provide extensive data translation services for Macintosh computers. Macintosh Easy Open uses the Translation Manager to provide

• automatic translation of a document from one format to some other format if the application that created it is not available when the user attempts to open the document
• automatic translation of documents drop-launched onto an application
• enhanced Standard File Package file-opening dialog boxes and (when necessary) automatic translation of documents the user selects in those dialog boxes
• batch desktop translation of documents
• automatic translation of data pasted from the Clipboard
• automatic translation of data in editions

Most applications take advantage of these services automatically if they use the system software to open documents. You can, however, enhance your application's interaction with Macintosh Easy Open by adding several resources to your application's resource file. For example, the Finder and Macintosh Easy Open work with the Standard File Package to list in the file opening dialog box all files that your application can open, including those that it can open only after they have been translated from their current format to another format. See "Declaring the File Types Your Application Can Open" on page 7-13 for instructions on adding the required resources to your application. If, however, your application doesn't use the Standard File Package when opening files, you might also need to use the Translation Manager to direct the translation. See "Translating Files Explicitly" on page 7-17 for more information.

This chapter also describes how to write a translation extension. Macintosh Easy Open doesn't do any translating itself; instead, it uses translation extensions to translate documents (data in files) and scraps (data in memory) in the situations listed above. Translation extensions also need to be able to report the kinds of files or scraps they can handle and to identify specific files that need to be translated. You're likely to need to write a translation extension only if you are developing file or scrap translators (also known as convertors or filters).

Macintosh Easy Open and the Translation Manager are not available in all system software versions. You should use the Gestalt function to ensure that the services you need are available before calling them. See "Checking for the Translation Manager" on page 7-12 for details.

To use this chapter, you should already be familiar with the Standard File Package, the Scrap Manager, the Edition Manager, Finder-related resources, and the Component Manager. For information on the Standard File Package, see Inside Macintosh: Files. For information on the Scrap Manager and the Component Manager, see their corresponding chapters in this book. For information on the Edition Manager, see Inside Macintosh: Interapplication Communication. For information on Finder-related resources, see Inside Macintosh: Macintosh Toolbox Essentials.

---

Chapter Contents

About the Translation Manager

Opening Documents From the Finder

Opening Documents Within an Application

Translating Documents on the Desktop

Sharing Data Between Applications

Using the Translation Manager

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

Writing a Translation Extension

Creating a Translation Extension

Dispatching to Translation Extension-Defined Routines

Creating a Translation List

Identifying Files

Translating Files

Writing Application Translation Extensions

Translation Manager Reference

Translation Manager Routines

Getting Translation Information

Translating Files

Resources

The Open Resource

The Kind Resource

Translation Extension Reference

Translation Extension Data Structures

File Type Specifications

File Translation Lists

Scrap Type Specifications

Scrap Translation Lists

Translation Extension Routines

Managing Translation Progress Dialog Boxes

Translation Extension-Defined Routines

File Translation Extension Routines

Scrap Translation Extension Routines

Summary of the Translation Manager

Pascal Summary

Constants

Data Types

Translation Manager Routines

C Summary

Constants

Data Types

Translation Manager Routines

Assembly-Language Summary

Data Structures

Trap Macros

Result Codes

Summary of Translation Extensions

Pascal Summary

Constants

Data Types

Translation Extension Routines

Translation Extension-Defined Routines

C Summary

Constants

Data Types

Translation Extension Routines

Translation Extension-Defined Routines

Assembly-Language Summary

Data Structures

Trap Macros

Result Codes