H O M E

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

HyperCard, Hypertext, Hypermedia

Originally published in MACinations (Club Mac, Sydney, Australia) September 1994

This [article] began life as a tutorial stack for the Club Mac HyperCard Special Interest Group. It demonstrates how HyperCard can be used to create online documents with hypertext and hypermedia features with a minimum of scripting.

Although HyperCard can be adapted to just about any kind of task, it really shines in the area of information delivery. In fact, I believe the very first HyperCard stack to be seen by the public was an introduction to the 1987 Macworld Expo in Boston. Since then, HyperCard has been used, amongst other things, to run on-line help systems for other applications (e.g. ClarisWorks) and interactive multimedia systems in museums and on CD-ROMs (1). It is also used as the basis for Voyager's popular series of "Expanded Books". Yet, to just create a stack with card after card of scrolling text is to miss the point entirely. Bits of information in one place should be linked to bits of information in other places, and this should include non-text information such as pictures, sound and moving images. But how? If there is a lot of text, programming all these links can be a real pain, if not impossible. Fortunately, with just a little over 100 lines of HyperTalk in the stack script and a few easily obtained resources, you can build in automatic hypertext/hypermedia with cross-referencing, full-colour pictures, sounds and QuickTime movies.

The method is basically:

1. Flag every piece of link text by its style and font; each piece of link text has its style set to "group" (which puts a grey underline under it, if that property has been turned on) and particular kinds of links (text cross-reference, picture etc.) are indicated by particular fonts.

2. Put a handler in the stack script that will trap every mouseUp message that has not been trapped by the scripts of any other objects. This mouseUp handler just checks that it was indeed a field that was originally clicked on and that the text clicked on was "grouped". If so, it determines what kind of link it is and finally make the appropriate link.

A typical card might look like this: (The user has just clicked on the word "one" to launch a QuickTime movie of the same name.)

How to do it

Open the script editor for the stack script (the quickest way is by typing command-option-S) and enter the following. Remember, any text on a line after double hyphens (--) is to help you understand how it works and can be omitted. All quotes should be entered as straight quotes (").

on openStack
  show groups -- makes grey underlines visible
  set userLevel to 5 -- just in case
end openStack

on closeStack
  hide groups
end closeStack

on resumeStack
  openStack
end resumeStack

on suspendStack
  closeStack
end suspendStack

on mouseUp
  if "field" is not in the target then exit mouseUp
  -- if it wasn't a field that was clicked on, then forget it!

  put the clickChunk into theChunk
  -- in the form "char <a> to <z> of bkgnd|card field <n>"

  if "group" is not in textStyle of theChunk then exit mouseUp
  -- likewise if the clicked text was not grouped

  -- make the clicked text flash on & off
  select theChunk
  select empty
  wait 10 ticks -- (60 ticks = 1 second)

  get the clickText
  -- put the clicked text itself into it

  put textFont of theChunk into theFont
  if "Helvetica" is in theFont then showPict it
  else if "Courier" is in theFont then play it
  else if "Chicago" is in theFont of theChunk then playMovie it
  else jumpTo it
end mouseUp

on showPict pictName
  picture pictName
  put "Shift-Click to expand. Option-click to shrink. Click to close"
end showPict

on playMovie movieName
  -- requires XCMD "movie" (from stack "QuickTime Tools")
  set cursor to watch
  movie movieName
  if the result is not empty then
    answer the result
    exit playMovie
  end if

  --delete (or comment-out) next line if you DON'T want movie to auto-close:
  set closeOnFinish of window movieName to true
  send "play" to window movieName
end playMovie

on jumpTo theText
  push this card
  set lockMessages to true -- ignore any openCard, closeCard messages
  set cursor to watch
  lock screen
  go next -- so we don't find the text on this card again!
  find whole theText -- add <<in field "Title">> if required
  put "find whole" && quote & theText & quote into message
  hide message -- get it out of the way
  -- in case user wants to keep looking, by pressing return-key
  palette "Return/cancel","1,11" -- so user can get back easily
end jumpTo

on mouseDownInPicture pictName
  -- option-click shrinks, shift-click expands
  get scale of window pictName
  if the optionKey is down then
    set scale of window pictname to it-1
    set zoom of window pictName to out
  else if the shiftKey is down then
    set scale of window pictName to it+1
    set zoom of window pictname to out
  end if
end mouseDownInPicture

on mouseUpInPicture pictname
  -- close picture when clicked on
  if the optionKey is up and the shiftKey is up then -- see prev handler
    close window pictName
    put empty into message -- message box held instructions
    hide message
  end if
end mouseUpInPicture

on popAndHide
  pop cd
  if there is a window "Return/cancel"
  then close window "Return/cancel"
  put empty into message -- message box held instructions
  hide message
end popAndHide

on cancelPop
  pop cd into it
  if there is a window "Return/cancel"
  then close window "Return/cancel"
  put empty into message -- message box held instructions
  hide message
end cancelPop

How it works

openStack, closeStack, resumeStack, suspendStack
- mainly for making "group" text grey underline visible.

mouseUp
- the central handler. This traps the mouse clicks and tests to see...a) that it was on a field, and b) that the clicked text was "grouped". If so, then it calls one of three custom messages: showPict, playMovie and jumpTo

