HyperActive Software Home

Converting a HyperCard stack to MetaCard

Table of Contents

(Partial listing:)

Moving existing objects down

The first thing we need to do is increase the card height to make room for the new menu group. Choose "Stack Properties..." from the Edit menu.

There are six boxes at the bottom of the dialog that control the size of the card. Change the height dimension at the far left to 380, which is the current card height plus 38 for the menu group. The stack will resize as soon as you tab out of the field.

Click the "Edit menus" checkbox at the right of the "Menu Bar" field. This setting is effective only on Macs, and instructs MetaCard to display the menu group at the top of the stack window, just as it does on a Windows machine. This will make working with the new menu group easier after we create it.

Now click the "Properties" tab and uncheck the "Resizable" box, which removes the size box from the bottom right of the stack window. Since we are not planning to write scripts that reposition card objects, we don't want the user to be able to resize the stack. If they could, all they would see outside the original card area would be white background.

Close the Stack Properties dialog.

Next we need to move all the existing card and background objects downward by 38 pixels to make room for the menu group. This is best accomplished by a script.

The script of card 3 is empty, so we will use that space to write a temporary script that we will run only once. Type this into the script of the first card of the Records background:

on pushDown
  repeat with x = 1 to the number of bgs
    set the top of bg x to the top of bg x + 38
  end repeat
  repeat with x = 1 to the number of cds
    go cd x
    repeat with n = 1 to the number of cd parts
      set the top of cd part n to the top of cd part n + 38
    end repeat
  end repeat
end pushDown
For HyperCard compatibility, MetaCard accepts the use of the word parts, though the actual term is really controls. You can use either in the above script.

Close the script editor and run pushDown from the message box. Every object in the stack will be repositioned, and a clear area at the top is now available for the menu group. Once the repositioning is done, you can delete the pushDown handler and save the stack to disk. You can use this script to help with any HyperCard stack conversion, not just this tutorial.

Creating a menu bar and menu items

The easiest way to create a menu group in MetaCard is to use the Menu Builder tool. This utility creates all the menu buttons, sets the necessary properties of each so that it acts like a menu, and places it on the current card. Choose the Menu Builder from the Tools menu.

MetaCard defaults to a File, Edit, and Help menu. These are pretty much the minimums for any application on any platform, and we will use them. We want to change their contents though to suit our stack.

Click on the File listing in the top field. The bottom field displays the contents of that menu. You will notice that the menus and their menu items contain some unusual punctuation, which is explained in the About MetaCard Menus section.

Our stack does not open any files, so remove the "Open" menu item by selecting it and clicking the Delete button. We do want to be able to save and print our stack, so we will add these lines:

Page Setup...
&Print Card/P
To add the first of these items, click the Add button next to the Menu Items field and enter "&Save/S". The item will go to the bottom of the list. Add the other four lines the same way (the second and fourth lines are just hyphens, which create divider lines.) Then hilite each item in turn and use the up arrow button to move the item higher up in the menu items list. Position these four lines in the above order at the top of the menu item contents.

Click on the Edit menu listing in the top field to see its contents. Cut, copy, and paste are already there, but let's add "undo". Use the Add button to add these two lines to the Edit menu items field:

The second line is again just a hyphen. Use the up arrow to position these two items at the top of the Edit menu contents.

The Help menu needs no changes, so we don't need to do anything there.

We also want to add an additional menu which will hold the dynamic Index. Click the "Add" button next to the menu list (not next to the items list) and enter:

This menu has no default items, so leave the bottom menu items field empty. Use the up arrow button to move the Index menu upward one position so that it is between the Edit and the Help menus.

Remember: to function correctly, the Help button must always be last in the list.

Click the "Build" button to build the menu group. It is placed on the current card.

If some of the menu buttons are created opaque instead of transparent (the current version of MetaCard seems to do this by accident) you can double-click each one while in background mode to set its opaque property to false. The easiest way to access the properties for these buttons is to double-click their names in the Control Browser.

Finally, double-click the "menugroup" group in the Control Browser, and check the Background Behavior checkbox. Setting the backgroundBehavior of a group to true causes that group to be automatically duplicated on every new card, in the same way that HyperCard handles backgrounds. Since we want a menu group on each card, this is the desired behavior. MetaCard sets this property to true automatically for all backgrounds that are imported from a HyperCard stack, but any new groups you create in MetaCard must be set manually if you want that behavior.

Note about menu buttons: The menu items of a menu button are simply a return-delimited list stored in the button contents. After the menu group is initially built, it is easy to edit the menus by changing the contents of each menu button. You do this just as you would in HyperCard. You can view the contents of each button by double-clicking the button with the arrow tool and choosing the "Extras" tab in the dialog window. The contents can be edited directly in this dialog, or can be set via script just as in HyperCard. The advantage to using the Menu Builder tool initially is that it is a quick way to generate a menu group with all the button properties set correctly for menu use, but you cannot edit an existing menu group with the Menu Builder.

