HyperActivity - Part 1: Start Scripting
Author: Chris Pelkie
Date: January, 1988
Keywords: hypertalk hypercard programming
Text: by Chris Pelkie, Senior Technical Consultant, Cornell Computer Services Manager, Mac Ed Center for Faculty Courseware Development, 215 CCC, Cornell University, Ithaca, New York, 14853-2601. AppleLink A24. HyperActivity is one of the regular HyperCard features in Nibble Mac Magazine. Nibble Mac is published eight times a year, and an 8-issue subscription costs $19.95. from MicroSPARC Inc., 52 Domino Drive, Concord, MA 01742, (617) 371-1660.This article is * 1987 by MicroSPARC Inc., but may be reprinted in User Group newsletters and on BBS's as long as this paragraph is included. Trying to describe HyperCard to someone who hasn't seen it brings to mind the tale of the three blind men trying to describe an elephant - it depends on which end of it you grab hold of first! Apple Computer calls HyperCard ''system software,'' but Bill Atkinson, the developer of HyperCard, QuickDraw, and MacPaint, calls it a ''software erector kit.'' I think of it as an ''information presentation system'' because it allows you to create associations easily within a set of information, including text, graphics, sound, music, even videodiscs and other external devices. While the name HyperCard might imply that a special piece of hardware is involved (like a printer card or a video card), in fact, this program is entirely software. The only hardware required is a Macintosh Plus, Macintosh SE, or Macintosh II, preferably with two disk drives. The basic unit of information in HyperCard is a card, which is one screenful of text, graphics, and buttons; a group of related cards make up a stack. A stack is a HyperCard document and, like any other document, is displayed as an icon by the Finder. Though not required, having a hard disk is very desirable, since HyperCard can take advantage of as much stackware as you can fit on a hard disk. Related cards generally share a consistent appearance, like library catalog cards or pages in a spiral notebook. For example, a teacher may combine illustrations and maps with a set of lecture notes. She can establish cross-references to definitions of important terms or link close-up views to larger maps. Her students can browse through this information network in any order that makes sense to them, rather than in a strictly sequential order. Even more exciting, a student can add his own associations to this set of information, similar to highlighting important passages in a book, but in a much more dynamic and personal way. This ability to jump around in a collection of information is more like the way many of us browse through a library, a dictionary, or encyclopedia - we follow interesting trains of thought and investigate side paths before returning to the mainstream. But no one has been able to use a computer this way before. The prefix hyper is used in its traditional sense of over, above, beyond, which implies that you can travel through hyperspace from card to stack to graphic without following a straight line, that you can get from point A to point C without passing through point B. In fact, everyone who sees HyperCard tends to get a little hyper in the modern sense of overexcited as they start to envision its potential. This brief introduction to HyperCard only scratches the surface of its many features. In this article, I want to introduce you to one of its most remarkable features - the scripting capability - by describing the built-in HyperTalk language. Working closely with Bill Atkinson, Apple's Dan Winkler has created a new way for ''the rest of us'' to teach our Mac how to perform some clever feats. For jargon lovers, HyperTalk is a high-level, object-oriented, interpreted computer programming language. I hope that's the last time I have to call it that! If you aren't a programmer, don't turn the page - writing a HyperTalk script may be the most exciting thing you have ever done on your Macintosh! Scripts are almost English-like, but HyperTalk gives you access to Mac features previously reserved only for those who have read the programmer's manual Inside Macintosh at least twice. HYPERTALK SCRIPTS Let's start by creating simple scripts that perform flashy effects and ease into more sophisticated tasks later. Open your copy of HyperCard, and choose New Stack from the File menu. To start with a clean white card, uncheck the Copy current background button by clicking it. Name your stack ''Script Stack'' and save it to the disk. A HyperTalk script is a set of instructions attached to a button, field, card, background, or stack. Think of each of these objects as actors in a play, each with his own script to perform. As in a play, each actor speaks only his lines and makes his moves on cue. So how do we cue a HyperCard object to perform? There are a number of cues that HyperCard understands, but the most common and the most familiar to any Mac user is the button click. Think about the hundreds of OK buttons you've clicked in your Mac career. When does a button do what it is designed to do? The precise answer is: When you press the mouse button down while the cursor is on top of the button, then release the mouse button while the cursor is still on top of the button. Remember, if you press the mouse button down on a button but drag the mouse away before releasing it, that button will not be activated. So the essential cue a clicked-on button sends to HyperCard is ''the mouse went up.'' The first command in a script is frequently on mouseUp, followed by the set of instructions you want performed, and terminated by end mouseUp. (Peculiar capitalization is not required, but it's typical of people who have stared at Pascal code for too long. If you want people to think you are a knowledgeable Mac hacker, just capitalize compound words in the middle instead of using spaces.) With that background, let's write a script that's attached to a button. First, create a new button by choosing New Button from the Objects menu. Double-click on the new button, and change its name to ''My Button'' by typing in the appropriate place in the dialog box. Click the Script button in the lower left area of the dialog box. You are now in the script editor dialog box. Note that HyperCard has already filled in the on mouseUp and end mouseUp commands for you, and the blinking insertion point is conveniently placed right between them, waiting for your instructions. Type go Home. Your script should look like this (you don't need to type the comments at this time): on mouseUp --when the user releases the mouse button go Home --go to the first card of the Home stack end mouseUp --return control to user Note that each command in a script appears on its own line. You can add new lines by pressing the Return key at the end of the previous line. Next, click on the OK button, or press the Enter key to leave the script editor. Now choose the browse tool (the hand with the pointing index finger) from the Tools menu. When you return from the script editor, you are still in the button editing mode but to try out a script, you must select the browse tool, so you can click on the button. Ready? Click your new button with the browse tool's index finger. One of three things will happen: 1. If you typed the script correctly, you are now looking at the Home Card. Congratulations! Press the key at the top left of the keyboard (either the Escape key or the tilde (~) key) to return to Script Stack. 2. If you accidentally typed in something that HyperTalk couldn't understand, you'll see a dialog box complaining about the problem. If this happens, click the Script button to return to the script editor and check your spelling and typing. Generally, the insertion point will be blinking near the spot where HyperTalk got confused, so look there first for the problem. 3. You may have typed something that is neither correct as far as you are concerned nor an error as far as HyperTalk is concerned. The symptom for this problem is that nothing happens when you press My Button. For instance, if you had pressed the script editor's OK button before you added the command go Home, the script will be perfectly legal but do absolutely nothing. To check your script, choose the button tool (in the middle of the top row in the Tools menu), double-click My Button, and then click the Script button in the Properties dialog box. Another common mistake is to edit a script, and then click the Cancel button. Of course, none of your edits will be recorded if you do this, but since you are sure you just made those changes, you can't understand why they don't work! I've found that this is particularly maddening at two o'clock in the morning. As we get to more advanced scripts, refer back to the above set of cases if you encounter problems. Those three basic situations are the most common: your script works as planned, your script has errors and can't be understood, or your script either doesn't do anything or does something you don't want it to do. In all but the first case, you must chase the bugs out. We'll discuss debugging tips as we need them. Right now, let's add the promised flash to this script, so you can amuse your friends and amaze your neighbors. First, return to the script editor. Here's a trick to speed things up: choose the button tool from the Tools menu, then hold down the Shift key while double-clicking the button tool on My Button to go straight into the button script. Click after the words on mouseUp, and press the Return key once. Type visual effect dissolve to gray.
Your script should now look like this: on mouseUp visual effect dissolve to gray go Home end mouseUp Press the Enter key or click the OK button to leave the script editor. Now here's another keyboard shortcut: press the Command key and the Tab key together to reselect the browse tool (or just select browse tool from the Tools menu). Try out your new button script by clicking on My Button. See the difference? When you see the Home Card, press Escape or ~ to return to your stack. There are a number of fancy visual effects like dissolve that you can use whenever you write scripts that move from one card to another. Some of the others include iris open, barn door close, checkerboard, and wipe up. The complete set is documented in the Help Stack and can be found by choosing Help from the Go menu, clicking the tab labeled HyperTalk on the bottom of the Help card, clicking on the word Commands, then clicking on the command visual effect. If you want to take a look at the Help stack right now, go ahead. When you are finished, simply click the Exit tab in the bottom right of the Help card to return to your Script Stack. To try another visual effect, go back into the script of My Button and change the effect type from dissolve to one of the others. The added effect to gray can be removed if you like. The correct syntax of the visual effect command is listed in the HyperTalk help as follows: visual [effect] <type of effect> [speed] That means that the word visual is required, although ''effect'' is optional. An effect type is required, but modifiers like to gray or slow are optional. This way of describing a command's syntax is used throughout the HyperTalk command reference stack. Remember, if a command word is not surrounded by square brackets, it's a required part of the HyperTalk command, but words in square brackets are optional. Words in angle brackets are place holders for specific values that must be substituted in place of the words (don't type the angle brackets in the actual script command). Allowable substitutes are usually listed in the Help stack. In many cases, the replacement value can even be a computed value. LEAVING A TRAIL Return to the stack ScriptStack if you aren't there already (just press ~ until you see the card with New Button on it.) Choose New Card from the Edit menu, select the paint brush tool from the Tools menu, and then make a doodle on the new blank card. The doodle will serve as a visual cue when you return to this card later. I'll refer to this card as the doodle card and the card containing My Button as the button card. By the way, when you choose the New Card command, the new card is added right after the card you are viewing. Let's add some more commands to our button script. Choose Prev (previous) from the Go menu to return to the button card. Select the button tool, and then click once on My Button. You should see the ''marching ants,'' indicating that the button is selected. Put the mouse in the center of the button, and drag the button to a new location. You can also resize a selected button by placing the mouse arrow tip in one of the four corners of the button and dragging. Try resizing your button. If you end up relocating the button, try again but be sure the arrow tip is very close to a button corner before you press down the mouse button. Another important capability of HyperCard is that you can copy a button and paste a copy onto any other card in any stack along with all the button's properties, including its script. For example, with your button still selected, choose Copy Button from the Edit menu, then choose Paste Button from the Edit menu. Since the copy is superimposed on the original, drag the copy away to make sure that there are really two buttons. Double-click the copy and change its name by typing in the Button Properties dialog box. Let's name it ''Flash Button.'' Type the new name then click the Script button in the dialog box to modify this button's script. When you enter the script editor, you'll see that Flash Button and My Button have identical scripts. Edit the third line of the script to read go Next rather than go Home (shortcut: double-click on the word Home and then type Next). Click OK to leave the script editor, choose the browse tool, and test the action of Flash Button. You should be looking at the card with your paint doodle on it, since it's the next card in Script Stack. If not, follow the debugging steps presented earlier to check Flash Button's script for mistakes. Press Escape or ~ to return to the button card and open the script editor dialog box for Flash Button. Add these lines just before end mouseUp: push recent card wait 2 seconds pop card Exit the script editor and try the Flash Button now. The doodle card will appear for two seconds, and then return automatically to the button card. The function of the command wait 2 seconds is obvious, but push recent card and pop card need some explanation. Think of a card game which uses a deck of playing cards. When one player discards a card to the top of the deck, that card becomes the first one that the next player can draw. In HyperTalk, adding a card to this imaginary deck of cards is called ''pushing'' a card. When you remove the top card, the action is called ''popping'' a card. You may push any number of cards before you begin popping them off in the reverse order. Pushing a card has no visible effect, but when HyperCard pops a card, it automatically displays that card after removing it from this imaginary deck. These commands are useful when you write scripts that allow a HyperCard user to browse through different cards, and then return along the same path. Although it's impossible to know ahead of time exactly which card the user will be looking at when he jumps to another card, you still want to provide a trail so he can find his way back. In Flash Button's script, we go to another card and push the recent card, which instructs HyperCard to add the last card we were looking at (the button card) to our imaginary card deck. After we look at the doodle card for two seconds, HyperCard pops the top card off the deck and takes us back to that card (the button card). Push and pop don't have to occur within the same script. You can push a card on the stack and go to another card. That card may have a button whose script contains a pop card command. In fact, it's generally a good, user-friendly practice to provide a Return button in your stacks (the arrowhead that hooks down and to the left), and push and pop is one technique you can use. This Return button is the browsing equivalent of an Undo command, which lets the users of your stack back up and explore another path whenever they like. GETTING USER FEEDBACK There will be many occasions when you want to allow the user to spend more time looking at a card. It isn't very nice to show them something interesting and then whisk them away before they're done admiring your artwork. Instead of using the wait command with a fixed delay, you can write a command that will pause until the user gives the go ahead cue. To do this, return to the button card, and enter the Flash Button script editor. Change the script so that wait 2 seconds is replaced by repeat until the mouse is ''down''. Press Return to start a new line, and add the command put the long time and press Return. You'll notice that the final command end mouseUp does not line up at the left margin of the window. That indicates that you haven't entered a valid script. Whenever you start a ''repeat'' command, you must also add the line end repeat after the instructions you want repeated. If you think of end repeat as a close parenthesis that matches the open parenthesis of repeat, you probably won't forget to add it in your own scripts. Your script should now look like Example 1. EXAMPLE 1 on mouseUp visual effect dissolve to gray --you may have entered your own effect go Next --show the next card in this stack push recent card --remember the card we just left repeat until the mouse is down --keep doing until mouse button pressed put the long time --put the current time (h:m:s) into message window end repeat --don't forget this command! pop card --go to the first card on top of our return deck end mouseUp See how the commands are indented? On mouseUp and end mouseUp should line up, as do repeat and end repeat. The command put the long time is indented within the repeat subsection which indicates that the command will be repeated until the user presses the mouse button to end the repeat loop. When the loop ends, the rest of the script will be performed. Although the explanatory comments in the script are optional, you should get in the habit of adding comments to your scripts to explain commands that may not be obvious. A comment is preceded by two hyphens (--). HyperCard will ignore comments, so they don't cause syntax errors. Reading a script a month from now will be much easier if you've commented it. Also, if you plan to share scripts with others, they will understand your scripts much more quickly if you comment them. Test your modified button script and make sure that everything works. HyperTalk understands a number of variations of the repeat command. But for beginning script writers, the basic concept to learn is that a loop is a set of instructions that are performed repeatedly before going on to the instructions that follow the loop. If this is an unfamiliar concept, think of the actions you perform when setting the dinner table. The sequence of instructions (the place setting script) might read: on tableSetting take place settings to dining room repeat until all plates are in position put one plate in position end repeat return to kitchen for glasses --and so on end tableSetting For an average family, you could write repeat 4 times, but then you'd have to rewrite the script for guests. Specifying a fixed value is sometimes called hard-wiring and would not be desirable in this case. There are better ways to design a script in HyperTalk if you don't know in advance exactly how many times to repeat a loop. One good way is to ask the user to type a number, and then use that number in the script. We used another technique above when we repeated the loop ''until'' the user signaled us that all the plates were done. This is called an infinite loop, since it will keep repeating forever if the user doesn't click. If you ever suspect you're caught in an infinite loop, you can terminate any HyperCard script by pressing Command-Period. Let's write a simple script that asks you how many times you want the Mac to beep. To begin, return to the button card and choose New Button from the Objects menu to create another button. Double-click on the button and change its name to ''Beeper.'' Then click on the Script button and enter the script shown in Example 2. EXAMPLE 2 on mouseUp ask "How many beeps" --displays a dialog box asking for user input --the number the user types is placed in a container called "it" put it into beepCount --put value of "it" into the container "beepCount" repeat beepCount --repeat the number of times equal to beepCount beep --beep the Mac speaker wait 30 ticks --one half second pause between beeps end repeat end mouseUp ASKING FOR IT There are couple of new HyperTalk features in this script. First, the command ask followed by a quoted phrase is the fast and easy way to display a dialog box to the user. The quoted phrase will be displayed as the message in the dialog box. A space is provided for the user to type the requested information, and an OK and a Cancel button are provided automatically. When you enter your answer to the request and click on OK, the answer is stored temporarily in a special HyperTalk container called ''it.'' This is a special object called a variable in traditional programming languages. You created another variable or container called beepCount in your script. Containers are similar to mailboxes. A mailbox has a name on the outside, like Smith or Jones, but the contents of the mailbox are neither Smith nor Jones, but letters or bills. Likewise, we can refer to a container by its name (it, beepCount), but the contents of that container may be numbers or text. In this script, when the user provides a response, say 5, the value 5 is first automatically placed in the container called ''it'' by HyperTalk. Since ''it'' is used for lots of things, it's usually good practice to store the value of ''it'' in a container that you create. To send a letter to Smith, we address it to his mailbox; to put a value into a container, we call the container by name. It's a good idea to give your containers names that mean something to you. Since you asked for the number of times to beep, our container is called beepCount. The command put it into beepCount does two things: it creates a new container called beepCount and, at the same time, stores a copy of the current value of ''it'' in beepCount. In this short script, the value of ''it'' doesn't change, but you will be writing longer scripts where ''it'' may change several times in one script. The script then beeps the speaker for the number of times stored in beepCount. So you didn't have to hard-wire the number of beeps-we get that information whenever this script is performed. Try the script a couple of times and give different numbers each time to check that the script works as advertised. We've learned about buttons, containers, loops, scripts that allow the user to have some input and control, and a handy way to return to the last card we visited. Next time, we'll look at some more HyperTalk commands and system messages and learn how to use HyperCard fields to display information. We'll also encounter two more important programming concepts, conditional statements and modular design.
Copyright © january, 1988 by Chris Pelkie