The Finder needs quick access to some key information about your application, such as which icons to use when displaying your application and its documents. You supply most of this information in the resource fork of your application file. The Finder extracts this information and uses it to maintain its own database of the resources it needs.

The Finder uses certain high-level events known as Apple events to communicate certain instructions and information to your application. Accordingly, this chapter should be read in conjunction with the Chapter 10 - Apple Events

Resources, the Catalog File, and the DeskTop Database

• A signature resource, which enables the Finder to identify and start up your application when a user double clicks documents created by your application.

• A set of resources that describe icons, which visually represent your application and any documents it creates.

• A set of file reference resources, to link icons with the file types they represent, and to allow users to launch your application by dragging the document icons to your application icon.

• A bundle resource, which groups together your application's signature, icon and file reference resources.

• A size resource (see Chapter 2 - Low Level and Operating System Events) which tells the Finder how much memory to allocate for your application when it starts up and whether your application supports various system software features.

• Version resources, which allow users to ascertain the version of your application and, if applicable, the version of your application's superset of files.

• A finder icon help resource, which the Finder uses to display your customised balloon help message for your application, control panel, or system extension icon.

• Contains all icon definitions and their associated file types (see below).

• Lists all the file types that an application can open and all copies or versions of the application listed as the creator (see below) of the file.

• Lists the location of each application on the disk and any comments that the user has added to the information windows for desktop objects.

  The window opened when the user selects an icon and chooses Get Info from the Finder's File menu.

To ensure uniqueness, developers are required to register their application's signature with Apple Computer, Inc, at Macintosh Developer Technical Support.

You must include in your resource file a special resource which has your application's signature as its resource type. By convention, the signature resource has a resource ID of 0. The signature resource is typically defined to be a string resource (that is, a resource of type 'STR ') which specifies the name, version number, and release date of your application.

If you do not provide specific version information through a version resource, the Finder displays the string stored in the signature resource in the information window for that file.

Creating an Application Signature Resource Using Resorcerer

File Creator and File Type

Note that in this and other references to your application receiving requests to open and print documents, the assumption is made that your application supports the receipt and handling of required Apple events (see Chapter 10 - Required Apple Events).

File Type

Apple reserves the use of all signatures and file types whose names contain only lowercase and non-alphabetic characters. Your signature and file type created especially for your application must each contain at least one uppercase character. Like signatures, file types must be registered with Apple.

Your application must have a file type of 'APPL'. The standard file type 'TEXT' should be assigned to files that consist only of text, that is, a stream of characters with return characters at the end of paragraphs. A document of type 'TEXT' can be opened or printed by any application that accepts such file types.

Use of the File Type by the Finder. Another way for a user to open a document created by your application, as well as a document not created by your application but which is of a file type supported by your application, is to select its icon and drag the selected icon to your application's icon. Because the document's file type is stored in the catalog file, and the Finder stores a list of your application's supported file types in the desktop database, the Finder can determine whether it should launch your application. If the document's file type is supported by your application, the Finder calls the Process Manager to launch your application and then sends your application a required Apple event containing the information it needs to open the document.

Use of File Type by Your Application. Your application also relies on file types to determine which files to allow the user to open when your application is running. When your application calls the Standard File Package or Navigation Services to open a file, your application supplies either a list of the file types that your application can open or a filter function for those types. The Open dialog box then displays files of the specified types only.

Creating Icons for the Finder

However, to distinguish your product for the user, you should design your own icons for all the files associated with your application, including:

• The application file itself.

• Standard documents created by your application.

• Stationery pads that users create from your application's documents. (Stationery pads are files the user creates to serve as templates for other documents.)

• Data-sharing editions that user's create from your application's documents. (Editions are special files that contain data to be shared among applications.)

• Other special documents such as read-only, graphics, and query documents, which are either created by your application or provided by you for use by other applications. (Query documents contain commands and data in a format appropriate for a database or other data source.)

The small icons appear in the Application menu, and in the Apple menu if the user places the application or an alias to it in the Apple Menu Items folder.

Creating Icon Family Resources Using Resorcerer

