Volume Number: 10
Issue Number: 3
Column Tag: Tools Of The Trade

Hypercard 2.2

by Paul Foraker

Apple's taken HyperCard back from Claris. Here's what they've done with it

In 1987, when Apple Computer introduced HyperCard at MacWorld Boston, most experts thought that users would primarily 'play' stacks, not script their own. Turned out that a majority of HyperCard users became scripters. Furthermore, to the surprise of HyperCard's creator, Bill Atkinson, and the rest of the HyperCard Team, a very large number of scripters were in the business and education markets, not the home market. With the introduction of HyperCard 2.2, Apple Computer makes a small but significant step toward acknowledging its technical market, and this version represents a significant upgrade to perhaps the most popular development environment on the Macintosh.

There are actually two HyperCards: the full application and the unscriptable HyperCard Player. In the beginning, when there was only one, the full version of HyperCard shipped in the box with every Macintosh. When Claris took over the application a few years ago, the HyperCard Player was introduced, replacing the complete application in the CPU box, and a "HyperCard Developer's Kit" was sold separately. With version 2.2, Apple continues this scheme, although without calling the full version a "developer's kit". In the United States, every new Macintosh will have the HyperCard Player on its hard drive. The About box in the Player mentions the full version.

(Claris also tried an interim scheme of shipping a crippled, low user-level, Home stack, which users could override by typing 'magic' in the message box. There was some confusion between this version and the Player, that had people trying unsuccessfully to type 'magic' in the message box of the Player. The magic in HyperCard 2.2 is all plain and visible.)

What's in the box?

Weighing nearly as much as the original 128K Macintosh, the HyperCard 2.2 product box contains the full development version, AppleScript 1.1 Runtime, and for a limited time, Motion Works' ADDMotion II, for a total of eleven 800K diskettes. The documentation has been updated and includes a revised Script Language Guide and HyperCard Reference Manual. Serious AppleScript developers will want to purchase the AppleScript 1.1 package separately, because the bundled version does not contain the AppleScript Language Guide. On-line documentation includes the HyperCard Help, HyperTalk Reference, and the HyperCard AppleScript Reference stacks. Balloon help has been implemented extensively.

An installer places a 10+ MB "HyperCard 2.2" folder on the designated hard drive. Users can customize the installation to leave out AppleScript and ADDMotion.

What's new?

Most of the differences between HyperCard 2.1 and 2.2 can be summarized under five categories: (1) OSA support, (2) color, (3) stand-alone applications, (4) enhancements to HyperCard's feature set, and (5) improvements to HyperTalk, HyperCard's built-in scripting language. In addition, WorldScript support has been improved such that, with the Japanese language kit installed, users can have both Kanji and Roman text in the same field.

The file format for HyperCard stacks did not change with this version, so HyperCard 2.1 can open and run stacks built in 2.2 (except, of course, the new features). Further, HyperCard 2.2 can open and run 2.1 stacks without any conversion.

OSA Support

HyperCard users tend to think of HyperCard and HyperTalk as inseparable. In version 2.2, HyperTalk is not the only language that can be used in HyperCard scripts. Any OSA-compliant scripting language (such as AppleScript, UserScript, QuicKeys) can be used in the scripts of HyperCard objects. A new popup menu in the script editor lists the available languages on the user's computer.

HyperCard 2.2 is an AppleScript-scriptable and -attachable application, though it is not recordable. HyperCard stacks can be controlled by other applications, and, perhaps more importantly, HyperCard can provide an interface to other scriptable applications. As programmer Kevin Calhoun put it, "any scriptable application can be an XCMD for HyperCard".

HyperCard 2.2 supports the Core and Required suites for Apple Events, and provides its own HyperCard suite. About 90% of HyperCard's commands, functions and features have been implemented in the HyperCard suite. Missing commands can be executed by using the "do script" or "evaluate" commands, so virtually all of HyperCard is available through AppleScript.

Message passing between AppleScript and HyperTalk scripts is fully implemented, so that HyperTalk handlers can call AppleScript functions elsewhere in the hierarchy and vice versa.

To demonstrate the effectiveness of the AppleScript implementation in HyperCard, the reviewer constructed a simple "mail" stack. The stack provides fields for To, CC:, Subject, and Text. A Send button uses AppleScript to launch Aladdin System's scriptable terminal communications program, SITComm. SITComm dials The WELL (a multi-user conferencing system in Northern California) and sends the mail, logging off when done. When finished, the stack saves the outgoing message in a text file selected via a popup button, and checks a "Sent" checkbox. From start to finish, this stack was created and saved as a stand-alone application in about an hour.

