Technical Note TB01

Bundles

CONTENTS Introduction How to Create a Bundle How the Finder Uses Bundles Problems That May Arise References Downloadables

This Technote describes what a bundle is and how to create one. [Nov 01 1988]

Introduction

A bundle is a collection of resources. Bundles can be used for a number of different purposes, and are currently used by the Finder ito tie an icon to a file type, allowing your application or data file to have its own icon.

Back to top

How to Create a Bundle

A bundle is a collection of resources. To make a bundle for finder icons, we need to set up four types of resources: an ICN#, an FREF, a creator STR and a BNDL.

The ICN# resource type is an icon list. Each ICN# resource contains one or more icons, on after another. For Finder bundle icons, there are two icons in each ICN#: one for the icon itself and one for the mask. In our sample bundle, we have two file types, each with its own icon. To define the icons for these files we would enter this into our Rez input file:

    resource 'ICN#' (732) { /* first icon: the ID number can be anything */
       {                    /* first, the icon */
          $"FF FF FF FF"    /* each line is 4 bytes (32 bits) */
          $"F0 09 CD DD"    /* 32 lines total for icon */
          ...
          $"FF FF FF FF"    /* 32nd line of icon */
          ,                 /* now, the mask */
          $"FF FF FF FF"    /* 32 lines total for mask */
          $"FF FF FF FF"
          ...
          $"FF FF FF FF"    /* 32nd line of mask*/
       }
    };
    resource 'ICN#' (733) { /* second icon */
       {
          $"FF FF FF FF"
          ...
          ,
          $"FF FF FF FF"
          ...
       }

Now that we've defined our icons we can set up the FREFs. An FREF is a file type reference; you need one for each file type that has an icon. It ties a file type to a local icon resource ID. This will be mapped by the BNDL onto an actual resource ID number of an ICN# resource. Our FREFs will look like this:

    resource 'FREF' (816) { /* file type reference for application icon */
       {
          'APPL', 605, /* the type is APPL(ication), the local ID is 605 */
          ""           /* this string should be empty (it is unused) */
       }
    };

    resource 'FREF' (817) { /* file type reference for a document icon */
       {
          'TEXT', 612, /* the type is TEXT, the local ID is 612 */
          ""           /* this string should be empty (it is unused) */
       }

The reason that you specify the local ID, rather than the actual resource ID of the ICN# is that the Finder will copy all of the bundle resources into the Desktop file and renumber them to avoid conflicts. This means that the actual IDs will change, but the local IDs will remain the same.

Every application (or other file with a bundle) has a unique four-character signature. The Finder uses this to identify an application. The creator resource that contains a single string, and should be defined like this:

    type 'MINE' as 'STR '; /* MINE is the signature */
    resource 'MINE' (0) { /* the creator resource ID must be 0 */
       "MyProgram 1.0 Copyright 1988"

Now for the BNDL resource. The BNDL resource associates local resource IDs with actual resource IDs, and also tells the Finder what file types exist, and which ICN#s and FREFs are part of the bundle. The resource looks like this:

    resource 'BNDL' (128) { /* the bundle resource ID should be 0 */
       'MINE', /* signature of this application */
       0, /* the creator resource ID (this must be 0) */
       {
          'ICN#', /* local resource ID mapping for icons */
          {
             605, 732, /* ICN# local ID 605 maps to 732 */
             612, 733  /* ICN# local ID 612 maps to 733 */
          },
          'FREF', /* local resource ID mapping for file type references */
          {
             523, 816, /* FREF local ID 523 maps to 816 */
             555, 817  /* FREF local ID 555 maps to 817 */

When you are in the Finder, your application, type APPL (FREF 816), will be displayed with icon local ID 605 (from the FREF resource). This is ICN# 732. Files of type TEXT (FREF 817) created by your application will be displayed with icon local ID 612 (from the FREF resource). This is ICN# 733.

Back to top

How the Finder Uses Bundles

If a file has the bundle bit set, but the bundle isn't in the Desktop file, the Finder looks for a BNDL resource. If the BNDL resource matches the signature of theapplication, the Finder then makes a copy of the bundle and puts it in the Desktop file. The file is then displayed with its associated icon.

If a file has lost its icon (it's on a disk without the file containing bundle and the Desktop file doesn't contain the bundle), then it will be displayed with the default document icon until the Finder encounters a copy of the file that contains the right bundle. The Finder then makes a copy of the application's bundle (renumbering resources if necessary) and places it in the Desktop file of that disk.

Back to top

Problems That May Arise

There are times when you have set up these resource types properly but the icon is either the wrong one or it has defaulted to the standard application or data file icon. There are a number of possible reasons for this.

If you are using the Macintosh-based RMaker, the first thing to check is whether there are any extraneous spaces in your resource compiler input file. The Macintosh-based RMaker is very picky about extra spaces.

If your icon is defaulting to the standard icon, check to see that the bundle bit is set. If the bundle bit isn't set , the Finder doesn't know to place the bundle in the Desktop file. If it isn't in the Desktop file, the Finder displays the file with a default icon.

If you changed the icon and remade the resource file, but the file still has the same old icon when displayed in the Finder. The old icon is still in the Desktop file. The Finder doesn't know that you've changed it, so it uses what it has. To get it to use the new icon you need to rebuild the Desktop file. To force the Finder to rebuild the Desktop file, you can hold down the Option and Command keys on startup or on insertion of the disk in question if it isn't the boot disk. The Finder will ask whether or not you want to rebuild the desktop (meaning the Desktop file).

Have a bundle of fun!

Back to top

References

The Finder Interface

Back to top

Downloadables