Standalones for the MacOS-challenged
by one who is more Challenged than most, with help from many contributors to the SuperCard Mailing List.
Good luck with your standalones!
Graham Samuel, The Living Fossil Co.
V1.1, 4 March 1997
As every SuperCard developer knows, a SuperCard project can be turned into a freestanding application, aka Standalone (SA). This is done using the Standalone Maker (tm) system provided by ATI, which combines your project with the SuperCard Interpreter (SCI) and various other bits and pieces to create a well-formed application, which will start up and run your scripts when opened or double-clicked from the Finder, etc. This note is intended to clarify issues concerning Standalones which are not covered in the Standalone Maker documentation, and which can confuse people who don't know a lot about the MacOS and who don't want to get to grips with any form of programming other than SuperTalk scripting. As it is written by one such person, it is certain to contain inaccuracies and even gross misconceptions, so comments and corrections will be gratefully received.
I assume that you have read the Standalone Maker documentation provided by ATI and that you are familiar with SuperCard scripting. I also assume that your Mac is running System 7.1 or greater.
The emphasis in this note is on the creation of 'classic Mac applications' which contain things like "File" menus which allow one to manipulate documents created by the SA. However we begin with the simplest possible SA. Topics covered are:
1. BNDLs, icons and binding
2. What an SA needs to do to be a good MacOS citizen
3. What you can get away with without doing any special scripting
4. Limitations of the 'non-interventionist' approach
==============================
1.1 Type/Creator Pairs
As explained in the Standalone Maker documentation, the MacOS uses the concept of a Type/Creator (T/C) pair to define a file as a program, and to define other files as being documents associated with ("bound to") that application. The T/C pair is implemented as two four-character codes. It seems that any printable character is legitimate, but that Apple have reserved codes consisting entirely of lower case letters for themselves.
Applications always have a Type code APPL and a Creator code which is your very own, representing the unique 'signature' of your SA. Each document bound to an application (SA) has its Creator code, and a type code representing the type of data which you want it to be. Some type codes, particularly PICT and TEXT are universal and can be read by any program designed to read those data types. Others are private to your SA. Thus if you employ a PICT type of document, when a user double-clicks on its icon in the Finder, your SA will be started (or informed, if it is already open), because the Creator code **binds** it to your SA; but if you try to read it into say Photoshop as a PICT via the "File" "Open" menu item, this will work too.
Each different T/C pair can have its own icon family associated with it. An icon family is described in 1.2 below.
The information about which T/C pairs exist for your SA and what icons the whole caboodle uses are stored in something called a BNDL resource in the resource fork of your application. In the case of SuperCard, Standalone Maker looks after creating the BNDL resource, which you can look at if you are willing to use ResEdit (you'll probably have to do so in the end, however scary it may seem).
Note that the BNDL resource of the SA is the **only** thing the MacOS uses to tell the Finder how to display the icons and what is bound to what. **None** of this information is stored in the documents of your project - not the icon, not the binding information. All that goes in your doc is the T/C pair, and that doesn't go in its resource fork (in fact the doc doesn't need to have a resource fork at all) but somewhere else, presumably the file header [?]. (Sometimes the Finder loses the info which it maintains about the BNDLs of individual applications, and this spells trouble for your desktop in the form of generic icons being displayed instead of the expected ones, and/or a failure to get an application to start by double-clicking on one of its documents - the situation can be recovered by rebuilding the desktop.)
If you plan to distribute your SA at all widely, you should register your Creator and Type codes with Apple. This is quite painless if you have access to any browser - the URL for getting started is:
http://devworld.apple.com/dev/cftype/index.shtml
which is part of Apple's Developer's World site at:
http://devworld.apple.com/devworld.shtml
Note that Apple will give you a list of the unallocated codes, but you can keep on querying their database until you find a free Creator code. Type codes don't have to be unique but should still be registered.
1.2 Icons and Icon Families
The Standalone Maker requires you to provide icons for your application and all its document types. This is explained in the documentation. What isn't explained is that icons come in families. The family is necessary because the icon is obliged by the MacOS to appear in several forms, and each form can appear in two sizes; furthermore icons can be masked to indicate that the corresponding file is selected, in use or is offline. This obliges the icon designer to produce no less than 8 designs, viz:
The basic design, full size (32x32 pixels), in 8-bit colour (i.e. up to 256 colours) - this is the icl8 version of the icon; a small (16x16 pixels) version of the same (ics8); black and white versions of the above (ICN# and ics# respectively); 4-bit colour (16 colours) versions (icl4 and ics4); plus two masks, a full-size one and a small one, which define what the 'selected', 'open' and 'offline' versions of the icons look like - these versions are manufactured by the OS at runtime by combining the mask with the appropriate icon. The combining is done in three different ways, one to give the 'selected' look, one to give an 'open' look, and one to give an 'absent' look - this is like the different ink effects in SuperCard itself.
The best way to create a complete icon family is to open an existing one in ResEdit, copy it into a new document (typically a ResEdit document which you can use as a store for all your icons) and then modify it until it looks the way you want. If you have ready-made 32x32 pictures, you can paste them into the icon editor or ResEdit. I leave the rest, including the clever uses of masks, for you to experiment with.
There is doubtless a great deal more to know, for example about colourisation of icons (different cluts), the possible use of larger icons (64x64 pixels), the ID numbers of icons and if/when they can conflict, but I have not penetrated that far into the icon mystery.
1. BNDLs, icons and binding
2. What an SA needs to do to be a good MacOS citizen
3. What you can get away with without doing any special scripting
4. Limitations of the 'non-interventionist' approach