Color

In HyperCard 2.2, color is supplied via a Color Tools stack and an XCMD, "addColor". An installer in the Color Tools stack adds a script to the user's Home stack and a Color menu to the menu bar. When the user selects Open Color Tools from the Color menu, HyperCard installs the addColor XCMD into the current stack, along with the resources necessary for managing color. By selecting colors from a 256 color palette, users can color buttons, fields, and rectangles. Color and gray scale PICTs can be imported from either the resource fork of the stack (PICT resource) or from a file on disk (PICT file). Other picture formats (for example, TIFF) are not supported. About twenty visual effects ("transitions") specific to color are provided. These are in addition to and different from HyperCard's black and white visual effects.

The color solution provided in HyperCard 2.2 is not full color support. There are no color painting tools. The color palette can not be customized. There is no support for color printing. In addition, colorized stacks do not display on black and white monitors. This last is a serious shortcoming. Commercial developers will need to do some fancy scripting to have their stacks usable on both color and black & white machines.

A third party addition to the Color Tools stack is already shipping from Heizer. Called InColor, it provides a very useful superset of color manipulation tools based on the addColor XCMD.

The addColor XCMD demonstrates a problem with 32-bit QuickDraw that developers will have to work around. When the addColor XCMD gets loaded and color is produced on the card window, 32-bit QuickDraw locks down a handle low in the HyperCard heap. If the user then opens a large-windowed stack that has not yet been opened in that session, the stack will open in a small window and there will not be enough memory for painting tools. To most users, this will appear to be a bug in HyperCard. The work around is to open any large stacks first. Hopefully, Apple will soon fix this in a future version of QuickDraw.

Stand-Alone Applications

In earlier versions of HyperCard, it was possible to create a stack that ran as a stand-alone application. This was accomplished by an XCMD, separately licensed from Claris, that embedded the HyperCard Player in a stack.

In HyperCard 2.2, this capability is built-in. The Save a Copy dialog presents a popup menu listing the possible file types, as shown below.

The file types that ship with this version are "stack", "custom file type", and "application". Third party developers can provide the ability to save-as other file types (for example, a text file containing all the text of a stack). There is no license fee to Apple for distributing stand-alone applications.

When the user saves a stack as an application, an intermediate dialog allows the designation of custom file type and creator.

Figure 3 Developers can specify the file type, creator and version info in this dialog.

Since stacks can be saved as standalones, with custom file type and creator, Apple has also provided the ability to save a stack as a file type other than 'STAK', using the Custom File Type option. A suite of stacks, therefore, can be bundled into a stand-alone application and its files, complete with custom icons.

With customized menus, a stand-alone application can take on its own look. Saving a stack as a stand-alone adds about 780K to the size of the stack. Developers can remove unused resources to reduce this size.

Since a stand-alone application contains all of HyperCard except the script editing environment, standalones are AppleScriptable applications. Developers will be able to build special-purpose applications and control them from other applications, including HyperCard itself.

New and Enhanced Features

• Button families. Earlier HyperCard versions supported a button type called Radio Button, but a cluster of mutually exclusive buttons required scripting. A new "family" property removes the need to write scripts. A button family is a group of two or more buttons, only one of which may be selected at once. When the user clicks one button of the family, all the others automatically unhighlight. Up to 15 families can be defined for each card, plus an additional 15 families for each background. Families are designated either in a script (set the family of button 1 to 15) or by choosing a number from the Family pop up menu in the Button Info dialog (shown below).
  
  Figure 4 The new movable modal Button Info dialog and its Family popup menu. Note the preview area for the button.

• List Fields. Another oft-scripted featured is the provision of a clickable list. In previous versions, developers had to write a script to select the line the user clicked on, get the contents of the line, then execute whatever function the user selected. HyperCard 2.2 handles highlighting the line automatically. A new field property, autoSelect, determines whether a click on a locked field will behave like a clickable menu. A Multiple Lines property determines whether the user can extend the highlighted lines to select more than one line. One significant omission is HyperCard's inability to select discontiguous lines.

  Since the list field is a field behavior and not a field type, there is no "List Field" checkbox. To create a list field, the user sets the following properties to true: lockText, autoSelect, and dontWrap.

