Path: news1.icaen!news.uiowa.edu!feeder.chicago.cic.net!su-news-hub1.bbnplanet.com!news.bbnplanet.com!newsfeed.direct.ca!nntp.portal.ca!news.bc.net!unixg.ubc.ca!freenet.vancouver.bc.ca!not-for-mail
From: gareth@vcn.bc.ca (Gareth Jones)
Newsgroups: comp.sys.apple2.comm
Subject: HC Text Import Article
Date: 10 May 1997 18:39:58 GMT
Organization: Vancouver CommunityNet
Lines: 150
Message-ID: <5l2fdu$6r4@milo.vcn.bc.ca>
NNTP-Posting-Host: opus.vcn.bc.ca
X-Newsreader: TIN [UNIX 1.3 BETA-950824-16colors PL0]

Importing text files into HyperCard (ABC97.05)
     
     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.
 
     Get Ready
 
     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.
 
     Make the button script - Part 1
 
     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
     
     1. Go to the Tools menu, and select the Button tool. (It's the
rounded rectangle in the first row of tools).
     2. Double-click on the button you made to open up a dialogue box.
     3. Type in a name for the button in the appropriate spot. ("Import,"
for example).
     4. Click on the button called "Script..." in the dialogue box.
     
     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
 
 
     Explanations
 
     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.
 
     Make the button script - Part 2
 
     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!
 
     Using the New Stack - and looking beyond
 
     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.