Converting from SuperCard to Revolution

This article is for new Revolution developers who have experience with SuperCard and the SuperTalk language, and who want to learn how to leverage their SuperCard knowledge and existing projects to get a running start in Revolution.

SuperCard is a HyperCard clone product first developed by Silicon Beach, then sold along with the company to Aldus. After Aldus was acquired by Adobe, the product was taken on by Allegiant, which included members of the original SuperCard team. Allegiant then sold out to a company known as IncWell. IncWell shipped the last major update to its SuperCard Roadster technology, Windows plugin and the first and last Japanese version of SuperCard.

Contents:
From SuperCard to Revolution
Converting SuperCard Projects (Includes Supercard to Revolution Converter download)
Tips and Gotchas

From SuperCard to Revolution

As an experienced SuperCard developer, you’ll find the transition to using Revolution straightforward and easy. Just as you did in SuperCard, you’ll create objects in a stack window (which can have one or more cards). You write handlers in the Revolution language, whose syntax is very similar to SuperTalk.

Revolution supports all the object types SuperCard does, plus more: buttons, fields, images (bitmaps you can either paint in or display a file in), players, graphics, and scrollbars. QuickTime and QuickTime VR movies are displayed in the built-in player object, which is a full peer of other object types. You use the Object Properties palette to change the appearance and behavior of these objects and to edit scripts.

There are a few conceptual differences to be aware of.

Stacks, projects, and windows

In SuperCard, each window is an object, and windows are contained in a project file. In Revolution, each window is still an object (called a stack), but there is no project object. Instead, each stack file contains one or more stacks, of which one is the main stack and any others are substacks. Like a project, the main stack is in the message path of all objects in the substacks. Unlike a project, the main stack is a stack in itself and has a window of its own.

The main stack opens by default when you open a stack file. Revolution applications usually use the main stack as either a splash screen or the main control window of the application.

Backgrounds and Groups

In SuperCard, you place objects in the background layer, and each card with that background displays those objects behind the card objects.

In Revolution, you use the Group menu item (or the group command) to combine any set of selected objects into a group. Unlike SuperCard backgrounds, groups can be added to any card in the stack, and a card can contain more than one group. (And unlike SuperCard graphics groups, Revolution groups can contain any object types, and grouped objects retain their scripts.) Groups can be interleaved with, or in front of, non-grouped objects.

When you create a new card, any groups on the current card are placed on the new card, just like the way SuperCard adds a new card to the current background. However, it’s important to remember that groups are not backgrounds. In SuperCard, every card belongs to a background. In Revolution, however, cards can exist without having any groups, and the groups belong to the cards they’re on rather than vice versa.

Menus

In Revolution, all menus (including menus in the menu bar) are implemented as buttons.

To create a menu bar, you first create a button for each menu, setting the button’s menuMode to pulldown. Then you combine those menus into a group, placed at the top of the stack window. (This is the normal location for menu bars on Unix and Windows systems.)

If you set the stack’s menubar property to the name of the group, Revolution displays the group’s menus as a normal MacOS menu bar and changes the window size to hide the buttons. This means that the menu bar will appear in the proper place for each platform: on MacOS systems, the menus appear at the top of the screen in the menu bar, while on Unix and Windows systems they appear at the top of the stack window, in accordance with user-interface standards for those platforms.

The Development Environment

Revolution’s development environment is similar to SuperCard’s. There is a message box (although the Revolution message box can execute multiple-line structures as well as one-line statements) and a tool palette for working with objects.

In SuperCard’s Project Editor, you must switch between Design Mode and Run Mode before testing your scripts. Revolution’s development environment is modeless: you can test a handler as soon as it’s written, and use your stack within the development environment. To test your stack in a ‘clean’ environment without any of Revolution’s own menus, palettes, or other parts of the development environment, use the ‘Suspend Revolution UI’ item in the Development menu. To prevent normal messages from being sent to your stack during editing, use the ‘Suppress Messages’ item in the Development menu.