• Part Number. In HyperCard 2.2, every button and field has a part number, which represents its ordinal position in the background or card layer. This property will save developers much time in layering objects. Only a script can change a part's number. The part number field in the info dialog is not editable.
• Popup Button. Before to this version, only an external command or some very fancy scripting could generate a popup menu. Now a new button type provides the correct functionality automatically. The "contents" of the popup menu button determine the items in the menu. HyperCard 2.2 makes buttons containers, just like fields. A new Contents button in the Button Info dialog provides access to the items. Unfortunately, the Contents window has no scrollbar. Users must click and drag to get to text outside the visible rectangle. Since a button may contain up to 30K of text, this will annoy some users.

  
  Figure 5 The new button contents dialog holds up to 30K of text, but has not scroll bar.

  A new property, titleWidth, gets and sets the width of the title area of a popup button. The selectedText and selectedLine properties apply to popup buttons as well as to list fields, for determining the selected item.

• New button types. In addition to the Popup Button, there are three new button types: standard, default and oval. The original drop-shadow button in earlier versions of HyperCard drew criticism for deviating from the standard interface for buttons. The new Standard button eliminates the drop shadow. To complement the Standard button, HyperCard provides a Default (double-bordered) button style. The Default button, however, does not trap the Return or Enter keys. Developers must script the functionality by trapping the returnKey and enterKey messages.

  The Oval button type allows circular or oval graphics to behave like buttons, without requiring the developer to place multiple small buttons overlapped to fit the area. The "hot" area in the Oval button is (correctly) inside the oval, not the rectangle, and when colorized, the color applies only to the oval area.

  
  Figure 6 The color in an Oval button fills the oval, not the bounding rectangle.

  The Oval button type does not produce polygon buttons. Developers still need to buy an add-on like PolyTools from Heizer to meet that need.

• Enabled property of buttons. Buttons can now be disabled. When disabled, their text or icon dims and the button ignores mouse events.
• Printing enhancements. Apple made several minor improvements to report printing. In 2.2, some hidden features present in 2.1 are now explicit, and they added a Save button so users can save changes as they work on report templates. The Report Item Info dialog box shown below now has an Invert option (white text on black field) and a Framing option for drawing a line along the sides.

  
  Figure 7 The print items dialog includes an inversion choice and frame checkboxes.

  It is still not possible to produce graphics in reports. Printing has always been a weak spot in HyperCard, which has resulted in an excellent market opportunity for add-ons like Reports from Nine to Five Software, and FillForm from Berumen & Associates. With these extensions, report printing from HyperCard rivals that of any sophisticated database program.

• Other enhancements. There are several other minor enhancements that provide useful additions to the program. These include balloon help for most of the commands and features; up to 16 stacks in use at once (resource files in the message hierarchy); a new default size for PowerBook screens; undo for buttons and fields; movable modal dialogs for the object info dialogs; and a new "push" visual effect (different from the color transitions).

Although not documented, using AppleScript for stack scripts limits the number of stacks in use.

Enhancements to HyperTalk

The New Features stack lists 35 new or enhanced features for HyperTalk, most of which fit into four categories: commands, functions, properties and messages. Here are the major ones:

• Command changes. There is one new command, copy template, which allows a script to copy a printing report template from one stack to another. Modified existing commands include:
  • close: a script can now close a desk accessory
  • convert: a "from format" option has been added
  • delete: a script can delete a part (button or field)
  • {disable | enable}: buttons can be disabled or enabled
  • do: a script can "do" a command "as" any resident scriptingLanguage (for example: do field 1 as QuicKeys)
  • doMenu: modifier keys can be specified; for example, doMenu "Stack Info..." with shiftKey
  • find: the find command now supports international characters (diphthongs and diacritical marks)
  • {lock | unlock}: lock recent, unlock recent are now allowed
  • open: the parameters of the open command are now available to handlers
  • put: since buttons are now containers, put button 1 into field "Address" is now a legal expression
  • {read | write}: these commands now support a negative number with the "at" preposition; for example, "write theText to file theFile at -100" writes the variable to the file at 100 characters from the end of the file
  • sort: sorting by an arbitrary sort key is now allowed; for example, sort lines of container by last word of each

  Error handling for file i/o changed. Commands that fail to read from or write to a text file no longer abort the script, but return an error message in the result. Further, XCMDs no longer cause an error if they send a callback that doesn't get handled by a script (and therefore, do not close open text files).

  HyperCard now creates text files of type 'ttxt' (Teach Text) instead of 'MACA' (MacWrite). Developers can specify a different word processor by modifying 'STR ' resource #128 with ResEdit.

