Menu format - %mn[menu_specification]

In this section:

%mn (Menu) is used to attach a menu to the window. This is best illustrated by an example:

+         cb1,cb2,cb3,cb4,cb5)

This format specifies five selectable items, three of which, Beta1, Beta2, and Beta3 are contained in a drop-down menu. A bar symbol ( | ) between Beta2 and Beta3 causes a separator to be drawn in the drop-down menu. The three top-level menu items (Alpha, Beta and Gamma) can be selected using accelerator keys Alt-A, Alt-B and Alt-G that are specified by the inclusion of the ampersand character (&) placed to the left of the character chosen to be the (unique) accelerator for this menu (a double ampersand (&&) is required if you want an ampersand to appear in the text). Five call-back functions are required as arguments corresponding to each selectable menu item. A call-back function is called when the corresponding menu item is selected.

Individual menu items may also be greyed (so that they are visible, but not usable). In order to grey an item, prefix its name with a tilde (~) and insert an INTEGER argument to provide a control integer. When the value of this integer is zero, the item is greyed and disabled, otherwise it is enabled. Note that it is not necessary to use a different control integer for every item. You can use one integer to control several menu items and/or buttons. The following example illustrates a 3-item menu, in which the middle item is greyed:

      INCLUDE <windows.ins>
      INTEGER drinker
      EXTERNAL squash_func,beer_func,tea_func
c---- call back function ---
      INTEGER FUNCTION squash_func()

The hash character (#) is used to control the placement of a check mark (tick) at the front of a menu item. The corresponding control variable is set to the value 1 in order to display a check mark otherwise it is set to zero. Top level menu items cannot be checked.

The caret character (^) can be used before the menu text to indicate that a callback function will be supplied to control the greying and checking of the item. This is an alternative to supplying control variables for # and (or) ~ modifiers. The callback, which is placed before the regular menu callback is called before the menu is displayed. It should return 1 to enable the item, 0 to disable. If the menu item is to be checked then it should add 2 to the return value. In essence bit zero controls whether the menu item is enabled and bit one whether it is checked. For example:

!!! Return zero to grey/disable the menu item, 1 to enable.
!!! Add 2 to the return value in order to make the item checked.
saveState = 1

i = winio@("%mn[[^Save]]",save_state, save_cb)

As an alternative to using the ampersand (&) before a character, an accelerator key may also be associated with a menu item and its corresponding call-back function as illustrated in the following example.


The caret symbol ^ is used here as an alias for the tab character (CHAR(9)) and is followed by the key name. Valid key names are illustrated with the accelerator key format %ac (Accelerator Key) below. The use of an accelerator key is is only permitted in sub-menus and should not be used in top level menus.

In order to continue a menu in a new winio@ statement, it is necessary to match opening square brackets with closing brackets on the line to be continued. Then use an appropriate number of opening square brackets on the next line. For example:


is equivalent to


Help strings are provided by inserting a question mark (%?mn). All the strings are placed in order at the end of the format description, one for each item that has a call-back function. For example,

 i=winio@('%?mn[File[New]][Start a new file]&',newfn)
 i=winio@('%?mn[[Save]][Save this file]',savefn)

You can provide help strings that vary if the menu item is greyed. To do this start the help string with a pipe symbol '|' and use another to separate the initial enabled state from greyed. For example:

 iw = winio@('%?mn[[~Save]][|Save is enabled|Save is disabled]&',doSave,savefn)

Separators also require a help string but this is not used.

See also: Dynamic Menus



Copyright © 1999-2024 Silverfrost Limited