                             WIMP Menu Interface
                             ===================
Overview
--------
Rabbit provides scripts with an interface to WIMP menus.


Technical details
-----------------
In order to create a menu a script should call reset_menu followed by one or
more calls to add_menu_item followed by a call to open_menu. The script has no
choice as to the menu's position, which is always at the current location of
the mouse pointer.
A selection in the menu is reported to the script via the menu_selection entry
point.

Commands
--------

void reset_menu(string title; int width)

   * Parameters:

       title      - The menu's title.
       width      - The menu's width (from Riscos 3.5 on this is ignored and
                    set automatically)

  resets the menu structure in memory in preparation for calls to add_menu_item
and closes any existing menu.


void add_menu_item(string text; int flags)

   * Parameters:

       text       - The menu item text, sprite menu items are not allowed.
                    (max 12 characters)
       flags      - Flags, not the same as for a call to the SWI Wimp_CreateMenu

                     Bit 0 - The item is greyed out.
                     Bit 1 - The item is ticked.

                    All other bits are reserved and must be 0.

   adds an item to the menu structure, which must have been reset using the
reset_menu command prior to the first call to this command. 


void open_menu()

   opens a script menu. The menu must previously have been built using a call to
reset_menu() followed by at least one call to add_menu_item.


void change_menu_item(int item; string text; int flags)

   * Parameters:

       item       - The menu item to be changed (the item create by the first
                    call to add_menu_item is numbered 0)
       text       - As for add_menu_item()
       flags      - Flags, not the same as for a call to the SWI Wimp_CreateMenu

  should any changes be required to the menu following an selection with ADJUST (which will leave the menu open) they can be made using this call.


Entry Points
------------

void menu_selection(int item)

   * Parameters:

       item       - The menu item selected (the item create by the first
                    call to add_menu_item is numbered 0)

  is called when the user chooses an item in a menu belonging to the script. If the selection was made with ADJUST, then the menu is kept open. Which mouse button was used is not reported to the script, should any changes to menu items
be required as a result of the selection, then they should be made regardless of
which mouse button was used.

   Should it be necessary to close the menu regardless of which mouse button was used, then this entry point should call reset_menu() without any subsequent calls to add_menu_item() or open_menu().