• Function Changes. These include three new functions: destination(), selectedButton(), and sum(); and three enhanced functions: diskSpace(), number(), selectedLine(), and selectedText().

  The new function, destination(), returns the full path to the stack to which HyperCard is going next. This will be very useful for managing suites of stacks that share common menus. If the destination returns a stack outside the suite, for example, the script could delete the custom menus.

  selectedButton() returns the highlighted member of a button family.

  sum() adds up a comma-delimited list of numbers.

  diskSpace() now allows an optional parameter to specify the volume. number() can return the number of parts (card or background). selectedLine() and selectedText() now handle list fields and popup buttons.

• Property Changes. There are nine new properties: the autoSelect, the dialingVolume, the environment, the family, the multipleLines, the partNumber, the scriptingLanguage, the titleWidth, and the zoomed.

  The autoSelect, family, multipleLines, partNumber and titleWidth properties were mentioned earlier. Quadra users will welcome the dialingVolume property. It allows the scripter to set and get the volume used by the dial command. The environment property is a read-only property that returns either "development" (for the full HyperCard application) or "player" for a stand-alone or the HyperCard Player. The scriptingLanguage property can be used to get and set the scripting language used by the message box or an object (card, button, etc.). The default scripting language is HyperTalk.

  A recent message on AOL asked how to center a card window on a monitor. In previous versions, it was necessary to script the location by calculating it from the rect of the screen. In HyperCard 2.2, the zoomed property centers the window on the current display.

• Message Changes. Apple has provided a new message, mouseDoubleClick. This message is "...sent to a button, field, or card when the downstroke of a second click follows the downstroke of a previous click within the double-click interval set in the Mouse control panel and the second click occurs within four pixels of the first and the second click occurs within the same object as the first."

The "there is" operator received several welcome enhancements, including the ability to determine in a script whether there is a card or background picture, or whether there is a disk by a specific name.

Script Editing and Debugging

In addition to the scripting language popup menu added to the script editor window, a new Check Syntax menu is available for languages other than HyperTalk. With AppleScript, this menu checks the syntax, and if it passes, copies the script properly indented to the window. Scripts still do not support text styles.

No significant changes were made to the debugging environment. As in previous 2.x versions, users can step and trace through the execution of scripts, and use the Watchers to track variables and messages. These tools are not available, however, when debugging AppleScript scripts. For that, developers will need to copy their scripts to AppleScript's Script Editor and debug them from there. A third party development opportunity exists to provide such an editor in HyperCard.

Performance

HyperCard 2.2 is no faster than earlier versions. As one might expect, the addition of color and AppleScript will slow down a stack's performance. However, as many developers are realizing, HyperCard, with the addition of the appropriate XCMDs, can hold its own with the major database programs. At MacWorld in January this year, Nine to Five Software distributed the results of a bench mark test showing HyperCard outrunning FileMaker Pro by a factor of 20 in one test. With external add-ons and HyperCard's rapid development cycle, expect to see more businesses developing internal solutions with HyperCard 2.2.

Support

There are two levels of technical support available. New users can call 1-800-SOS-APPL and get help installing and launching the application. For advanced scripting help, Apple provides fee-based support. Developers can buy one of three scripting support products by calling 1-800-950-2442. Help for a single incident costs $55.00. Five incidents for 1 year costs $249.00, and unlimited incidents for 1 year is available for $399.00.

Scripting support includes the following assistance:

• Modifying Stacks
• Writing Stacks
• Command syntax and use
• Debugging Stacks
• The current and immediately preceding version (2.2 and 2.1)

What is not included?

• Writing and Using XCMDs
• Stack concept and design
• Project management or consultation

Send bug reports and feature requests to AppleLink address HYPERBUG$.

Pricing and Availability

HyperCard 2.2 is available now at a suggested retail price of $249. Developers can purchase from APDA at a significant discount ($99.00 at this writing). The upgrade price from version 2.1 (for registered Claris owners) is $89.00.