Name: menuPick

Type: message

Syntax: menuPick <pChosenItem> [, <pPreviousTab>]

Summary:
Sent to a <button(object)> when a <menu item> is chosen from the <menu>
associated with that <button(object)>.

Associations: button

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:
on menuPick pChosenItem -- in a pulldown menu
  if pChosenItem is "Close" then close the defaultStack
  else if theItem is "Quit" then quit
end menuPick

Parameters:
pChosenItem:
The label of the menu item the user chose.
If the menu item chosen is part of a submenu, the menu item label is 
followed by a vertical bar (|) and the submenu's label.

pPreviousTab:
The text of the menu item that was selected before the user chose a new
menu item. This parameter is included only if the button's menuMode
property is set to "tabbed".

Description:
Handle the <menuPick> <message> to do something when the user chooses a
<menu item> from a <button menu>, or chooses a tab in a <tabbed button>.

>*Note:* If the specification of a menu or submenu includes a tag, that
> tag will replace the menu label in the <pChosenItem> parameter

The <menuPick> <message> is sent when the user clicks a tab in a 
<tabbed button>, when the user chooses a <menu item> from the <menu> 
associated with a <button(keyword)>, or when a <button(object)|button's>
<menuHistory> <property> is set by a <handler>.

The <menuPick> <message> is sent every time a <menu item> is chosen,
even if the <menu> is a type that retains its state (such as an option
menu) and the chosen <menu item> has not changed. (However, no
<menuPick> <message> is sent when an already-chosen tab in a <tabbed
button> is clicked, since no menu is displayed.)

To get the item number of the currently chosen menu item, use the
<menuHistory> <property>.

>*Note:* The & and / characters can be used in a pulldown menu to create
> special effects. To be shown (instead of creating these effects),
> either <character> can be doubled. (For example, placing the line
> "This && That" in a <menu item> results in the <menu item> being
> displayed as "This & That", with one ampersand.) When the user chooses
> a <menu item> with these special characters, the <pChosenItem>
> <parameter> is the text that appears in the menu as displayed, not the
> text of that line of the <button menu|menu button>.

The menu item specification allows a tag to be specified using the form:

    <label> [ '/' [ <accelerator> ] [ '|' <tag> ] ]
    
Note that the <tag> is optional as is the <accelerator> however, if you
want an item with a tag but without the accelerator you need:

    <label> '/' '|' <tag>
  
If a menu item has a <tag> then it is the tag string that is passed to
menuPick rather than the <label>. This is useful for localization of
menu items as you don't need to change the menuPick handler for each
language supported.

The following tags should be used to label the standard edit menu items
to enable them to be controlled by the system dialogs on Mac OS X
(e.g. answer file, ask file etc.):

- undo
- redo
- cut
- copy
- paste
- clear
- select all
- preferences

Changes:
In version 3.5 menu tags were added to the menu item specification.

References: pulldown (command), property (glossary),
tabbed button (glossary), menu item (glossary), handler (glossary),
message (glossary), menu (glossary), button menu (glossary),
parameter (glossary), character (keyword), menu (keyword),
button (keyword), button (object), label (property), 
 menuName (property), menuHistory (property)

Tags: menus

