H O M E

Jonathan Cooper Manager of Information, Art Gallery of New South Wales, Sydney, AUSTRALIA

An Extensions Folder for HyperCard

Originally published in MACinations (Club Mac, Sydney, Australia) June/July 1994, altered November 1997

A big part of the appeal of HyperCard is its extendibility: If you find that HyperCard, "out of the box", does not have a certain feature that you want, this feature can often be added without having to touch the application itself. These "extra features" include sounds, icons, commands, functions, external commands (XFCNs), external functions (XFCNs), floating palettes and menus (1). Before HyperCard 2.0, features other than commands and functions written in HyperTalk itself had to be installed into your Home stack using a resource moving program such as ResEdit or ResCopier if you wanted them to be available to all your stacks. In a similar way, HyperTalk commands and functions had to be added to the script of the Home stack. With the introduction of HyperCard 2.0, up to ten stacks can be temporarily put "in use", meaning that until you put such a stack "out of use" or you quit HyperCard, that stack's features (2) can be accessed by any other stacks you go to. All you need is to type the command "start using " or "stop using " then a valid stack name into the message box and press return.

As easy as this is, some features are so useful that they deserve to be available every time that HyperCard starts up. One way of doing this would be to add a line to the "startUp" handler (3) within the script of your Home stack, in the form "start using stack <stackName>", for each stack you wanted to use. But wouldn't it be nice if you could add features to HyperCard as easily as you can already add features to your System, that is by putting files into a folder (like the Extensions and Control Panels folders in the System Folder)? You can, by following the steps outlined below; and, in the process, you will hopefully learn some useful HyperCard/HyperTalk tips.

The first thing we need to do is to create a way for HyperCard to look inside a particular folder and list all the stacks it finds there. The prolific HyperCard developer Frederic Rinaldi has created a free external function called "GetDir" which will do the trick. "GetDir" is very powerful, which means its syntax can get rather complicated. Fortunately, in its simplest form --

getDir(<folderPath>)

-- it returns a list of the names (i.e. not the full path names (4)) of all the files it finds inside the folder <folderPath>, one file per line. As long as we only put stacks in there, this will work fine. Since "GetDir" requires the full path of the folder it is to search, we need to define it in such a way that it will still work even if we do something like rename the hard disk or move or rename the HyperCard folder. In HyperCard 2.1, there is a version of the HyperTalk property "name" that will supply this. [If you only have HyperCard 2.0, read the footnote (5).] The expression "the long name of HyperCard" will return something like "Hard Disk:HyperCard Folder:HyperCard 2.1". All we have to do is replace the last part (after the last colon) with the name of our folder (which we will call " Start Using Folder"). With HyperCard 2.1 and above, the easiest way is to change the itemDelimterfrom the default (comma) to a colon, replace the last item, then change the itemDelimiterback to a comma (6). So, we now have enough to create a list (which we will call stacksToUse ) of the stacks we want to use:

    put the long name of HyperCard into SUfolder

    set itemDelimiter to colon

    put "Start Using Folder:" into last item of SUfolder

    set itemDelimiter to comma

    put getDir(SUfolder) into stacksToUse

    repeat with i=1 to the number of lines in stacksToUse

    start using stack (SUfolder & line i of stacksToUse)

    end repeat 

But wait! This is only designed to work if the original stacks are placed in the folder. Alternatively, you could put aliases there but they would have to be named exactly the same as the originals. The trick is to let the Macintosh System resolve the aliases by (very quickly) opening each alias, which of course opens each original stack.

It would be a nice touch if we could see which stacks were being put "in use" as HyperCard starts up, in the same way that the row(s) of icons along the bottom of the screen tell us what optional extensions and control panels are being loaded when the computer itself starts up. No problem! Just get our handler to put the name of each stack in the message box, one after the other.