The development environment—menus, palettes, dialog boxes, and all—is built entirely in Revolution. This not only demonstrates the power of the Revolution engine, it means that as you advance, there is the possibility of exploring the Revolution user interface and customizing it for your needs.

Converting SuperCard Projects

The converter consists of a SuperCard project and a Revolution stack. Documentation is included with the converter program.

Click here to download the latest version of the SuperCard to Revolution Converter (version 1.3.3B8). The Supercard to Revolution Converter only supports projects created in versions 3.0 and 3.6 of SuperCard.

The process works like this:

1. Open the ‘SuperCard -> SIF Exporter’ in SuperCard and export your project. The Exporter creates a set of text and image files.
2. Open the ‘SIF to Rev importer.rev’ stack in Revolution and import your exported files. The Importer creates a Revolution stack file from the text and image files.

Each window of your SuperCard project becomes a stack in the Revolution stack file that is created. Backgrounds in your project are converted to Revolution groups. Names and most other object properties are retained during the conversion.

The project script is placed in the script of a substack called ‘Directory of project name’. To place this script into the message path, paste it into the script of the main stack.

All the menus from the project are placed in a separate stack. If your application will be made available for Unix or Windows, this stack will become a separate window containing the menu bar on those systems. You will need to decide whether your application design makes more sense with this detached menu bar, or whether the menus should appear inside your stack windows.

For most projects, the conversion process is straightforward. Following these guidelines will help ensure a smooth conversion.

Convert SuperCard Projects under Mac OS X

The ‘siftostk’ stack can be used to complete the second stage of the conversion on any platform Revolution supports. However, it is recommended that you run it on a MacOS system, particularly if your project contains special characters such as accented letters. The resulting stack file can then be used on any platform.
Remove quotes from object names:

Make sure the double quote character (") does not appear in any object names in your project before you convert it.

Un-nest Nested Groups

The converter does not reliably handle nested groups of graphics, so if your project has groups that contain other groups, re-group them so they are one level deep before converting. You can nest groups in Revolution, so after the conversion is complete, you can restore the nesting if you wish.
Replace incompatible terminology in scripts:

A few common SuperTalk terms have different equivalents in Revolution. (See Terminology Changes, below.) The converter does not alter your scripts, so you will need to make these changes by hand after converting.

Tips and Gotchas

Revolution has a high level of compatibility with SuperCard, and almost all your knowledge will translate easily. However, there are a few incompatibilities and areas where Revolution offers a different method of doing things. Here are the most common gotchas and some useful tips.

Custom properties instead of user properties

Revolution custom properties can hold any data you want to place in them, are saved with the stack, can be associated with any object, and are used in handlers just like built-in properties. Unlike SuperCard’s user properties, custom properties do not have to be defined before use. Simply setting the custom property creates it. Revolution also allows each object to have several sets of custom properties, which you can swap in and out as needed.

Overriding Built-in Commands and Functions

In SuperCard, commands and functions pass through the message path, so a handler with the same name as a built-in command or function overrides its normal behavior.

In Revolution, built-in commands and functions are executed immediately rather than passing through the message path, so a handler with the same name as a built-in command or function will never be executed.

Explicit Save

SuperCard saves changes automatically. Revolution uses the more usual method of requiring the user to save changes explicitly. (You can also write a closeCard handler to save the current stack automatically when you go to another card.)

Everything in Memory

When you open a stack file in Revolution, all its stacks are loaded into memory and kept resident until you purge the file. (Use the destroyStack property to remove files automatically from memory when you close them.) This makes for much faster access, since stacks are pre-loaded in memory and Revolution doesn’t need to access the disk when you go to another card.

This also means stack files cannot be too large to fit into memory. If you have a large collection of data in your stack, you may want to split it into multiple stack files, or keep media, such as pictures, videos, and sounds, in external files and display these items in referenced controls. (Files in referenced controls are loaded into memory only when you go to the card the control is on.)

Dates, times, and the start of the Eon

The MacOS date routines (and therefore SuperCard) use midnight, January 1st, 1904 as the ‘beginning of time’. The seconds function counts from this moment. However, since Revolution is cross-platform, it doesn’t use the MacOS-specific date. Instead, time begins at midnight, January 1st, 1970 GMT. This will affect your stacks if you store or manipulate the value of the seconds function.

The ticks function in Revolution goes back to the start of the eon, not to the last time the system started up.

The date and time functions and the convert command always use the U.S. format for dates and times.

Using send instead of idle handlers

At times you will need to execute one or more commands periodically. In SuperCard, it is common practice to place such commands in an idle handler. In Revolution, you can instead use the send command to send a message at a specified future time. This means you can place the commands to be executed in a handler, and at the end of that handler, send a message to execute it again after the delay you specify. This example handler beeps once per second:

on annoyUser
beep
send "annoyUser" to me in 1 second
end annoyUser

This approach offers greater efficiency, since Revolution does not need to continually execute an if/then statement in an idle handler to determine whether enough time has passed.
Polling the mouse position:

When you need to monitor the mouse’s position, it is usual in SuperCard to use a mouseWithin handler that executes continually while the mouse pointer is within the object. In Revolution, it is more efficient to use a mouseMove handler in the object’s script to track the mouse’s motions while the pointer is within the object.

Window Layers

In most applications, the active window holds the current document, and menu commands operate on the active window. In Revolution, because you can open stacks as palettes and dialog boxes, this is not necessarily the case and occasionally the active window is not the frontmost stack. Use the topStack function (similar to SuperTalk’s ‘topWindow’ function) and defaultStack property to control which stack is the active window.

Pathnames

In SuperCard, file pathnames use the MacOS convention of separating levels with a colon, and a file path might look like this: ‘Hard Disk:Folder:File’. Revolution uses the Unix style for pathnames, which uses slashes instead of colons, on all platforms to simplify writing cross-platform handlers. The same file path, written Revolution-style, looks like this: ‘/Hard Disk/Folder/File’. Revolution translates slashes to colons in pathnames, so if you have a file called ‘And/Or’, in a Revolution pathname it becomes ‘And:Or’.

Absolute paths begin with a slash and relative paths begin without a slash. The folder that contains the current folder is indicated in a relative path by ‘../’. For example, if the current folder is ‘Folder 1’, the path to ‘Folder 2’ on the same level is written ‘../Folder 2/’.
Visual effect quoting:

Revolutiont’s visual effect command does not allow the visual effect name to be enclosed in quotes. The statement visual effect "barn door" does not work in Revolution, though it works in SuperCard.

Closing Fields

Pressing the Enter key doesn’t automatically close the current field. To have the Enter key close a field, insert an enterInField message into an object in the field’s message path:

on enterInField
select empty -- closes the field
end enterInField
Window appearance properties:

In SuperCard, you use a number of properties to control a window’s appearance. In Revolution, you set the stack’s decorations property to control its title bar, zoom box, and collapse box).

Terminology Changes

Most SuperTalk terms can be used unchanged in Revolution. The most commonly-used exceptions are:

* ‘backSize’ property: Use the rectangle, width, and height properties of the group instead.
* ‘clickList’ message: Use mouseDown and mouseUp instead.
* ‘closeProject’ message: Use closeStack instead.
* ‘isNumber’ function: Use the is a operator instead.
* ‘itemSelect’ message: Use menuPick instead.
* ‘keyStroke’ and ‘keyInField’ messages: Use keyDown instead.
* ‘loc of the cursor’: Use the screenMouseLoc property instead.
* ‘openProject’ message: Use openStack instead.
* ‘penBack’ property: Use the borderColor property instead.
* ‘setWindow’ command: Use the defaultStack property instead.
* ‘textHeightSum’ property: Use the formattedHeight property instead.

Graphics and Images

In Revolution, graphics and images are two distinct object types. A graphic is a resizeable shape, while an image holds a bitmapped picture. You cannot put bitmapped data into a graphic (although you can set a graphic to display a bitmapped patten.