showPict, playMovie, jumpTo
- The reason why these custom handlers were created was in case their special features needed to be accessed from other handlers

mouseDownInPicture, mouseUpInPicture
- to give the picture windows special properties: to expand when shift-clicked, to shrink when option-clicked and to close when (plain) clicked.

popAndHide, cancelPop
- two messages called by the special "Return/cancel" palette, displayed when the jumpTo message is triggered.

The Externals

The script, as listed above, refers to two external resources:

1. Palette "Return/Cancel" - for the text cross references

This was created (with incredible ease) using the Power Tools stack. To create your own, go to the stack "Power Tools" (which comes bundled with HyperCard 2.0, 2.1 and 2.2 [& 2.3]), and click on the words "Palette Maker". From there, just follow the step-by-step instructions. (Don't forget the help button - with the light-bulb icon.)

1. Palette name: "Return/cancel"
2. Palette workspace: Create artwork something like this, with two buttons:

The scripts of these buttons should be (apart from on mouseUp and end mouseUp) "popAndHide" and "cancelPop" respectively.
3. Window style: This is a personal choice, but I prefer no title.
4. Hilite type: Inverse hilite, Remain hilited.
5. Create palette: Just click.
6. Install palette: Click and select your stack.

2. XCMD "Movie"

This external command was installed from the QuickTime Tools stack (which comes with the QuickTime Starter Kit). [NB: If you have another stack that plays QuickTime movies it may have a different XCMD with a different syntax.]

The basic syntax to open the movie is:

Movie <file name>,<window style>,<location>,"[in]visible","[non]floating"

(Where <file name> is the name of the movie file.)

This is the only required parameter. If the others are omitted (as they are in the playMovie handler), <window style> is "windoid", <location> is the centre of the screen, the window is initially "visible" and the window is in the "floating" layer.

To play the movie automatically, use the following command:
send "play" to window <file name>

To make the movie automatically close when it has finished:
set closeOnFinish of window <movie name> to true

For full details of the "movie" XCMD, consult the QuickTime Tools stack. (The XCMD can also be installed from that stack to any other stack)

Further ideas

Of course, there is no reason why you have to stop there. Here are some ideas for extending he interface and making it even greater:

a. Playing sounds
How about showing a palette that has one button for stopping the sound immediately? The syntax for this is simply play stop. The palette would have to close when clicked or when the (original) sound was "done".

b. Pop-up fields
Sometimes it is more appropriate to have small shadow-style field pop up to give further information, rather than going to another card. You would have to choose another font for this kind of link (although see point d, below).
The basic syntax is:
show|hide [card|bkgnd] field <field name or number>

c. Opening or sending apple events to other applications (Now we're getting ambitious!)

The syntax for opening another application is:
open <application name>
[NB: Remember, HyperCard has no control once another application comes to the front. It is up to the user to go back to HyperCard.]

The syntax for sending an apple event to another application (including HyperCard on another Mac) is:
send "<message name>" to program [<zone>:] [<Macintosh>:] <program>

The syntax for requesting data from another application using apple events is
request "<expression>" from program [<zone>:] [<Macintosh>:] <program>
(The value that is returned gets put into it.)

d. Using special characters instead of fonts to indicate type of hyper-link (e.g. * Ý # etc...)
Perhaps you don't like the idea of all these different fonts, why not use special characters?
Check to see if "*" (or whatever) is in the clickText. If so, don't forget to remove it before using it as your hypertext value.

If you would prefer not to type the script and create the palette yourself, you can get a hold of the demonstration stack "Hyper- Card/text/media" from the BBS.

---

Footnote:

1. In fact the highly acclaimed National Gallery (London)'s MicroGallery, upon which the "Microsoft Art Gallery" CD-ROM was based, was originally created in HyperCard.