-- xtra Menu
-- v0.5 (c) 2017 Valentin Schmidt


Interface
=========

new object me
addItem object me, string title, *subMenuID -- returns itemID
addSeparator object me, *subMenuID
addSubMenu object me, string title, *subMenuID -- returns subMenuID
getItemChecked object me, integer itemID
setItemChecked object me, integer itemID, integer flag
setItemEnabled object me, integer itemID, integer flag
setMenuFont object me, string family, float size
show object me, object point


Notes:
======

Menu xtra is a simple (28 KB) scripting xtra for macOS (OS X 10.7 and later)
that allows to define and show popup-menus which can be arbitrarily nested (i.e.
having sub-menus).

Each xtra instance represents a single (nested) popup-menu, so if you need
multiple different menus, create multiple xtra instances.

Function 'addSubMenu' allows to add a submenu either to the main or some
already existing sub-menu, which allows arbitrarily nested menus.

A popup-menu menu can be opened programmatically at arbitrary places on the
screen, by calling 'show' (e.g. in some rightMouseDown event handler) and pass
the location as point. If the user selects a menu item, its itemID is returned,
and 0 if the menu was cancelled without selecting an item.

The Apple APIs the xtra is based on use a different coordinate system than
Director (the y-coordinate has 0 at the bottom of the screen), and to keep it
simple, the coordinate conversion has to be done by Lingo.

Here some sample code (propably could be simplified/improved) showing how a
popup-menu can be displayed at the point of the stage window were the user
(right-)clicked via mouse:

global gMenu

on rightMouseDown
  p = _mouse.mouseLoc

  -- calculate absolute cocoa coordinates on screen
  sr = _movie.stage.rect
  mr = _system.desktopRectList[1]
  gMenu.show(point(sr[1]+p[1], mr.height-(sr[2]+p[2])))
end