Back to Contents        Previous        Next





5. Doing more with menus **

So far we have only got a simple two-item menu with an info window leading, like a sub-menu, from Item 1. (Windows used as ‘sub-menus’ are often called ‘dialogue boxes’.) There is a lot more you can do with menus. This part looks at submenus, ticks, greying out, dotted lines, changing menu text, writable menu items and showing keyboard shortcuts with menu items.

First of all, let’s create a menu for our main window.

Just below the existing FNwimp_createmenu line, add the following lines:

menu$=“MyApp/Info/Item 2/Item 3/Item 4/Save”
mainmenu%=FNwimp_createmenu(menu$,0)
PROCwimp_attachsubmenu(mainmenu%,1,info%)

And cause this menu to open in the main window by altering FNuser_menu so it looks like:

DEF FNuser_menu(window%,icon%,screenx%,screeny%)
return%=0
CASE window% OF
         WHEN iconbar% : return%=iconbarmenu%
         WHEN main% : return%=mainmenu%
ENDCASE
=return%

When you press <menu> anywhere over the main window, you should get a menu with 5 items. The first item should have a small ‘arrow-head’ to the right of it - showing that it leads to a submenu. ( In fact, as we have said, it can be a sub-menu or a window - just supply the appropriate handle.) In this case we have attached the ‘info’ window.


Now create another menu by adding the following line above the menu$=... you have just entered:

i3menu%=FNwimp_createmenu(“Item 3/Help/Tick me!”,0)

You can see from the title of this menu that it is obviously a submenu for Item 3 on our main menu. So, we need to use PROCwimp_attachsubmenu again - but this time attaching a menu handle rather than a window handle.

Therefore, immediately below PROCwimp_attachsubmenu(mainmenu%,1,info%) add:

PROCwimp_attachsubmenu(mainmenu%,3,i3menu%)


Run !MyApp and take a look at the menu. And that is all there is to it!





Here is another example:

Before the i3menu%=... line add the following:

tickmenu%=FNwimp_createmenu(“Tick me!/Bored/Dull/Waffle”,0)

And after the i3menu%=... line add:

PROCwimp_attachsubmenu(i3menu%,2,tickmenu%)

which results in a sub-menu attached to a sub-menu item. Thus you can see that it is quite painless to build up long and/or complex menu structures.


Choosing items from a sub-menu is exactly the same as from a menu: in both cases Dr Wimp causes PROCuser_menuselection to be called. The only difference is that, for a sub-menu selection, the parameters placed in PROCuser_menuselection will be from the sub-menu where the actual selection is made. For example, if the ‘Bored’ item from the tickmenu% sub-menu is selected, the values passed by Dr Wimp in the PROCuser_menuselection call will be the value of tickmenu% in the menu% parameter and 1 in the item% parameter. i.e. the selection is treated as if the tickmenu% menu stood alone. (Note: Selections from the sub-menu of a font menu are handled slightly differently - see Section 2.18)


When you first create a menu, it will have no ticks by the side of any items, no dotted lines separating items, and none of the items are greyed out. If you want any of these features they have to be set up after the menu has been created (and set up again after any menu re-creation, see later).

PROCwimp_menutick(menu%,item%,state%) is multi-functional and uses the now-familiar Dr Wimp format to put or remove a menu-tick or to toggle between these two states. If the third parameter is 0 any menu-tick against the item is removed: if it is 1 a tick is placed: and if it is 2 the existing menu-tick status is reversed.

So, add the following line to the end of PROCuser_menuselection and try it out:

IF menu%=tickmenu% AND item%=1 THEN PROCwimp_menutick(menu%,item%,2)

(In addition, FNwimp_getmenutick allows you to check whether or not a menu item is already ticked.)


PROCwimp_menuenable
works in exactly the same way to allow you to enable/disable menu items - or to toggle between these two states. (And FNwimp_getmenuenable allows you to check whether or not a menu item is already enabled.)

At the end of PROCuser_menuselection, add the following lines and try it out:

IF menu%=mainmenu% AND item%=2 PROCwimp_menuenable(menu%,3,0)
IF menu%=mainmenu% AND item%=4 PROCwimp_menuenable(menu%,3,1)

Similarly, PROCwimp_menudottedline(menu%,item%,on%) puts/removes a dotted line on the menu below the item specified. If on% is 1 a dotted line is added: if on% is 0 a dotted line (in that position only) is removed. (No toggling option this time.) Try it out by adding the following after i3menu% is created:

PROCwimp_menudottedline(i3menu%,1,1)

(Also, FNwimp_getmenudottedline() allows you to check whether or not any menu item already has a dotted line below it.)


There are still a few more functions related to menus.

Look at:

PROCwimp_menupopup(menu%,pos%,x%,y%)

This wimp-function is designed to allow you to bring up a menu without the need to press <menu>. You can use it to bring up a menu from a <select>/<adjust> mouse-click, or at any time you wish. (You can also display a window in the same way by using a window handle instead of a menu handle in the first parameter.)

The parameter pos% controls the positioning of the menu:

If pos%=0, then the menu is displayed at the screen co-ordinates x%
,
y% .
If pos%=1 then the menu is positioned as for an iconbar menu (as if the iconbar icon was at the screen coordinate x%).
If pos%=2 then the menu is centred on the screen.
If pos%=3 then the menu is placed at the mouse pointer position (slightly to the right, to line up with the use of the ptr_menu pointer shape).
If pos%=4 then the menu is placed with its left edge butting up against the right edge of the icon over which <select> was clicked. (This option is designed for use with ‘pop-up menu button’ icons and is complementary to the previous option.)
These options can be useful for many purposes. (For instance, a ‘menu icon’ is often used - usually to the right of a writable icon - to offer the user a choice of items/strings to enter into the writable icon. The use of pos%=4 would be ideal here.)

