Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 7 - Translation Manager / Translation Extension Reference

Translation Extension Routines / Managing Translation Progress Dialog Boxes

UpdateTranslationProgress

A translation extension can call UpdateTranslationProgress to update the progress dialog box that is displayed during file and scrap translation and to give the user a chance to click the Cancel button.

FUNCTION UpdateTranslationProgress (refNum: TranslationRefNum; 
                                    percentDone: Integer; 
                                    VAR canceled: Boolean) 
                                    : OSErr;

refNum

A translation reference number.

percentDone

An integer in the range 0-100 that indicates the percentage of the translation that has been completed.

canceled

On exit, UpdateTranslationProgress returns TRUE in this parameter if the user clicked the Cancel button in the progress dialog box; otherwise, UpdateTranslationProgress returns FALSE in this parameter.

DESCRIPTION

The UpdateTranslationProgress function updates the translation progress dialog box. You should call this function periodically during a translation to update the progress bar and to give the user an opportunity to cancel the translation. If the user clicks the Cancel button in the dialog box (or types Command-period while the box is displayed), the canceled parameter is set to TRUE; otherwise, it is set to FALSE. When canceled returns TRUE, you should stop the translation, and your application-defined routine DoTranslateFile or DoTranslateScrap should return the result code userCancelledErr.

The percentDone parameter specifies the approximate percentage of time elapsed until completion. You should call UpdateTranslationProgress periodically at reasonable time intervals to allow the user to cancel the translation. When the translation is complete, you should call UpdateTranslationProgress with percentDone set to 100 so that the user can see that the translation is complete.

You should set the refNum parameter to the translation reference number passed to your DoTranslateFile or DoTranslateScrap routine. The Translation Manager uses that number internally.

SPECIAL CONSIDERATIONS

Your translation extension should call UpdateTranslationProgress only in response to the kTranslateTranslateFile or kTranslateTranslateScrap request code (that is, in your DoTranslateFile or DoTranslateScrap routine). Do not call this function in response to any other request code or from any code that isn't a translation extension.

You should already have called SetTranslationAdvertisement before calling UpdateTranslationProgress.

The UpdateTranslationProgress function might cause memory to be moved or purged; you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the UpdateTranslationProgress function are

Trap macro	Selector
_TranslationDispatch	$0001

RESULT CODES

noErr	0	No error
paramErr	-50	Parameter error
memFullErr	-108	Not enough memory