Name: popup

Type: command

Syntax: popup {<stack> | <button>} [at <location>]

Summary:
Displays a <popup menu> whose <menu item|menu items> are either lines in
a <button(keyword)> or <button(object)|buttons> in a <stack>.

Introduced: 1.0

OS: mac, windows, linux

Platforms: desktop, server

Example:
popup button "Contextual Menu"

Example:
popup stack "Button Properties"

Example:
on mouseDown theButton
   -- pop up the menu on right-click or control-click
   if theButton is 3 then popup stack "Lookup Options"
   else pass mouseDown
end mouseDown

Parameters:
stack:
Any stack reference. The stack's first card contains a button for each
menu item in the popup menu.

button:
A reference to a button on the current card

location:
A point or expression that evaluates to a point. Two integers separated
by a comma.

Description:
Use the <popup> command to display a contextual menu.

Use the <popup> command in a <mouseDown> handler to display the menu. 

The popup menu appears with its top left corner at the <location>. If no
<location> is specified, the menu's top left corner is at the
<mouseLoc|mouse location>. While the popup menu is displayed, the
handler pauses.

Choosing a menu item from the popup menu sends a <menuPick(message)>
message to the button (for a button menu) or a <mouseUp> <message> to the
clicked control in the stack (for a stack menu). The button or stack
menu handles the menu choice.

If you use a button to hold the contents of the menu, the contents of
the button's <menuItem Keyword> is displayed in the popup.

**Important:**  If you use a button to hold the contents of the menu,
the following properties must be set:

- <style(property)> must be set to "menu"
- <menuMode(property)> must be set to "popup"
- <visible(property)> may be set to either true or false.


**Important:**  You must escape reserved characters in the button's
<menuItem(Keyword)>. These include:

- `&` (To display the string "A&B" in the popup menu, use "A&&B")
- `\` (To display the string "A\B" in the popup menu, use "A\\B")
- `/` (To display the string "A/B" in the popup menu, use "A//B")


**Important:**  The <menuMouseButton(property)> of a button used with
the <popup> command must be set to zero. Setting it to any other value
may result in unexpected behavior when the menu is used. To control
which mouse buttons may be used to access the menu, use the mouse button
parameter of the <mouseDown(message)> message, as described above.

References: pulldown (command), clickLoc (function), mouseLoc (function),
menu item (glossary), popup menu (glossary), button (keyword),
menuItem (keyword), popup (keyword), menuPick (message),
mouseDown (message), mouseDown (message), mouseUp (message), message (glossary),
stack (object), button (object), style property (property),
toolTip (property), menuMode (property), visible (property),
menuMouseButton (property)

Tags: math

