HyperActive Software

Home What's New Who We Are What We Do Solutions Resources

We make software for humans. Custom Mac, Windows, iOS and Android solutions in HyperCard, MetaCard, and RunRev LiveCode


Converting a HyperCard stack to LiveCode

Make the About card into an independent splash screen

LiveCode Substacks

LiveCode is not limited to one window per file like HyperCard is. A single LiveCode file can contain any number of stacks, each in its own window. In other words, a LiveCode stack can have multiple windows. SuperCard users are familiar with this concept.

Each window is actually a stack in its own right, with its own set of cards, objects, and message hierarchy. One stack, usually the first one you create, is the mainstack and all other stacks you attach to the mainstack are substacks. The message hierarchy in a substack follows the normal chain, but once messages have passed through the script of the substack, they also pass through the stack script of the mainstack, much as HyperCard stack messages always pass through the Home stack before arriving at HyperCard. (If the mainstack is being run in the development environment, messages consequently also pass through LiveCode's Home stack before arriving at LiveCode.)

Substacks can be created to represent almost any windowed element -- dialog boxes, modal windows, palettes, etc. -- and attached to the mainstack so that they are stored in the same file on disk. Unlike HyperCard, LiveCode does not need XCMDs to create custom dialogs.

We will create a substack that functions as a modal About box, which will replace the About card in the Tech Support TimeSaver stack, and then script the menu to display it.

Create the substack

If the Tech Support TimeSaver stack is frontmost, click on one of LiveCode's native stacks or palettes to bring LiveCode's menus into view. Choose "New Substack of TSTS" from the File menu. This sets the new stack as a substack of the Tech Support TimeSaver stack; the new stack will be stored in the same file with it.

Open the Stack Properties palette, set the name of the stack to "About" and set the label to "About Tech Support TimeSaver". Close the dialog.

Drag the size box of the new stack to approximately the same size as the graphic on the About card. Click on the main TSTS stack to bring it to the front. Choose the edit tool and hold down the shift key to select both the scrolling field and the OK button. Copy them. Bring the new stack to the front and paste them onto the card.

Adjust the position of the objects on the About stack and resize the stack if necessary to approximate the original graphic on card 2 of the main TSTS stack.

Let's add some color to the About stack. You can use your imagination with the Color Palette if you like, or import color images. For now, we will just set the background color. The background color can be any RGB triplet, or one of LiveCode's pre-defined color names. We'll just type this into the message box:

set the backgroundColor of this stack to "lavender"

Until you save the main TSTS stack, the new About stack exists only in memory. If you were to quit LiveCode right now, you would lose the About stack. Save the TSTS stack to disk now. Since substacks are part of the same file on disk as the main stack, saving any stack in the set saves all of them.

Script the substack

Our About stack isn't going to do too much so we don't need many scripts. We do want it to display over the main stack when it appears, so open the About stack script and set it to this:

on preOpenStack
  set the loc of me to the loc of stack (the mainstack of this stack)
end preOpenStack
We also need to change the OK button so that it hides the About stack when it is clicked. Change the OK button script to this:
on mouseUp
  close this stack
end mouseUp
Save the file to disk once again and close the About stack.

Revise the menu script

All that's left is to rescript the Help menu button. Open its script. Under the "about" case, change the go cd "About Card" line in the button script to:

modal "about"
This instructs LiveCode to open the "About" stack window as a modal window. The user will not be able to do other things until the window is closed. This is fairly standard behavior for about boxes, but if you wanted to, you could also use the "modeless" command instead to open the About stack in a dialog window that will be sent behind other windows if the user clicks elsewhere.

As an optional exercise, change the Help button contents to say "About TSTS..." instead of just "About..." as it is now. You'll have to change the Help button script to match.

Debugging the script

The first thing that happens when you try the "About" menu item is an error dialog claiming that LiveCode can't find the background. Since our About box is modal, you will have to click the OK button to close it before you can see the script execution error dialog. If you click the Script button in the dialog, it takes you to the openStack handler of the main stack.

The error is a result of the message hierarchy, which is sending an openStack message to our About stack. Since there is no handler to trap the message, the message continues on to the main stack. The openStack handler in the main stack references a "records" background, but the current card is in the About stack which has no such background. That's why it errors.

There are a couple of ways to fix this. One way would be to move the openStack handler in the main stack to the main stack's first card. Like HyperCard, LiveCode always goes to the first card when a stack opens, so the openStack handler would always run. Another way, which we will use, is to put a trap in the About stack so that the message doesn't go any further.

One way to edit the About stack, since it is invisible right now, is to use the message box. You can enter:

toplevel "about"
The toplevel command tells LiveCode to display the stack as an editable document window, as it was when we created it. Then you can open its stack script by typing Cmd-Shift-S. Or you can just use the message box to open the script directly:
edit script of stack "about"
In the About stack script, enter this trap:
on openStack
end openStack
Close and save the script. Try the About menu item again.

Now that the About stack is done, you can delete card 2 of the main stack. You will also need to change the script of the "About" button on card 1. The revised script should be:

on mouseUp
  modal "About"
end mouseUp
The script of the Records background also needs a change now. It calculates the number of the record currently being viewed. The last line of the handler needs adjustment; you'll want to change the 2 to a 1 here.
put (number of this card - 1) \
    && "of" && (number of cards of this bkgnd) into bkgnd field "Card#"
The last change is in the Sort button of the Records background. It's script calculates the card's new numerical position in the stack by adding the number of non-record cards to the current sort index. Originally there were two cards before the records background, now there is only one. In the script of the Sort button, change the 3 to a 2:
on sortBgCards
  repeat with x = 1 to the number of cds in this bg
    put (line 1 of fld "product name" of cd x of this bg) \
        & numToChar(3) & (the short id of cd x of this bg) & \
        return after theList
  end repeat
  set the itemDelimiter to numToChar(3)
  sort lines of theList by item 1 of each
  put 2 into i
  repeat for each line l in theList
    set the number of cd ID (item 2 of l) to i
    add 1 to i
  end repeat
end sortBgCards

Optional exercise: Make the Help card into a substack too.

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