Input Description: TetonPop Popup Menu Xtra for Director

Input is straight-forward and consists of a single function call:

returnValue = TetonPop(me, PopPassInt, screenloch, screenlocv, MyList)
	where
MyList = a single lingo list containing the menu (button) definitions, i.e. 
	    {menu-set 1 input}, {menu-set 2 input}, ...)
		

Input for the top-level menu and each submenu {repeat for each menu-set input}. Note that this is a single, comma-delimited list that can be reconstructed with each call (add buttons, remove buttons, etc).

MenusetID	Unique menu-set ID (integer < 0)
SetCount	Number (integer) of items (including separator lines) in the menu or submenu. An item consists of one pair of mitemID and mitemlabel.
"Button" input for the menu (repeat SetCount times)
mitemID	Unique menu item ID (integer). If mitemID > 0, it is returned from the TetonPop function call if the menuitem (button) is clicked. If mitemID = 0, it flags this item as a "separator line". If mitemID < 0, it is a reference to a submenu's menusetID.
MitemLabel	Label (string) that appears on the menu item "button" (as in "file", "edit", etc).
Checked	1 or 0 (integer) If Checked = 0, NO checkmark appears beside the label. IF Checked = 1, a checkmark is placed beside the label.
Grayed	1 or 0 (integer) If Grayed = 0, the button is a normal "active" button. IF Grayed = 1, the button is "Grayed Out" and is inactive.

Note that "pseudo-shortcuts" can be created by placing an ampersand before the desired character in MitemLabel. These aren't true shortcuts because they are NOT active UNLESS the popup is displayed. (The popup is not persistent.) Note: true shortcutting is straight-forward via lingo.

Example Director Script

This script can be associated with a Director button. When the button is clicked, the TetonPop menu appears on-screen where the click occured. The top-level menu has 3 items, one of which is a separator line, and one of which points to a submenu that also has three items. The return value (either a mitemID or zero) is used to fill in field "returnValue". (NOTE: the example below is actually short and simple if you delete all of the comments.)

on mouseUp
  Global PopPassInt
  
  -- Define new instance of TetonPop extra.  
  set f = xtra "TetonPop"
  set me = new(f)
  
  -- xx and yy are screen coordinate values for the upper left corner 
  -- of the top-level popup.  
  xx = the stageLeft + the mouseH
  yy = the stageTop + the mouseV+10
  
  -- The call to TetonPop is shown below. Input arguments are as 
  -- follows.
  --   1. me : xtra instance (defined above)
  --   2. PopPassInt : integer password. You may purchase the password
  --      at TetonMultimedia.com. IF YOU DON'T HAVE THE PASSWORD, an 
  --      extra button (inactive) will be added to the bottom of each 
  --      menu and will be labeled "TetonMultimedia.com".
  --   3. xx, yy : the screen coordinates of the upper left corner of 
  --      the popup (see above for specification method).
  --   4. MyTry : a list (it MUST BE a list) describing the actual 
  --      labelling/interaction of popup menu and buttons. It is 
  --      defined in a list (rather than hard-coding) so your popups 
  --      can be defined on the fly. It is described below.
  
  -- MyTry is the button definition list included in the TetonPop call.
  --   The 1st, 3rd, etc. lines are similar.
  --   The 2nd, 4th, etc. lines are similar.
  
  -- Lines 1, 3, etc. contain:
  --   1. MenusetID : (negative integer) the identifier of a submenu 
  --      within the popup menu. ALL popups have at least one submenu. 
  --      (For example, the first submenu is the menu that appears when 
  --      you click the "file" menu on a standard windows program.)
  --      Each MenusetID must be a unique integer < 0.
  --   2. SetCount : the number of menu items in submenu MenusetID. (For 
  --      example, when you click the "file" menu on a standard windows
  --      program, if 6 buttons drop down, then SetCount = 6.
  -- 
  -- Lines 2, 4, etc. contain SetCount groups of 4 items as follows. 
  -- Each group of 4 items defines an individual button OR a
  -- separator line. 
  --   1. mitemID > 0 : the numeric value returned from the popup when 
  --                    the button is clicked
  --      mitemID = 0 : flags this item as a separator line 
  --      mitemID < 0 : MenusetID of the submenu opened when this button 
  --                    is clicked.
  --   2. mitemLabel : string label (up to 80 characters) for the button 
  --                   (ie, "Save" on the "file" menu). If you want a 
  --                   pseudo-shortcut for the button, insert "&" in 
  --                   front of the character to use as the shortcut.
  --                   (Note that "true" shortcuts are not possible due 
  --                   to the non-persistent nature of the popup. 
  --                   However, if necessary, shortcuts can be 
  --                   implemented via lingo.)
  --   3. Checked = 0 : no checkmark beside the button label.
  --      Checked = 1 : display a checkmark beside the button label.
  --   4. Grayed = 0 : standard "active" button.
  --      Grayed = 1 : button grayed and inactive.
  
  -- NOTES:
  -- 1. TetonPop will return zero if no item is selected.
  -- 2. Menus may be nested 3-deep at most (a Windows limitation).
  -- 3. Maximum number of submenus in a single invocation = 100.
  -- 4. Maximum number of buttons (and separators) in a single 
  --    invocation = 1000.
  -- 5. ALL input fields are integer EXCEPT mitemLabel (string).
  -- 6. Each nonzero mitemID Must be unique.
  
  -- PROGRAMMING GOTCHA'S
  -- 1. Director scripting is a bit quirky about "ALT-Enter" useage 
  --    (line "to be continued" character). It's usually best to type 
  --    things out on a single line, THEN break it up using "ALT-Enter". 
  --    (This is particularly true on NT?)
  --  
  
  -- menusetid  setcount 
  --      setcount "fours" of (MitemID, mitemLabel, Checked, Grayed)   
  --              four1                  four2              four3           
  MyTry = [-1,       3, ¬
       11,"&button 11",1,0,   0,"dummy",0,0,       -3,"button Q",0,0, ¬
           -3,       3, ¬
       4,"button YY",0,0,    51,"button 51",1,0,   22,"button 22",1,1 ¬
  ]
  
  -- Call to tetonPop.
  myresult = string(TetonPop(me, PopPassInt, xx, yy, MyTry )) 
  
  set me = 0
  
  if myresult = 0 then set bstr = " "
  if myresult = 11 then set bstr = "button 11"     
  if myresult = 4 then set bstr = "button YY"
  if myresult = 51 then set bstr = "button 51"
  if myresult = 22 then set bstr = "button 22"
  
  set the text of member "returnValue" = bstr
  
  -- Obviously, the above script could benefit from some sort of 
  -- automation/list-useage. However, the clunky form used here may 
  -- assist visualization by the neophyte.
  
end