Converting a HyperCard stack to Revolution

General conversion guidelines: what will and will not transfer

For the most part, almost all aspects of a HyperCard stack will convert to Revolution with little alteration. There are a few things that are done differently in Revolution, however, which always need to be modified. Most of the differences are due to the cross-platform capabilities of Revolution that HyperCard lacks. For example, the Macintosh resource fork, while supported by Revolution on Macs, is not available on other platforms. Therefore Revolution provides alternate ways of handling color, pictures, sounds, cursors, icons, etc. For all of these, the resources are stored instead in the data fork of the stack, which all platforms recognize.

Issues which need to be addressed during conversion are:

• Menus and menu handling
• Resource fork items that Revolution does not automatically move;
• XCMD/XFCN substitutions (including addColor)
• Report printing
• Reserved word variable names
• Unquoted literal strings

In addition, the Revolution compiler is much more particular than HyperCard in some areas of syntax. Function calls must always be preceded with "the" (as in the length of myString) or used with the parenthetical syntax (i.e., length(myString)). The longer English form will not work without the preceding "the". For example, length of myString will usually error.

Menus

HyperCard's method of working with menus is incompatible with Revolution and all menu commands will need to be rewritten. For a fuller explanation of how Revolution menus work, see About Revolution Menus later in this tutorial. A large part of this tutorial involves setting up and managing Revolution menus, with a walk-through in the Adding a Menu Bar section.

XCMD/XFCN Substitutions and Resource Fork Items

Our example stack contains no XCMDs, so a brief discussion here is appropriate. When Revolution imports a HyperCard stack, the resource fork is stripped off; the most common resources are automatically moved to the data fork and all other resources are lost. In general this is preferred behavior because Revolution provides built-in commands for nearly all the features that HyperCard users commonly use externals to accomplish. The best way to address XCMDs in your converted stack is to note where they are used and substitute the native Revolution syntax to accomplish the same thing. In very rare cases, an XCMD will be necessary. If the stack will be run on a Windows machine, a matching DLL will also be needed.

The most common XCMD used in HyperCard stacks is AddColor, which provides a color overlay that HyperCard itself knows nothing about. Quite a bit of scripting is usually necessary to support color in HyperCard and colorized stacks generally have addColor calls sprinkled liberally throughout their scripts. Since color is built into Revolution, none of those scripts are necessary and, in fact, will error repeatedly in Revolution until they are removed. The best approach for handling colorized HyperCard stacks is to completely remove all addColor handlers and references from the scripts before doing the import into Revolution. If you do this, the number of compiler errors you will receive from Revolution will be substantially reduced, not to mention your frustration level.

Resources that are automatically imported and moved to the data fork during a Revolution import include button icons, sounds, and cursors. Icons are automatically assigned to the correct buttons, and sounds and cursors will work when called in scripts. The conversion of these resources is transparent.

Report printing

Revolution supports several forms of the print card command and ships with a revPrintField handler that will print the contents of a field. The use of both of these is demonstrated in the tutorial. However, Revolution does not contain HyperCard's report engine. Scripts that use report templates or rely on print stack menu commands will need to be rewritten. While report printing is beyond the scope of this tutorial, there are scripted methods of accomplishing it, though none are as easy as HyperCard's built-in report generator. This tutorial contains a very simple script, which can be found in the Records Cards section, which duplicates one of HyperCard's Print Stack options.

Reserved word variable names
Unquoted literal strings

Unquoted literal strings will fail much of the time, though there are minor exceptions. Good HyperCard programming demands that literals are always quoted; if you are not yet in the habit of doing so, start now. Quoted literals execute much faster in HyperCard anyway, and they are required in Revolution.

While reserved words (words which are part of the language syntax) can be used as variable names in HyperCard, they are disallowed in Revolution. The command:

put field "last name" into name

will work in HyperCard but will error in Revolution because name is a reserved word. It is best to develop the habit of customizing your variable names so that they will never be confused with reserved words, either now or in future versions of either program. HyperActive Software uses "the" before variable names for easy readability, i.e., theName. Many programers prefer a simple "t": tName. Any convention will do, as long as it guarantees a unique variable name. The best bet is to choose a convention that works for you and use it consistently.

A good guideline for constructing efficient variable names can be found (among other excellent scripting style information) at Fourth World's Scripting Style Guide.

This tutorial does not specifically deal with unquoted literals or reserved word variable names because our example stack does not contain any instances which would interfere with our conversion. But when converting your own stacks, you should look for and correct these items within HyperCard before importing your stack to Revolution. You will receive fewer errors after the import if you do.

Saving stacks

Revolution, like most other applications, does not automatically save your work the way HyperCard does. For those who are used to HyperCard's behavior, this can be disasterous. It is easy to forget to save as you go, since Revolution resembles HyperCard in many ways and old habits are hard to break. This tutorial reminds you to save periodically. It is important to remember that the users of your stacks will also need to save their work, so don't forget to include a Save menu item if you are building custom menus. If a stack is not saved first, any data the user enters into a stack will disappear when Revolution quits.

Up to top | Converting Stacks to Revolution - TOC | Next Page