Converting a HyperCard stack to LiveCode

Records Cards

Click the "Records" tab to go to the Records cards.

Adjusting the fields for the default textfont

LiveCode substitutes Helvetica for fields that displayed Geneva in HyperCard. Helvetica translates well across all platforms and looks similar on Macs, Windows, and UNIX. (LiveCode's Distribution Builder tool can set the textfont in fields back to Geneva on Macs, Lucida on OS X, and to other platform-appropriate fonts when a standalone is built. However, for our tutorial, we'll use Helvetica.)

The change in font, however, requires us to adjust the field heights slightly.

The fields are all in the background layer, so make sure "Select Grouped Controls" in the Edit menu is checked. This setting allows you to edit controls that are in a background (i.e., a group) without going into background editing mode.

Choose the edit tool from the Tools palette. Click on each field in turn, grab the handle at the top center of the field, and drag upward a few pixels until the full height of the text comes into view and the grid line is visible. If necessary, grab the field in the middle and re-align it even with its label.

Fixing the Product Name field script

We need to fix the script of the "Product Name" field, which contains menu commands that will error in LiveCode. Position the mouse over the field and hold down Option-Command to open its script. Change the script to this:

on closeField
  makeIndexMenu
  pass closeField
end closeField

In HyperCard, this script originally replaced only the item in the Index menu that had changed. This is an efficient method that would also work in LiveCode, though LiveCode's speed is so much faster than HyperCard's that it isn't always necessary except in much larger stacks. Re-creating the entire index is less efficient but works better for this tutorial, since we will be removing the entire Index button later on. Calling makeIndexMenu directly in this case allows us to change the structure of the stack later without having to rewrite this script a second time.

Fixing the Sort button

With the edit tool still selected, open the script of the Sort button. This script contains a variation of the sort command that is unsupported in LiveCode:

    sort cards of bg "Records" by bg field "Product Name"

LiveCode does support the sort command and can sort containers in all the usual HyperCard ways. It can also sort the cards of an entire stack by any criteria. However, it does not sort cards of a single background. This feature is scheduled to be added in an upcoming release of the engine. For now, we will write our own workaround as a substitute.

Replace the sort cards of this bg line of the script with the single command

sortBgCards

Below the existing mouseUp handler, add this handler:

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 3 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

This script will sort the cards in the background just as HyperCard would, though it assumes the cards are contiguous in the stack, which in our sample stack is the case.

Several things are worth noting about this script:

Line continuation characters: The line continuation character in LiveCode is the backslash (\). The standard HyperCard line continuation character, created by typing Option-L, will work in LiveCode running on Macs but not on other platforms. It is a good habit to use LiveCode's notation rather than HyperCard's in your scripts if you want your stack to run on platforms other than Macintosh. LiveCode automatically replaces HyperCard's line continuation characters with a backslash in existing scripts when it converts the stack.

Item Delimiters: Another thing to note is that LiveCode automatically resets the itemDelimiter to the default (a comma) at the start of the handler rather than at the next idle message as HyperCard does. This means that a script almost never has to save the old itemDelimiter and reset it later. The itemDelimiter will revert to the default by itself if sub-handlers are called, while still remembering what it should be in the current handler, because the itemDelimiter in LiveCode is a local property. HyperCard users should note that if an imported HyperCard script calls a sub-handler, and that sub-handler relies on an itemDelimiter that was set in the calling handler, the sub-handler will fail in LiveCode.

Repeat structure: The final piece to note is the LiveCode repeat construction repeat for each. We could have written the second repeat loop in the above script using the repeat with x = 1 to n structure, but not only is that a much slower construct, but we wanted to demonstrate this alternate structure, which doesn't exist in HyperCard. The repeat with x = 1 to n structure requires LiveCode (and HyperCard, for that matter) to count from line 1 at every iteration, which creates a lot of processing overhead. The repeat for each structure instead leaves a pointer at the line that is being processed, and each interation simply moves the pointer ahead another line. This method is very efficient and very fast. Whenever possible, the repeat for each structure is preferred and should be used. Even the slight overhead of adding a counting variable to the loop in the example above does not significantly impair the speed of this type of repeat.

When using repeat for each, note that the variable l holds the actual value of the line rather than a chunk reference to the line. The script does not have to parse out the contents because it is already contained in l, and can be treated like any string container. The value of l is updated each time through the loop.

Repeat for each can be used to iterate through any type of data, not just lines. Repeat for each item i in theData is valid, as is repeat for each char c in thePhrase. The repeat for each structure requires a data container such as a field or variable; you cannot, for example, repeat for each card c in this stack.

Setting a card's number: Note that a card's number property, which is read-only in HyperCard, is writable in LiveCode. This makes it easy to add a new first card after a stack has been created; just set the card's number to 1.

The finished script of the Sort button should look like this:

on mouseUp
  answer "Sort the record cards alphabetically by product name?" \
        with "Cancel" or "Sort"
  if it is "Sort" then
    sortBgCards
    makeIndexMenu
  end if
end mouseUp

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 3 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

Click Compile at the top of the window. Save the stack to disk.

Adjusting the Print button

The Print button needs only a single, minor modification, so open its script. You will see a reference to doMenu. Change that line to:

if it is "Print" then print this card from "0,26" to "512,368"

Note that when printing, we use card coordinates to avoid printing the area of the menu bar. Compile and close the script.

Changing the OpenCard handler to preOpenCard

This change is completely optional. The background script contains an openCard handler that places the number of records and the number of the current record into a field. This works fine in LiveCode and we could leave it alone, but there can be a brief delay before the correct numbers appear after the card opens. LiveCode offers a preOpenCard system message which allows scripts to run before the card is displayed. This solves some problems which, in HyperCard, required locking the screen, going to a card, executing a handler, and then unlocking the screen. None of that is necessary if a preOpenCard handler is used instead.

To access the script of the background, you can select the group "Records" in the Application Browser and click the "Script" button in LiveCode's toolbar. Change the first line of the handler to on preOpenCard and the last line of the handler to end preOpenCard. Change pass openCard to pass preOpenCard. The rest of the handler is fine as-is. Compile and close the script.

We are done altering the Records background. Choose the browse tool again. Save the stack to disk.

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