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.

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.