Menus

HyperTalk can specify the menus and menu items that appear in the menu bar and define the action taken when a menu item is chosen.

However, changes to the menu bar are not "saved" as part of the stack, nor are they restricted to the current stack. Modifications to the menu bar will not be restored when opening a saved stack, and navigating to a different stack does not restore the menu bar to its default state. Stack authors should use the on openStack or on resumeStack handlers to configure the menu to a desired state each time the stack is opened or becomes the focused window.

Even though the behavior of a menu is scriptable, menus themselves do not "contain" a script. Nor are they assigned an ID.

The list of menus appearing in the menu bar is retrievable via the menus function. For example, if the menus contains "Edit" then delete menu "Edit"

Referring to menus

A menu or menu item can be addressed by name ("Edit" menu, "Undo" menuItem of menu "Edit") or by its position (the third menu, menu 5, menuItem 6 of menu "Font"). When referring to a menu, the resultant value is a line-separated list of menu items that appear in the menu (a single hyphen character, -, is used to denote a separator). When referring to a menu item, the value of the item is its name (i.e., "Undo" menuItem of menu "Edit" yields Undo).

For example,

if menu "Objects" contains "Card Info..." then answer "Try choosing 'Card Info...'"
put the second menu into editMenuItems    -- typically all the menu items in the Edit menu
answer the first menuItem of menu "Edit"  -- typically responds with 'Undo'

Creating menus and menu items

New menus are added to the menu bar using the create command and removed using the delete command. For example, create menu "My Custom Menu" or if the menus contains "My Custom Menu" then delete menu "My Custom Menu". When creating a new menu, it will be added to the end of the menu bar (rightmost position).

You cannot create two menus that share the same name, nor can you delete a menu that does not exist.

The value of each menu is treated as a list. You can add, delete, or modify menu items by mutating items in the menu's value. For example, to replace the contents of a menu put "Item 1,-,Item 2" into menu "My Custom Menu". To append items to a menu, put "Item 3" after the last line of menu "My Custom Menu". To delete a menu item, delete the second line of menu "Edit"

Use the reset menuBar command to eliminate any changes you've made to the menu bar and restore the default WyldCard menus and menu items.

Responding to selections in the menu bar

Menus created by script have no default behavior assigned to them. However, when the user chooses a menu from the menu bar, the doMenu message is sent to the current card. A handler placed in the script of the card, background or stack can intercept this message and provide custom behavior. (Note that popup-styled buttons do not send the doMenu message; only menus in the menu bar send this message).

For example, place the following handler in a stack script to prompt the user to confirm if they really want to edit the background of the card:

on doMenu theMenu, theMenuItem
  if theMenu is "Edit" and theMenuItem is "Background" then
    answer "Are you sure you want to edit the background?" with "OK" or "Cancel"
    if it is "OK" then pass doMenu
  else
    pass doMenu  -- Don't interrupt other menu selections
  end if
end doMenu

By invoking pass doMenu we're letting WyldCard respond to these menu selections. In the case where the user chooses "Background" and does not click "OK" in the dialog box, we are not passing doMenu and thereby "trapping" the menu selection and preventing WyldCard from acting upon it.

Special considerations

Menus in WyldCard differ from Apple's HyperCard in a few ways:

• In HyperCard, if a script created a menu item with the same name as a HyperCard menu item, the new item would inherit the behavior of HyperCard's original menu item. This is not true in WyldCard.
• WyldCard cannot access or control the behavior of the menus produced by the operating system (such as the Apple or "WyldCard" menu on macOS systems). These menus cannot be deleted or modified, and selecting an item from one of these menus does not produce a doMenu message (thus, the stack cannot take action when the user selects an item from them).
• When getting the contents of a menu from the menu bar, the result will be a list of lines (each line being the name of a menu item or - to denote a separator). This is true even if the menu items were put into the menu as a single-line list of values.