The Finder uses the icon's mask (see Fig 3) to crop the icon's outline into whatever background colour or pattern is on the desktop. The Finder then draws the icon into this shape. It is therefore important that the mask be exactly the same shape as the icon. Because the mask also defines the region that users need to click to select the icon, it is best not to have any holes in the icon and thus in its mask.

Good icon design requires that one graphic element be repeated in all icons created for the application. This allows the user to quickly identify the files associated with your product. Also, colours for colour icons should ideally be chosen from the 34 recommended icon colours in the system palette. (See the Apple Icon Colors items in the IconFamily menu in Resorcerer.)

The 'icns' Resource

The four icon sizes are mini, small, large, and huge, the latter being a new size of 48 by 48 pixels. Four colour depths (1-bit, 4-bit, 8-bit, and 32-bit) and two kind of masks (1-bit and 8-bit) are supported. The deep (8 bit) mask means that masks can have 256 different levels of transparency.

Icon Services checks for an 'icns' resource of the specified ID before it checks for the older resource types ('ics#', 'icl4', 'icm8', etc.) of the same ID. If an 'icns' resource is found, Icon Services obtains all icon data exclusively from that resource.

As of Version 2.2, Resorcerer had no pixel editor for 'icns' resources. However, a command available in the Icon Family editor will take all icons currently being shown and build an 'icns' resource with the same resource ID as those icons. (Choose Build/Update 'icns' from the IconFamily menu.)

Related Resources

Users are able to customise individual icons. By selecting a file and choosing Get Info from the File menu, the user can select the displayed icon and use the Paste command to replace it with a picture from the clipboard. The Finder creates a family of icons (Mac OS 8.1 or earlier) or an 'icns' resource (Mac OS 8.5 or later) based on the user's customised icon, assigns a resource ID number of -16455 to each resource in the icon family, or to the 'icns' resource, stores these resources in the resource fork of the file that the icon represents and sets the hasCustomIcon bit in the file's Finder flags field (see below). Your can use the same procedure to provide customised icons for your document.

Note that, although an application can assign icons to all of its documents by associating their icons with the document's file type in a bundle resource, a customised icon can represent only one specific file, that is, that file which has an 'ICN#' resource or 'icns' resource with an ID of -16455 in its resource fork.

File Reference ('FREF') Resources

You create a 'FREF' resource for your application file itself and you create separate 'FREF' resources for each file type that your application can open.

Structure of the 'FREF' Resource and Creating a 'FREF' Resource Using Resorcerer

Use of 'FREF' Resources by the Finder

