Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 7 - Translation Manager / Writing a Translation Extension

Creating a Translation Extension

A translation extension is a component. It contains a number of resources, including icons, strings, pictures, and the standard component resource (a resource of type 'thng') required of any Component Manager component. In addition, a translation extension must contain code to handle required request codes passed to it by the Component Manager as well as translation-specific request codes.

For complete details on components and their structure, see the chapter "Component Manager" in this book. This section provides specific information about translation extensions.

The component resource binds together all the relevant resources contained in a component; its structure is defined by the ComponentResource data type.

TYPE ComponentResource =
   RECORD
      cd:               ComponentDescription;
      component:        ResourceSpec;
      componentName:    ResourceSpec;
      componentInfo:    ResourceSpec;
      componentIcon:    ResourceSpec;
   END;

The component field specifies the resource type and resource ID of the component's executable code. By convention, for translation extensions this resource should be of type 'xlat'. (You can, however, specify some other resource type if you wish.) The resource ID can be any integer greater than or equal to 128. See the following section for further information about this code resource. The ResourceSpec data type has this structure:

TYPE ResourceSpec =
   RECORD
      resourceType:     ResType;
      resourceID:       Integer;
   END;

The componentName field specifies the resource type and resource ID of the resource that contains the component's name. Usually the name is contained in a resource of type 'STR '. Macintosh Easy Open uses the component's name in several of the dialog boxes it displays. (For example, in Figure 7-3 on page 7-6, one of the translation extensions has the component name "Hang Ten.") This string should be as short as possible.

The componentInfo field specifies the resource type and resource ID of the resource that contains a description of the component. Usually the description is contained in a resource of type 'STR '. This information is not currently used by Macintosh Easy Open, but some development tools may use it.

The componentIcon field specifies the resource type and resource ID of the resource that contains an icon for the component. Usually the icon is contained in a resource of type 'ICON'. This icon is not currently used by Macintosh Easy Open, but some development tools may use it.

Note

The icon displayed in Figure 7-4 on page 7-7 is part of the translation extension's advertisement; it is not supplied by Macintosh Easy Open itself.

The cd field of the ComponentResource structure is a component description record, which contains additional information about the component. A component description record is defined by the ComponentDescription data structure.

TYPE ComponentDescription =
   RECORD
      componentType:          LongInt;
      componentSubType:       LongInt;
      componentManufacturer:  LongInt;
      componentFlags:         LongInt;
      componentFlagsMask:     LongInt;
   END;

For translation extensions, the componentType field must be set to 'xlat'. In addition, the componentSubType field must be set to 0 (because there are currently no subtypes of translation extensions). The componentManufacturer field identifies the supplier of the component. You should register your component with Apple's Component Registry Group to receive a unique manufacturer code; this code typically corresponds to the signature of your translation extension.

The componentFlags field of the component description for a translation extension contains bit flags that encode information about the extension. Currently, you can use this field to specify whether the extension supports file translation routines or scrap translation routines, or both. (See the chapter "Component Manager" in this book for information about the standard flags that you can also specify in the componentFlags field.)

CONST
   kSupportsFileTranslation   = 1;  {file translation extension}
   kSupportsScrapTranslation  = 2;  {scrap translation extension}

You should set the componentFlagsMask field to 0.

IMPORTANT

For compatibility with early versions of the Component Manager, a 'thng' resource should be locked. You can set the other resource attributes in any way you wish.

In addition to the component resource, a translation extension must contain the string and icon resources specified in the component resource (for example, the resource that contains the extension's name). You might also want to include several other resources in the translation extension, including the standard 'BNDL', 'FREF', and 'ICN#' resources used by the Finder and a 'PICT' resource that contains an advertisement or banner to be displayed in the translation progress dialog box. You should also include a 'kind' resource listing kind strings for all the file types your extension can translate from or to; this allows the Finder to display correct kind strings once your extension is installed. Listing 7-4 shows, in Rez input format, the component resource and associated resources of a sample translation extension.

Listing 7-4 Sample resources for a translation extension

/*a component resource*/
resource 'thng' (128, locked) {
   'xlat',                    /*all translation extensions have this type*/
   0,                         /*subtype is unused*/
   'MYCO',                    /*creator signature of extension*/
   kSupportsFileTranslation,  /*only file routines are implemented*/
   0,                         /*mask is unused and should be 0*/
   'xlat',128,                /*resource type & ID of translation extension*/
   'STR ',128,                /*resource type and ID of name string*/
   'STR ',129,                /*resource type and ID of information string*/
   'ICON',128                 /*resource type and ID of icon*/
};

/*strings*/
resource 'STR ' (128, purgeable) {
   "Hang Ten"
};

resource 'STR ' (129, purgeable) {
   "Hang Ten Translation Extension"
};

/*an icon*/
resource 'ICON' (128, purgeable) {
   $"7FFF FFF0 8000 0008 8000 0008 8000 0008"
   $"8000 0008 8000 0008 8000 0008 8000 0008"
   $"A000 0008 D000 000A 9000 000D 1000 0009"
   $"1000 0001 1000 0001 1000 0001 1000 0001"
   $"1000 0001 1000 0001 1000 0001 1000 0001"
   $"1000 0009 9000 000D D000 000A A000 0008"
   $"8000 0008 8000 0008 8000 0008 8000 0008"
   $"8000 0008 8000 0008 8000 0008 7FFF FFF0",
};

/*kind strings for document types supported by this extension*/
resource 'kind' (128, purgeable) {
   'SURF',
   verUS,
   {
      ftApplicationName,      "SurfWriter",
      'SURF',                 "SurfWriter document",
   }
};

resource 'kind' (129, purgeable) {
   'SPNT',
   verUS,
   {
      ftApplicationName ,     "SurfPaint",
      'SPNT',                 "SurfPaint document",
   }
};

resource 'kind' (130, purgeable) {
   'ttxt',
   verUS,
   {
      ftApplicationName ,     "TeachText",
      'ttro',                 "TeachText document",
   }
};

Your translation extension is contained in a resource file. The creator of the file can be any type you wish, but the type of the file must be 'thng'. If the extension contains a 'BNDL' resource, then the file's bundle bit must be set.

IMPORTANT

The Finder looks for open and kind resources only in files that have their bundle bit set.