When the user selects an item of a menu in the menu bar, in the (user-programmable) contextual menu or in the toolbar, or when the user clicks a button in the toolbar, Smile sends a do menu event to the active object's script.

• You handle do menu with a handler such as:

  on do menu the_cmd to the_object
      if the_cmd is command_1 then
          -- handle command_1
      else if the_cmd is command_2 then
          -- handle command_1
      [...]
      else
          continue do menu the_cmd to the_object
      end if
  end do menu

  the_cmd contains the command, a string, and the_object contains a reference to the target of the menu command, the owner of the script. Note that to is not optional: it is part of the command.

• If you install a do menu handler in an object's script, it is important that your handler send continue do menu the_cmd to the_object for the commands that it does not handle, in order that the object be able to perform its default behavior. If you trap do menu and you do not forward it, the built-in menu command will be effective, for instance you will not be able to save the object by the normal means.

• In a do menu handler, errors are silent: do menu traps errors and fails without an error message. If you want to be notified of errors occurring in the execution of a do menu handler, install a try [...] on error [...] end try structure such as in the example below:

  on do menu the_cmd to the_object
      continue do menu the_cmd to the_object
      if the_cmd is some_command then
          try
              -- handle some_command
          on error err_msg
              FatalAlert(err_msg)
          end try
      end if
  end do menu

  The script above uses FatalAlert, a built-in handler for displaying an error, part of Smile's built-in AppleScript library.

When the user selects an item of a menu in the menu bar, the name of the command is a string of four characters. Normally, such commands are handled by the Class script corresponding to the object's class. You can intercept the menu command that your object receives, and display the command, by installing (temporarily) the following handler in its script:

on do menu the_cmd to the_object
    dd("Received: " & the_cmd)
    continue do menu the_cmd to the_object
end do menu

You can override the default behavior, for instance to perform some specific action when the user closes a window, or when the user saves a window as in the example below.

on do menu the_cmd to the_object
    continue do menu the_cmd to the_object
    if the_cmd is "save" then upload_data(the_object)
end do menu

However, remember that it is your responsibility to call when needed the default behavior with a continue instruction.

When the user selects an item of the contextual menu, the name of the command is the string selected in the menu. You install a contextual menu to an object by providing its script with a CustomMenuItems handler, which must return a list of strings.

on CustomMenuItems(the_object)
    return {"Copy mail address", "Copy email address", "Copy Phone#", "Copy name"}
end CustomMenuItems

Your CustomMenuItems handler may use the built-in contextual menu by calling continue CustomMenuItems(the_object).

A do menu handler to handle the contextual menu could look like the example below.

on do menu the_cmd to the_object
    if the_cmd is "Copy mail address" then
        set clipboard to curr_address(the_object)
    else if the_cmd is "Copy email address" then
        set clipboard to curr_email(the_object)
    [...]
    else
        continue do menu the_cmd to the_object
    end if
end do menu

All objects support a contextual menu, but the contextual menu in dialogs is activated only when the dialog is in edit mode (not in the normal use mode).