If your application supports file types for which it does not provide icons, you can still define 'FREF' resources for them, allowing users to launch your application by dragging these document icons to your application icon. For example, you could create a 'FREF' resource for the document file type 'ttxt', which is used by documents which have SimpleText as their creator. (The Finder uses SimpleText's icon family resources for these documents.) The user can then open these documents in your application by dragging the document icon to your application's icon.

The Bundle ('BNDL') Resource

When the Finder displays your application on the user's desktop, it checks the catalog file to see if your application has a 'BNDL' resource. If it does not, the Finder displays the default icons. If it does, the Finder installs the information from the 'BNDL' resource and all its bundled resources into either the desktop database (hard disk) or the desktop file (floppy disk) and uses this information to display icons for the file types associated with your application.

Structure of the 'BNDL' Resource and Creating a 'BNDL' Resource Using Resorcerer

Note that you also assign local IDs to 'FREF' resources within the 'BNDL' resource. This assignment is, in fact, superfluous because the Finder does not map these local IDs to any other resources. It was implemented for the earliest versions of the system software, and it remains this way today for backward compatibility.

Resource IDs, Local IDs and the Desktop Database

In the desktop database, the Finder renumbers the resource IDs that you have assigned to your resources to avoid conflicts with the resources of other applications. Therefore, the 'BNDL' resource has to rely on these local IDs to map 'ICN#' resources to their 'FREF' resources, that is, the 'BNDL' resource uses the local ID you assign to an 'ICN#' resource to map it to the 'FREF' resource that has specified the same local ID. For example, the 'FREF' resource with resource ID 208 at Fig 4 shows that the file type 'APPL' is assigned a local ID of 0. At Fig 5, you will see that local ID 0 is assigned to the 'ICN#' resource with resource ID 128. This maps the icon defined by this resource to the application file.

Fig 6 illustrates how the 'BNDL' resource uses local IDs to map 'ICN#' resources to 'FREF' resources. This figure illustrates two main concepts:

• The one 'BNDL' resource ties together all the icon resources and 'FREF' resources for your application and all its documents.

• The icon resources and their associated 'FREF' resources are mapped together by local IDs.

In Fig 6, the application file's 'ICN#' resource has a resource ID of 128 while its 'FREF' resource has a resource ID of 208. For easier code maintenance, you should probably assign the same resource ID to a file's 'FREF' resource that you assign to its 'ICN#' resource.

Informing the Finder that Your Application has a 'BNDL' Resource

You can use 'vers' resources to assign version information to an individual file and, if it is a part of a larger collection of files, to the entire superset of files. The 'vers' resource with ID 1 specifies the version of the file; the 'vers' resource with ID 2 specifies the version of the set of files.

Structure of the 'vers' Resource and Creating a 'vers' Resource Using Resorcerer

The following describes the main fields of a compiled 'vers' resource:

Providing a Finder Icon Help ('hfdr') Resource

Fig 8 shows a 'hfdr' resource being created using Resorcerer.

How and When the Finder Launches Your Application

The Finder then sends your application a required Apple event (called an Open Application event) before relinquishing control to your application. In response to the Open Application event, your application should then perform its usual startup actions, such as opening an untitled document window.

User Double-Clicks a Document Icon or Selects One or More Document Icons and Chooses Open or Print from the Finder's File Menu

In these cases, the Finder reads the creator field of each selected file to find the document's creator. If the document's creator matches your application's signature, the Finder calls the Process Manager, which launches your application, and then sends your application a required Apple event (called an Open Documents or Print Documents event) before relinquishing control to your application. These events contain the name, or names, of the document, or documents, to open or print. Your application should then open the documents in titled windows or print them, as appropriate.

User Drags One or More Document Icons to the Application Icon

In this case, the Finder determines whether to launch your application by comparing the document's file type (stored in the catalog file) against the list of your application's file types. If the document's type appears in the 'FREF' resource list for your application, the Finder calls the Process Manager, which launches your application, and passes your application the name of the selected document, or selected multiple documents, in an Open Documents event. Your application should then open the documents in titled windows.

User Double Clicks a Document Icon - Application Already Running

The following applies to the situation where the user has selected Automatic document translation off in the Macintosh Easy Open control panel.

Missing Application and Application Missing

• If the file is a document file created by an application that is missing, whether the resource fork of that file contains a missing application name string resource, that is, a 'STR ' resource with ID -16396.

• If the file is a file which is not meant to be opened, whether the file's resource fork contains an application-missing string resource, that is, a 'STR ' resource with ID -16397.

Missing Application Name String Resource

• Including a 'STR ' resource containing your application's name in your application's resource fork.

• When your application saves a document for the first time, copying the resource from your application's resource fork to the resource fork of the newly-created document, ensuring that its resource ID is -16396. If this resource is present in the document's resource fork, and the user attempts to open the document when your application is not present, a modal alert box similar to that at Fig 11 is displayed.

Application-Missing

• Including a 'STR ' resource containing the explanation in your application's resource fork.

• When your application creates the file, copying the resource from your application's resource fork to the resource fork of the file, ensuring that its resource ID is -16397. If this resource is present in the document's resource fork, and the user attempts to open the file, a modal alert box similar to that at Fig 12 is displayed.

The file must have a unique signature that no other file application known to the finder is likely to have. This ensures that the Finder will display your message, instead of launching the application with that signature, when the user double clicks on the file's icon.

One 'STR ' Resource Only

Normally, your application sets the file type and creator information in fields of the file's file information structure when your application creates a new file. For example, the File Manager function FSpCreate takes a creator and a file type as parameters (see Chapter 17 - Files). The Finder manipulates the other fields of the file information structure. The file information structure is as follows:

     struct FInfo 
     {
       OSType         fdType;     // Type of file.
       OSType         fdCreator;  // File's creator.
       unsigned short fdFlags;    // Finder flags (invisible, stationery, etc).
       Point          fdLocation; // File's location in folder.
       short          fdFldr;     // Folder containing file.
     };
     typedef struct FInfo FInfo;

Using the System Folder and its Related Directories

Additional folders, such as the Temporary Items and Desktop folders (which are both invisible to the user), are maintained at the root level of the volume. The Trash directory also exists at the root level of the volume.

The Desktop Folder stores information about the icons which appear on the desktop area of the screen. The user controls the contents of the Desktop Folder by arranging icons on the screen. What appears on the screen is the union of the contents of DeskTop Folders for all mounted volumes.

You can use the FindFolder function to get the volume reference number and directory ID of these folders. Folder type constants are passed in the folderType parameter of FindFolder to specify the folder type. The only system-related folders you are ever likely to need are:

• The Preferences folder, to create and access an application's preferences file. The folder type constant kPreferencesFolderType applies. (The demonstration program at Chapter 17 - More on Resources demonstrates creating and accessing a preferences file in the Preferences folder.)

• The Temporary Items folder, to create a temporary file. The folder type kTemporaryFolderType applies. (The demonstration program at Chapter 16 - Files demonstrates creating a temporary file in, and deleting it from, the Temporary Items folder.)

• The Trash folder, to check how much storage is taken by the trash and report this to the user if your application runs out of storage while attempting to save a file. The folder type kTrashFolderType applies.

To support stationery, your application should specify the isStationeryAware constant in its 'SIZE' resource and always check the isStationeryAware bit of a document before opening it. The following is an example function which takes a file system specification structure and returns true or false according to whether the file is a stationery document or not.

     Boolean  isStationeryDoc(FSSpec fileSSpec)
     {
       OSErr    osErr;
       FInfo    fInfo;
       Boolean  result;

       osErr = FSpGetFInfo(&fileSSpec,&fInfo);
       if(osErr == noErr)
        result = ((fInfo.fdFlags & kIsStationary) == kIsStationary);
       else
         result = false;

       return(result);
     }

Ordinarily, when the user wants to open or print files, your application does not need to be concerned with whether they are aliases because both the Finder and the Standard File Package resolve aliases before passing them to your application. However, if your application opens a file or directory without going through the Finder or Standard File Package, your application should always call ResolveAlias just before opening the file.

Relevant Constants, Data Types and Functions

kIsOnDesk       = 0x1
kColor          = 0xE
kIsShared       = 0x40
kHasBeenInited  = 0x100
kHasCustomIcon  = 0x400
kIsStationary   = 0x800
kNameLocked     = 0x1000
kHasBundle      = 0x2000
kIsInvisible    = 0x4000
kIsAlias        = 0x8000

kTrashFolderType        = FOUR_CHAR_CODE('trsh')
kPreferencesFolderType  = FOUR_CHAR_CODE('pref')
kTemporaryFolderType    = FOUR_CHAR_CODE('temp')

struct FInfo
{
  OSType          fdType;     // Type of the file.
  OSType          fdCreator;  // File's creator
  unsigned short  fdFlags;    // Flags, for example, hasbundle, locked, etc.
  Point           fdLocation; // File's location in folder.
  short           fdFldr;     // Folder containing file.
};
typedef struct FInfo FInfo;

struct DInfo
{
  Rect            frRect;      // Folder rect.
  unsigned short  frFlags;     // Flags.
  Point           frLocation;  // Folder location.
  short           frView;      // Folder view.
};
typedef struct DInfo DInfo;

OSErr  FSpGetFInfo(const FSSpec *spec,FInfo *fndrInfo);
OSErr  FSpSetFInfo(const FSSpec *spec,const FInfo *fndrInfo);
OSErr  ResolveAliasFile(FSSpec *theSpec,Boolean resolveAliasChains,
       Boolean *targetIsFolder,Boolean *wasAliased);
OSErr  FindFolder(short vRefNum,OSType folderType,Boolean createFolder,
       short *foundVRefNum,long *foundDirID);

Demonstration Programs

The demonstration program at Chapter 17 - More On Resources shows how to copy an application-missing string resource to the resource fork of a Preferences file.

Using the System Folder and its Related Directories

The demonstration program at Chapter 17 - More on Resources shows how to create and access a Preferences file in the Preferences folder.