Putting a menu on each card

A custom menu will only appear in the menu bar if the current card contains a menu group, which means we need to place this group on every card. (The exception is if a defaultMenuBar has been assigned to the stack.) When you are building stacks from scratch in MetaCard, you can set MetaCard to create new cards with the same groups that were on the card you started from, just like HyperCard does. But in a HyperCard conversion where the cards have already been created without menus, we need to add the menu group to each imported card. This is most easily done with a script.

We will again use a temporary script that runs only once. Go to our temporary script warehouse, the first card of the Records section (you may have to select the browse tool again to use the buttons for navigation,) and type this into the script of the card:

on placeMenus
  repeat with x = 1 to the number of cds
    if there is no grp "menugroup" of cd x
    then place bg "menugroup" onto cd x
  end repeat
end placeMenus
This script will work in any stack conversion, not just in our example stack. Run placeMenus from the message box. You can page through the stack to see that every card now contains a menu group. Then delete the temporary script and save the stack to disk.

To see how the menus will look later: You can see how the menu bar will look on a Mac by choosing "Stack Properties..." from the Edit menu and unchecking the "Edit Menus" checkbox. The stack will collapse itself to hide the menu group. If you click on the stack to bring it frontmost, its menus will be visible in the Mac's menu bar. None of the menu items will work yet because they have no scripts. Re-check the "Edit Menus" checkbox in the Stack Properties dialog to bring the menu group back into view so we can work on it some more. While the dialog is open, you should also type menugroup into the Menu Bar field if it is not there already. This tells MetaCard which group to insert into the menu bar when the stack is running on a Macintosh. The Menu Bar field has no affect when running on other operating systems, since the menu group is always visible in the stack window on those systems. Close the Stack Properties dialog.

Writing the menu scripts

To edit these scripts, start editing the background "menugroup", choose the arrow tool, and Option-Cmd-click the button. Or, easier, hilite the button name in the Control Browser and click the "Edit Script" button. Edit each of the following button scripts.

File Menu:MetaCard provides a default switch script structure for menu buttons. We only need to fill in the details. (A switch control structure is like a streamlined if-else control structure, but more efficient.) Edit the File button script to look like this (changes are in red):

on menuPick which
  switch which
  case "Save"
    save this stack
  case "Page Setup"
    -- shows Page Setup on Mac, choose printer on Windows:
    answer printer 
  case "Print Card"
    if the short name of this bg = "records"
    then print this card from "0,38" to "512,380"
    else beep
  case "Quit"
  end switch
end menuPick
The menuPick message is sent to a menu button whenever a menu item is chosen, along with a parameter which is the name of the menu item. The switch statement determines the resulting behavior.

Edit Menu: MetaCard provides simple commands for common editing functions. Change the script of the Edit menu to look like this:

on menuPick which
  switch which
  case "Undo"
  case "Cut"
  case "Copy"
  case "Paste"
  end switch
end menuPick
Note that it is not necessary to specify the type of content that is to be cut, copied, or pasted as it is in HyperCard; i.e., paste picture and copy text are not commands in MetaCard. The copy, cut, and paste commands function universally, regardless of the content being manipulated.

Index Menu: The index menu contents are built dynamically by a handler in the stack script, which we will edit later. (And even further down the line, in the Optimizing for MetaCard section, we will be deleting this menu entirely and replacing it with a palette instead.) For now, we will just script the behavior that should occur when a user chooses one of the menu items. Each menu item will eventually be the name of a product that has been entered into the "Product Name" field on a Records card.

Change the Index menu button script to this:

on menuPick which
  go cd lineOffset(which,me) of bg "records"
end menuPick
Note the lineOffset function, which HyperCard doesn't provide. LineOffset() takes two parameters: the string to locate, and the container to locate it in. It returns the line number in which the string is found. In this case, we are getting the line number of a product name which is within a list stored in the button contents. MetaCard offers a similar itemOffset function.

Help Menu: The Help menu will take us to either the Help card or the About card, depending on the user's menu choice. Change the script to this:

on menuPick which
  switch which
  case "Help..."
    go cd "Help"
  case "About..."
    go cd "About Card"
  end switch
end menuPick
That takes care of the menus for now. You can turn off "Edit Menus" in the Stack Properties dialog, bring the stack to the front, and test them (or you can leave Edit Menus turned on and just test the menus in place.) We will add more to the menus when we edit the stack script, which is next.

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

Developer ResourcesHome



Contact us 5226 West Nokomis Pky, Minneapolis MN 55417





All contents copyright (C) 1996, HyperActive Software. All rights reserved.
Revised: December 3, 2001
URL: http://www.hyperactivesw.com/mctutorial/tutorialtoc.html