So, here is our final handler (7):

  on autoStartUsing

    put the long name of HyperCard into SUfolder

    set itemDelimiter to savedItemDelimiter

    put "Start Using Folder:" into last item of SUfolder

    set itemDelimiter to savedItemDelimiter

    put getDir(SUfolder) into stacksToUse

    lock screen

    lock messages

    push this card

    repeat with i=1 to the number of lines in stacksToUse

      get line i of stacksToUse

      go to stack SUfolder & it -- This resolves the alias

      put "Starting to use:" && short name of this stack into message box

      start using this stack

    end repeat

    pop card

    put empty into message box

    hide message box

  end autoStartUsing 

To make it work, you have two options: install it all in your Home stack or have a separate stack to which the Home stack will send "autoStartUsing".

Option 1:
Go to your Home stack and press command-option-S, the shortcut for opening the stack script. The handler can appear anywhere in the script (except within another handler, of course!) but the best place is probably right at the end; scroll down to the end and type in the handler. Then scroll back to the beginning and find the "startUp" handler (it starts "on startUp" and finishes "end startUp"). Click at the end of the line just before "pass startUp", press return and type the word "autoStartUsing". Press enter to save the changes and close the script.
Next, you will need to install the external function "GetDir" into your Home stack. If you think you might like to explore other externals, the best way would be to get a copy of the stack "XArchive 3.2", a collection of over 125 XCMDs and XFCNs by Frederic Rinaldi, available from Club Mac or from any good Mac ftp site. This stack will even install the XFCN (or XCMD) for you. (Important note: Whenever you install a resource into the active Home stack, you will need to quit HyperCard and launch it again for the resource to become available.)

Option 2:
If you had a stack containing the "GetDir" XFCN and the "autoStartUsing" handler (in the stack script), you could have the Home stack send the "autoStartUsing" message to this stack:

  send "autoStartUsing" to stack <stack name>

I have created just such a stack, called "Extensions For HyperCard" (previously "Auto Start Using"), which also a few extra features, such as buttons for automatically adding and removing the "send" line from the Home stack script, a field which tells you at any time the list of stacks which are currently in use and an easy way to edit this list. It can be downloaded by clicking on the link above.

Passing messages

One last important point: If you are going to "use" a stack (either automatically or manually), check the stack script for handlers that trap common messages such as "openStack", "closeStack" etc. Unless there are lines that deal with the possibility of the stack trapping messages from another stack, you will get error messages like "No such card". To stop this unwanted behaviour, add the following line immediately after the "on <message>" line:

  if the name of this stack is not the name of me then pass <message> 

___

FOOTNOTES:

1. All types of features, except for the external commands and functions, can be created by the ordinary end-user, with HyperCard 2.0 or higher (and for sounds, a computer with sound input, such as an LCII). All types (including the externals) can also be obtained for free or a modest shareware fee from sources such as the Club.Mac.BBS.

2. That is: all resources (sounds, icons, palettes, XCMDs, XFCNs) and all HyperTalk commands and functions that are part of the stack script.

3. The Home stack's "startUp" handler is triggered when HyperCard starts up. It normally contains commands that set the user's preferences (entered on the Preferences card) and check for missing fonts.

4. A file's pathname includes the names of all the folders enclosing it and the name of the volume (or disk) it is on separated by colons, in the form "Disk:Folder 1:Folder 2:...:File". E.g. "Hard Disk:Apps :HyperCard:Home". Folder pathnames always end in a colon.

5. With HyperCard 2.0, it's a little more complicated than this. Firstly, you can't get the name of HyperCard itself. Instead, you have to get the long name of Home, which would give you something like "stack "Hard Disk:HyperCard Folder:Home"". Secondly, you can't change the itemDelimiter. Instead, you have to strip out the word "stack" and the quotation marks and substitute the last four characters of what's left with the string "Start Using Folder:". For the actual lines of HyperTalk, see footnote (7).

6. This is probably not necessary as the itemDelimiter defaults to a comma on idle, but it is best to be sure, just in case another handler that uses items executes before the next idle message.

7. For HyperCard 2.0, substitute lines 2 to 5 with the following:

    put the long name of Home into SUfolder

    delete char 1 to 7 of SUfolder

    put "Start Using Folder:" into char (length(SUfolder)-4) 

    to length(SUfolder) of SUfolder

( is the option-return or continuation character; it simply makes long lines more readable within the script editor window.)