by Gareth Jones
HyperCard, in either its Macintosh or IIGS versions, handles text with aplomb. It can grab text files, find specific words or phrases or locations, move it about, and change it on the fly. Not surprisingly, one of the more common forms for a stack is a single card with a single field which holds text, and a script which changes it in some way.
Before you can change text, however, you must get it. This article shows how to Open and Read a text file into a HyperCard stack. The instructions apply to both Macintosh and IIGS HyperCard.
First, check the User Level at which your copy of HyperCard is set. Type Command-M to bring up the Message Box. Type the phrase "put the userlevel" in it and press return. If any number but 5 appears in the box, then type "set the userlevel to 5" and press return again. This change will last for your current session of HyperCard, but permanently changing your userlevel means changing a setting in your Home stack.
Let's start by creating a new stack for your experiments. Launch HyperCard, then select "New Stack..." from the File menu. Type in a name (e.g. "TextStack") for your new stack in the normal "Save File" dialogue box that appears. Do not bother to click in the checkbox for "Copy Current Background." Now click "Create" on the GS or "New" on the Mac to create your stack.
The completely blank screen (GS) or window (Mac) that appears is your new stack. Lets get ready for your experiments now by creating a card button and a background field. From the Objects menu select "New Button", and drag the button to the one side of the screen. To make sure that the field will be created in the Background layer of the card, press Command-B or select "Back-ground" from the Edit menu. (Your new button will seem to vanish, but don't panic! It will be visible again when you leave the background layer). Now create a field by selecting "New Field" from the Objects menu.
The new field will probably need a little more space than it gets by default, so drag any corner of the field away from its centre to increase its size.
Now double-click in the centre of the field to open up a dialogue box that lets you set a few other attributes of the field. Give it a name, first of all: Type "TextField" in the appropriate area. Now select the Style of the field. To do this on a IIGS, put your cursor over the boxed word "Transparent" and hold down the mouse button to reveal the other choices from a pop-up list. Select "Scrolling" as the type for your field, then let go. On a Mac, click the circular button beside the word "Scrolling." In either, click "OK" to leave the dialogue box, and Command-B again to get out of the background.
The next step is to write a small program that will let you select a text file and put it in TextField. An unusual aspect of HyperCard is that a program is attached to an object. You could attach this program to the field, or card, or background, or the stack itself, but the most direct place to put it is in the button youUve made. So try this
You're now in the Script Editor, a little word processor where programs ("scripts") are created. It's time to start programming by typing in the following text:
on mouseUp answer file "What text file should I open?" of type text put it into fileName end mouseUp
Let us interrupt this for a moment to discuss the next part of the program. Before you can read a book, you have to open it. HyperCard is similar in that, before you can read a file, you have to tell HyperCard to open it with a line like:
open file filename
And if you're a teacher telling a student to read a book, you'll probably tell him how much to read, too. Either "read until you get to the word 'antimatter'" or "read until you get to the end of the book" or "read one chapter". In HyperCard, the equivalents to those commands are:
read from file fileName until "Antimatter"
read from file fileName until end
read from file fileName for 16384
The number 16,384 above (also known as 16K, in computerese) is the maximum number of characters which can be read with a single command by HyperCard IIGS and by versions of Mac HyperCard earlier than 2.2. (HC 2.2 and 2.3 are limited only by the amount of free memory). If your text file is likely to be smaller than 16K, then there's no problem. If it is over 16K, however, you need to issue several commands, such as this:
read from file fileName for 15000 put it into theTextVariable read from file fileName for 15000 put it after theTextVariable -- (etc.)
The code above would put up to 30,000 characters of text into a variable called "theTextVariable". Thirty thousand characters, by the way, is the maximum amount that a HyperCard field can hold. Variables can hold any number of characters, however, limited only by the amount of free memory available to HyperCard.
It isn't a clean, easy, or simple solution to write multiple lines that say (in effect) "read another chunk" and "another chunk" and "another chunk". A better one is to put the command to read a chunk into what is called a "repeat loop," which is a specialized command to do something more than once. You will see what that looks like in the next section.
We've discussed all the code that you'll need for the rest of the program, so please add the following to your script:
open file fileName
put empty into theTextVariable
repeat forever
read from file fileName for 16384
if it is empty then exit repeat
put it after theTextVariable
end repeat
put character 1 to 30000 of theTextVariable into background field 1
end mouseUp
On a IIGS, finish up your work by clicking the "OK" button at the bottom of the Script Editor. On a Mac, click the Close box in the top left corner of the script editor window and answer "Yes" when you're asked if you want to save the changes to your script.
At this point, you should have a working stack!
You can't click on a button to make it work if you have the Button tool selected. So go to the Tools menu and select the Browser tool. (That's the one that looks like a hand). Now click on the button. YouUll be able to select a text file, and when you do, the first thirty thousand characters of it (which is probably the whole thing) will appear in the scrolling field. You can look at it, select text, change it - very much like using a word processor.
Quitting HyperCard or the stack automatically saves all the work you've done. This is good, since the next articles in this series will add more word-processor-like features to it: a search-and-replace function, a "Save file" button, and more.
Gareth Jones is the former Editor of Apples B.C. News and a Contributing Editor of Hyper Quarterly, a new magazine-on-disk devoted to HyperCard IIGS stacks.