Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 7 - Translation Manager / Translation Extension Reference

Translation Extension Routines / Managing Translation Progress Dialog Boxes

SetTranslationAdvertisement

A translation extension can call SetTranslationAdvertisement to install an advertisement into the progress dialog box.

FUNCTION SetTranslationAdvertisement (refNum: TranslationRefNum; 
                                       advertisement: PicHandle) 
                                       : OSErr;

refNum

A translation reference number.

advertisement

A handle to a picture to display in the upper portion of the dialog box.

DESCRIPTION

The SetTranslationAdvertisement function installs a translation extension-specific picture into the upper portion of a translation progress dialog box, then displays the dialog box. The advertisement parameter should be a handle to the picture to display. If the value of advertisement is NIL, no advertisement is displayed and the upper portion of the dialog box is removed before the box is displayed to the user.

Your translation extension can read the picture data from its resource fork, but it should detach the resource from the resource fork (by calling DetachResource) and make the handle unpurgeable before calling SetTranslationAdvertisement. Because you'll usually load the picture data into the temporary heap provided for the translation extension, the picture data is automatically disposed of when that heap is destroyed. If your translation extension loads the picture data elsewhere in memory, you are responsible for disposing of it before returning from your DoTranslateFile or DoTranslateScrap routine.

The size of the picture to display can be no larger than 280 by 50 pixels. If the picture you specify is smaller than that, it is automatically centered (both vertically and horizontally) in the available space.

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 SetTranslationAdvertisement 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 must call SetTranslationAdvertisement before you call the UpdateTranslationProgress procedure for the first time.

The SetTranslationAdvertisement 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 SetTranslationAdvertisement function are

Trap macro	Selector
_TranslationDispatch	$0002

RESULT CODES

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

SEE ALSO

See Figure 7-4 on page 7-7 for a sample translation progress dialog box showing an advertisement. See Listing 7-8 on page 7-34 for an example of the use of SetTranslationAdvertisement.