Note that, for some values of pos%, the values of x% and/or y% are ignored, but it is vital that dummy x%/y% values are still used in these cases.

The text of a menu item can be read by using FNwimp_getmenutext, passing the menu handle and the item number. The complement of this is PROCwimp_putmenutext. This allows you to change the text of an item. (In Dr Wimp, all menu text is created as indirected, including the menu title text - and there is no restriction on changing the text length subsequently.)

Now, delete the previously-entered PROCwimp_menuenable lines, and put the following lines in the same place:

IF menu%=mainmenu% AND item%=2 THEN
         PROCwimp_putmenutext(mainmenu%,3,“ABCDEFGHIJKLMNOPQRS”)
ENDIF

Try choosing the second menu item with <adjust> (to keep the menu displayed). The menu will automatically adjust its width to accommodate the longest line.



There is one more major menu function, which turns a menu item into a writable one. A block of memory is reserved automatically to put the text into.

After the main menu has been defined, add the following line:

PROCwimp_menuwrite(mainmenu%,4,20,1,””)

The first parameter is the menu handle, the second is the item number. The third parameter is the maximum length of text allowed to be entered and the fourth parameter determines if the writable item has a border placed around it (0 means no border, 1 means a border). The fifth parameter is the validation string.

It doesn’t matter if some text is already there: it will be reinserted into the writable icon (and, if necessary, the maximum length of text will be increased to allow all the existing text to be entered). To read the text, simply use FNwimp_getmenutext, as already mentioned.

When this wimp-function is used a validation string of “Pptr_write;Knar;” is automatically inserted by default - and the contents of the fifth parameter above are added to this default string as a suffix. So, if you are content with this default, the fifth parameter can be a null string - as above. But if you wish to add further validation string commands (and/or modify the defaults) simply include your required validation string as the fifth parameter. For example, a fifth parameter of “A0-9;Kn” would add an A-command restricting the allowable keyboard entries to the digits 0-9, modify the K-command to become Kn (and leave Pptr_write unaltered).

(Note that pressing the <return> key when the caret is in a writable menu item has the same effect as selecting that item with the mouse. Hence this action is captured with PROCuser_menuselection and not FNuser_keypress.)



The final handful of menu functions don’t really need much description. For more details see !Fnc’n’Prc or Section 3 in this manual.

FNwimp_menusize                           - Returns the current number of items in a menu.
FNwimp_menumaxsize                  - Returns the maximum allowable size of a menu, as
                                             specified at creation.
PROCwimp_menuclose                  - Closes any open menu.
FNwimp_getmenutitle                  - Returns the title of the menu.
PROCwimp_putmenutitle                  - Changes the menu title.
PROCwimp_menuitemcolour                  - Sets the colour of a menu item text.


Tip: If you are using a standard iconbar menu, with ‘Quit’ as its last item, you can use:

WHEN FNwimp_menusize(iconbarmenu%) : PROCwimp_quit(0)

instead of (in the earlier coding):

WHEN 2 : PROCwimp_quit(0)

This will ensure that the quitting action will always be associated with the last item on the iconbar menu, however many items there are. This is very useful when you are developing a program and changing the number of menu items.


[Your !RunImage listing should now look like listing RI_03 in Tutor1 (apart from the REM lines, perhaps). Do not destroy it as the following sections continue the tutorial from this stage.]


Adding ‘Keyboard shortcuts’ to menu items
You are probably already familiar with menus which look like the one below - taken from !Draw - where ‘keyboard shortcuts’ are shown right-justified against the menu item (here, a sub-menu) to which they refer.
Their intention is to tell the user that the indicated action can be obtained in two ways: either click with <select> over the menu/sub-menu item, or just press the indicated keyboard key combination.
Thus, on the sub-menu below, if you wished to select !Draw’s Text tool on its toolbar you can either press <select> on the second sub-menu item (appropriately called “Text”) or just press the key combination <Ctrl-F7>.

Picture Pics/pic004.png

Adding such shortcuts to your own application’s menus is made very easy by the Wimp. All you have to do is add the shortcut text to your menu item text, separated by a space. The Wimp will then do the necessary alignment.

For example, to achieve the sub-menu appearance for the second item shown above you would simply make the menu text for that item:

“Text ^F7”

This works for all of the following shortcut symbols:

         ^         - ASCII code 94, either one of the <ctrl> keys. (Any key symbol can follow)‹‹
         ‹         - ASCII code 139, either one of the <shift> keys. (Any key symbol can follow)
         Fn         - where n is any of the Function key numbers i.e. F1-F10

and also for the following text items, which are specifically named keys:

         ‹Esc
         Print
         Delete
         Insert
         Enter         - the <return> key
         Up         - the ‘Page Up’ key
         Down         - the ‘Page Down’ key

(This list may not be complete, and it is also known that on some computers there are further named keys which give the same effect. The list available for a particular computer can always be found near the top of the file Resources:$:Resources.Wimp.Messages)

Note that at least the first letter of the shortcut must be in upper case if it is not preceded by the <ctrl> or <shift> symbol.

Also, be careful not to add any spaces at the end of the shortcut text - and you might need to ensure that your menu title or one of the menu items has text long enough to make the resulting menu wide enough to make the right justifications visually pleasing.

If you indicate keyboard shortcuts like this, don’t forget to add the necessary coding to FNuser_keypress() to carry out the shortcut!‹‹‹‹‹




Top of page        Back to Contents        Previous        Next