Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 7 - Translation Manager / Writing a Translation Extension

Translating Files

If your translation extension identifies a document as one that it can translate and the user chooses to use your translation extension, your extension is called with the kTranslateTranslateFile request code to translate the document. The TranslateEntry extension (shown in Listing 7-5 on page 7-25) dispatches to its DoTranslateFile function when it receives this request code. Listing 7-8 shows the skeleton of a DoTranslateFile function.

Listing 7-8 Translating a document

FUNCTION DoTranslateFile (self: ComponentInstance; 
                           refNum: TranslationRefNum; 
                           srcDoc: FSSpec; 
                           srcType: FileType; 
                           srcTypeHint: LongInt; 
                           dstDoc: FSSpec; 
                           dstType: FileType; 
                           dstTypeHint: LongInt): ComponentResult;
VAR
      myAdvert:      Handle;
      myResFile:     Integer;
      myResult:      OSErr;
CONST
   rProgressAdvertismentResID       = 150;
BEGIN
   myResFile := OpenComponentResFile(Component(self));
   IF myResFile <> -1 THEN
   BEGIN
      {get advertisement}
      myAdvert := Get1Resource('PICT', rProgressAdvertismentResID);
      DetachResource(myAdvert);
      {display progress dialog box and show advertisement}
      myResult := SetTranslationAdvertisement(refNum, PicHandle(myAdvert));
      myResult := CloseComponentResFile(myResFile);
   END;
   {now call your routine to translate the file}
   DoTranslateFile := MyDoTranslation
                                 (refNum, srcDoc, srcType, dstDoc, dstType);
   DisposeHandle(myAdvert);
END;

By the time the DoTranslateFile routine is called, the file specified by the dstDoc parameter already exists. The destination file has a data fork; it also has a resource fork if the flags field in the appropriate destination file type specification (in your extension's file translation list) has the taDstDocNeedsResourceFork bit set. Your extension should open the destination file and fill it with the translated data.

In Listing 7-8, the DoTranslateFile function calls the SetTranslationAdvertisement function to install an advertisement in the progress dialog box. The routine that does the actual data translation (MyDoTranslation) should periodically call UpdateTranslationProgress to update the progress bar in the dialog box.

If an error occurs during the translation, you should make sure to close any files you might have opened (for instance, the destination file's data fork and resource fork), do any other necessary cleaning up, and then return a nonzero result code through your component selector dispatcher. When Macintosh Easy Open receives a nonzero result code, it automatically deletes the destination file.