Back to Contents        Previous        Next





2. First menus **


An iconbar menu
The next thing needed is a menu for the iconbar.

Menus can be created by DrWimp in several ways, but the simplest is by using a shorthand form which is passed as a string. DrWimp translates it into the correct layout in a block of memory for the Wimp to understand.

So, after the previous addition of FNwimp_iconbar, add the following line to PROCuser_initialise:

iconbarmenu%=FNwimp_createmenu(“MyApp/Info/Quit”,0)


This wimp-function creates a menu definition and returns a handle for it, which here is put into iconbarmenu%.

This is the first time we have added a wimp-function call to the skeleton !RunImage. See how straightforward it is.

The string in the first parameter is the key part and you can see that the string comprises three items of text separated by a “/”. Each item of text corresponds to an item in the menu-to-be. The first item (”MyApp”, here) is the menu title, and the following items are the actual menu items, in order. Thus, the top menu item is “Info” and the second (bottom) one is “Quit”. In the same manner you can use as many items as you wish - except that the total string length of the first parameter must not exceed 255 characters (or even less if you include the string directly in the Basic line as in the example above). (Other means are provided to get round this limitation and are introduced later.)

The second parameter is the maximum number of menu items allowed to be used in this menu - to allow for a later increase perhaps. It is set to 0 here and this has a special meaning: it just means that the maximum number of items in this menu is to be limited to the number used in the previous string i.e. two menu items, here.

At the moment “MyApp” doesn’t know about the menu, all we have done is set up its definition in memory.

Pressing the <menu> button
Here is where we first introduce a user-function with parameters - one of the most powerful features of Dr Wimp and what sets it apart from being ‘just another library’.

Using an application produced with Dr Wimp, whenever <menu> (the middle button) is pressed over a window belonging to the application (including the iconbar, which is a special window) the DrWimp library automatically calls the user-function:

FNuser_menu(window%,icon%,screenx%,screeny%)

whose definition is in the !RunImage i.e. DEF FNuser_menu().

Moreover, whenever this call is made, the parameters in the user-function (window%, icon%, screenx% and screeny%) are automatically filled, by Dr Wimp, with the current appropriate values. Thus, in our !MyApp example, if you press <menu> over the iconbar icon, FNuser_menu will be called with the iconbar window handle in the parameter window%.

Similarly, if we pressed <menu> over a particular icon in an ordinary window, then FNuser_menu would be called with the window handle in window% and the icon handle (the icon number) in icon%. (If <menu> is pressed over a window but not over an icon i.e. over the window background, the parameter icon% would be set to ­1.).

And, in all cases, the parameters screenx% and screeny% will contain the x/y position of the mouse pointer when the mouse-click took place - in ‘screen’ coordinates (see later).

In order to display a menu when <menu> is pressed over a particular window/icon combination, we simply have to change DEF FNuser_menu to return the handle of the menu that we want to open, otherwise return a 0.

It is easier done than explained! So, move down to DEF FNuser_menu in the !RunImage and change it to:

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

To ensure you understand the sequence of events properly in this first look at this type of user­function, let’s detail what will now happen, step-by-step:

i) The user presses <menu> over the iconbar icon;
ii) DrWimp automatically calls
FNuser_menu
with the parameters
window%
,
icon%
,
screenx%
and
screeny%
set, respectively, to the window and icon handles over which the <menu> mouse-click took place, plus the mouse x/y values. Thus, here,
window%
will contain the iconbar window handle (-2).
iii) DEF FNuser_menu has been altered by you to return the menu handle iconbarmenu% (whose definition you have already created) when window%=iconbar%, so DrWimp will receive this returned handle and duly display the particular menu you want.
Note that in all other circumstances the ‘default return’ value of 0 is returned and Dr Wimp will ‘do nothing’.

In this iconbar case the values in icon%,
screenx%
and
screeny%
are irrelevant - because there is only one icon-per-application on the iconbar and therefore its window handle is sufficient identity within the application. But in general, as we will see, other CASE statements (and/or IF constructs) could be added to pinpoint precise window/icon/mouse position combinations. In other words, we use the CASE statements as a ‘filter’.

Using Dr Wimp, the user-functions with parameters are the main focus of the programmer and they all operate in a similar way to the one described above - so it is very important for you to understand their role.

Try running the !MyApp application now. The iconbar menu will duly appear if <menu> is pressed over the iconbar icon.


Selecting a menu item
OK, the menu is displayed, but selecting any of its items does nothing yet.

When a menu item is selected, DrWimp automatically calls another user-function:

PROCuser_menuselection(menu%,item%,font$)

As before, the parameters menu% and item% tell you which menu and which item from it has been selected. (Ignore font$ for now. We return to it later - in Section 2.18.) This time, the user-function is a PROC, so nothing is returned. Instead you only have to act on the selection made by the user.

Therefore, if the ‘Quit’ item is chosen from our iconbar menu, PROCuser_menuselection will be automatically called with menu% containing the iconbar menu handle (iconbarmenu%) and item% containing 2. (The top-most item is number 1.)

So, to respond to this selection, change PROCuser_menuselection to look like:

DEF PROCuser_menuselection(menu%,item%,font$)
CASE menu% OF
         WHEN iconbarmenu%
         CASE item% OF
                  WHEN 2 : PROCwimp_quit(0)
         ENDCASE
ENDCASE
ENDPROC

Thus, when we select ‘Quit’ from our iconbar menu - and only in that case - we call PROCwimp_quit with an argument of 0. This wimp-function call quits the application.

If you now resave and run the application you will be able to confirm that it does indeed quit when you select ‘Quit’.


Try adding some more items when creating the menu. Don’t forget to increase the “2” (the ‘Quit’ item) in PROCwimp_menuselection accordingly though! For instance, try getting the computer to make a beep when you select one of the items. VDU7 would be ideal for this. Note that there is no need to change the last parameter (0) in FNwimp_createmenu (and we will return to this later). Menus may also be created automatically from arrays and message files. See Section 2.18 for details.

Before moving on, note that displaying the menu and making a selection from it were handled by two independent programming actions. We were able to check that the menu was displayed OK before tackling what to do with it. This is typical of wimp programming: features are added by smallish self-contained routines. This has considerable advantages for the programmer, who can (largely) thoroughly check one step before proceeding to the next - and go back and change one step with clear interfaces to the preceding and following steps.




Top of page        Back to Contents        Previous        Next