Enhanced menus

In this section:

• Menu format - %mn[menu_specification]
• Dynamic Menus
• Popup menu - %pm[menu_specification]
• System menu - %sm[menu_specification]
• Enhanced menus and New Enhanced menus - %em
• Accelerator key format - %ac[key]

See New enhanced menus for a simpler alternative.

A ClearWin+ window can have an enhanced standard menu (%`mn) as an alternative to a standard (%mn (Menu)) menu. Enhanced popup menus (%`pm) are also available. An enhanced menu has more possibilities such as bitmap entries and is more flexible for programs that update menus on the fly or read them from configuration files. Any window can be given either a normal menu or an enhanced menu.

%`mn and %`pm each take one character argument, that describes the entire menu, and one call-back function that is used for all menu events.

Example

INTEGER i,winio@,cbfunc
EXTERNAL cbfunc
CHARACTER*256 fmt
fmt='[File[-bm[openbmp],-se,E&xit],Help[About]]'
i=winio@('%`mn',fmt,cbfunc)
END
!-------------------------------------------------------
INTEGER FUNCTION cbfunc()
INCLUDE <windows.ins>
CHARACTER*16 menuitem
menuitem=clearwin_string@('CURRENT_MENU_ITEM')
cbfunc=1
IF(menuitem.EQ.'File~Exit') cbfunc=0
END
!-------------------------------------------------------
RESOURCES
openbmp BITMAP open.bmp

The character string fmt illustrates a typical enhanced menu definition:

fmt='[File[-bm[openbmp],-se,E&xit],Help[About]]'

Here the '&' character performs the same accelerator key function as for standard menus. Special options preceded by a minus sign are available as follows:

Notice that sub-menus are specified using nested square brackets - just as they are for standard menus.

The call-back function is invoked when the user selects a menu event. This function uses CLEARWIN_STRING@('CURRENT_MENU_ITEM') to determine which event is required. In the given example, when the user selects 'Exit' the string 'File~Exit' is returned. Strings are separated by a tilde '~' character and any '&' characters in the menu names are left in place. In the given example, selecting 'Open' generates 'File~openbmp'. (Menu items often represent recently opened files. File names might contain tilde '~' characters, however no ambiguity will occur because such items will always appear in terminal positions in the menu tree structure.)

Newline and carriage return characters are ignored between menu items. This means that a menu structure can conveniently be defined in a text file, read in and presented as an enhanced menu.

If an enhanced menu is to be altered (whether it be to alter the grey/check status of an item, or to add/remove entries etc.) the menu is simply replaced using one of the calls:

CALL REPLACE_ENHANCED_MENU@(HANDLE, MENU)
CALL REPLACE_ENHANCED_POPUP_MENU@(HANDLE, MENU)

where HANDLE is an integer (kind=7) that is the (%hw (Handle)) window handle of the parent window and MENU is the replacement character argument. HANDLE can be zero, in which case the most recently created window is updated. It is an error to call these routines for a window that does not use %`mn or %`pm.