> Wimp.Menus

New Calls
---------

        Wimp_CreateMenu
        Wimp_CreateSubMenu
        Wimp_Poll:  reason code 9  (Menu_Selection)
        Wimp_Poll:  reason code 17 (Menu_Warning message)


Overview
--------

The user interface to menus is as follows:

  MENU button click in window ==> open menu tree appropriate to that window
  moving over right-arrow icons in a menu causes the submenu to be opened
  MENU or SELECT button click on an item selects it and closes the menu tree
  ADJUST button click on an item selects it and keeps the menu tree open
  menus with a title bar can be picked up and moved around
  any button click outside the menu tree cancels the menus
  icons can be ticked to show current settings
  shaded icons cannot be selected, and their submenus cannot be opened

The significant change to this interface since Arthur 1.20 is that a menu
selection can be made with the ADJUST button so that the menu tree remains
open.

A facility has also been added so that an application can be notified when a
particular branch of the menu tree is being activated, and can take
appropriate action.  This allows, for example, a particular menu to display
different 'tick' information depending on which part of the tree it has been
activated from.


Persistent Menus
----------------

To retain backwards compatibility with the old Wimp, the following approach
has been taken to the problem of keeping the menu tree open after a selection
has been made using the ADJUST button:

     *  When a menu selection happens, the Wimp does not close the menu tree
        immediately, but simply sets an internal flag.  It then returns a
        menu_select reason code from Wimp_Poll, as before.

     *  When the application receives the Menu_Select reason code, it should
        perform the appropriate actions, as normal.  After that, it should
        make a call to Wimp_GetPointerInfo to find out the state of the mouse
        buttons.  If the right-hand button is depressed (bit 1 of the button
        state), it should re-encode its menu tree (depending on what happened
        as a result of the menu selection), and call Wimp_CreateMenu with the
        same menu tree pointer.  It should then return to its polling loop.

     *  When Wimp_Poll is called, if the current menu tree has been marked
        temporary, and Wimp_CreateMenu has not subsequently been called, the
        tree is closed.

     *  When Wimp_CreateMenu is called, the Wimp checks to see if this tree
        corresponds to the one currently active.  If it does correspond, it
        attempts to open the tree in the same way it is already, keeping the
        coordinates the same, and selecting the same submenus.  This process
        continues as far as possible, until the end of the tree is reached,
        the tree fails to correspond to the old one, or an item has become
        shaded.

On old Wimps, only the first menu in the tree will be re-opened.


Menu warning message
--------------------

To ask the Wimp to give a warning message when a particular branch of the
menu tree is accessed, the application program should:

     *  set bit 3 of the menu flags of the entry containing the submenu pointer

     *  when the mouse pointer is placed over the right-arrow icon of this
        entry, instead of simply opening the submenu, the Wimp will return a
        message of the following form from Wimp_Poll:

            R0 = 17
            R1 --> block (as passed in to Wimp_Poll)
              +0 = size of block
              +4 = 0 (message from Wimp)
              +8 = message reference number
             +12 = 0
             +16 = &400C0  (menu warning)
             +20 = submenu pointer
             +24 = x-coordinate of proposed submenu
             +28 = y-coordinate of proposed submenu
             +32.. = menu tree so far (selection numbers)
                     terminated by -1

     *  on receipt of this message, the application should perform whatever
        processing it wants to, and then open the submenu as follows:

            Wimp_CreateSubMenu
            Entry:  R1 --> submenu
                    R2 = x-coordinate of menu
                    R3 = y-coordinate of menu

        (R1,R2 and R3 are taken from the message block (+20,24,28).

Note that the submenu pointer itself does not have to be set up when the main
menu is created - it could just be a dummy pointer, and the call to
Wimp_CreateSubMenu could substitute in the correct menu tree as appropriate. 
This allows, for example, for a series of dialogue menus to be accessible via
the menu tree - the appropriate window is created when it is required, and
the window handle is passed in to Wimp_CreateSubMenu.