Menus

For BBj-specific information, see Menus - BBj.

Menus list commands available to the user and are contained within a menu bar, a special area displayed across the top of a window directly beneath the title bar. A window created with the $00000800$ (Include Default Menu Bar) flag makes it possible to create and display a custom menu. The 'SETMENU' mnemonic is used to replace the window's default menu bar with a custom menu. If the 'SETMENU' mnemonic is used on a window that does not have the $00000800$ flag set, an !ERROR-29 - Mnemonic Error is issued.

Each menu item in the menu is defined by a line of text separated by commas into four fields. All fields except title can be empty, but all commas must be present.

title,{tag},{accelerator},{flags}

Parameter	Description
title	Menu title text, which can contain spaces but cannot begin with a space or contain a comma. If a comma in a menu item title is required, create the menu with a different title and use the 'TITLE' mnemonic to change the title. The comma can be a concern if the menu returned by CTRL(x,0,6) is parsed. Including the "&" symbol before a letter in the title designates the letter as a menu mnemonic. It allows the item to be activated when the letter is pressed, but only if the menu is displayed and has keyboard focus. In the menu, the letter is automatically underlined, indicating which key the user must press. For example, entering &New as the title of a menu item allows it to be activated by pressing the letter N, once the menu containing it has been activated.
tag	Numerical ID, a positive number in decimal form between 1 and 32767. Do not use the values 32000 through 32767, except as follows:
	ID Function
	32027 Clipboard "Cut"
	32028 Clipboard "Copy"
	32029 Clipboard "Paste"
	A tag can have the same number as a control or child window in the same context because the negative of the tag is used with the various mnemonic and CTRL() functions. The same tag can also be used in more than one window. Using the same tag more than once in the same menu will not cause an error, but will make it impossible to determine which selection was made.
accelerator	Hexadecimal value delimited by dollar signs, listed in the table below. Accelerators make it possible to activate a menu item without requiring the menu containing it to be activated. For example, entering $014B$ designates the `F1` key as accelerator key, and causes "F1" to appear in the menu to the right of the title. If an accelerator is omitted or assigned the value $00$, no accelerator is assigned to the item.
flags	Menu flags, as follows:
	Flag Description
	C Sets the menu item to be checkable and initially checked.
	D Sets the menu item to be initially disabled.
	S Menu item separator. Title and hot key are ignored.
	U Sets the menu item to be checkable and initially unchecked.

The 'CHECK', 'DISABLE', 'ENABLE', 'TITLE', and 'UNCHECK' mnemonics can also be used with menus. In using these mnemonics with menus, the negative of the menu item's tag is used in place of the control ID.

Accelerator and Combination Key Values

Accelerator Key Values

The following key values can be used for menu accelerators, and are identical to the key values returned when Keypress "t" Events are enabled in a window:

Key	Hex Value
`Delete`	$007F$
`Up arrow`	$012D$
`Down arrow`	$012E$
`Right arrow`	$012F$
`Left arrow`	$0130$
`Page up`	$0131$
`Page down`	$0132$
`Home`	$0133$
`End`	$0134$
`Insert`	$0138$
`Backtab`	$013B$
`Keypad 0` (numeric keypad with Num Lock off)	$013E$
`Keypad 1`	$013F$
`Keypad 2`	$0140$
`Keypad 3`	$0141$
`Keypad 4`	$0142$
`Keypad 5`	$0143$
`Keypad 6`	$0144$
`Keypad 7`	$0145$
`Keypad 8`	$0146$
`Keypad 9`	$0147$
`F1`	$014B$
`F2`	$014C$
`F3`	$014D$
`F4`	$014E$
`F5`	$014F$
`F6`	$0150$
`F7`	$0151$
`F8`	$0152$
`F9`	$0153$
`F10`	$0154$
`F11`	$0155$
`F12`	$0156$
`F13` (BBj 19.10+)	$0157$
`F14` (BBj 19.10+)	$0158$
`F15` (BBj 19.10+)	$0159$
`F16` (BBj 19.10+)	$015A$
`F17` (BBj 19.10+)	$015B$
`F18` (BBj 19.10+)	$015C$
`F19` (BBj 19.10+)	$015D$
`F20` (BBj 19.10+)	$015E$
`F21` (BBj 19.10+)	$015F$
`F22` (BBj 19.10+)	$0160$
`F23` (BBj 19.10+)	$0161$
`F24` (BBj 19.10+)	$0162$
`Keypad ` ( on numeric keypad)	$0174$
`Keypad -` (- on numeric keypad)	$0175$
`Keypad +` (+ on numeric keypad)	$0176$
`Keypad /` (/ on numeric keypad)	$0177$

Combination Key Values

To include Shift, Ctrl, Alt and/or Cmd key combinations in accelerators, add the following values to the base key number:

Combination	Hex Value
`Shift`	$1000$
`Ctrl`	$2000$
`Shift` + `Ctrl`	$3000$
`Alt`	$4000$
`Shift` + `Alt`	$5000$
`Ctrl`+ `Alt`	$6000$
`Shift` + `Ctrl` + `Alt`	$7000$
`Cmd`	$8000$
`Shift` + `Cmd`	$9000$
`Ctrl` + `Cmd`	$A000$
`Shift` + `Ctrl` + `Cmd`	$B000$
`Alt` + `Cmd`	$C000$
`Shift` + `Alt` + `Cmd`	$D000$
`Ctrl` + `Alt` + `Cmd`	$E000$
`Shift` + `Ctrl` + `Alt` + `Cmd`	$F000$

Alt key combinations are only available in Visual PRO/5 Rev. 2.0x and later.

Cmd key combinations are only available in macOS (BBj).

For example, the following identifies the values for the possible combinations to be used with the F1 key (value $014B$):

Combination	Hex Value
`Shift` + `F1`	$114B$
`Ctrl` + `F1`	$214B$
`Shift` +`Ctrl` + `F1`	$314B$
`Alt` + `F1`	$414B$
`Shift` + `Alt` + `F1`	$514B$
`Ctrl` + `Alt` + `F1`	$614B$
`Shift` + `Ctrl` + `Alt` + `F1`	$714B$
`Cmd` + `F1`	$814B$
`Cmd` + `Shift` + `F1`	$914B$
`Cmd` + `Ctrl` + `F1`	$A14B$
`Cmd` + `Shift` + `Ctrl` + `F1`	$B14B$
`Cmd` + `Alt` + `F1`	$C14B$
`Cmd` + `Shift` + `Alt` + `F1`	$D14B$
`Cmd` + `Ctrl` + `Alt` + `F1`	$E14B$
`Cmd` + `Shift` + `Ctrl` + `Alt` + `F1`	$F14B$

Example

The following data string is used to create a menu bar that contains File and Finance menu items, each containing submenus.

menu$="File,1,,"+$0a$
menu$=menu$+" &New,2,," +$0a$
menu$=menu$+" separator,3,,S" +$0a$
menu$=menu$+" E&xit <F7>,4,$3151$," +$0a$
menu$=menu$+"&Finance,5,," +$0a$
menu$=menu$+" Western Division,6,," +$0a$
menu$=menu$+" Seattle,7,,C" +$0a$
menu$=menu$+" San Fransisco,8,,U" +$0a$
menu$=menu$+" Eastern Division,9,," +$0a$
menu$=menu$+" Atlanta,10,," +$0a$
menu$=menu$+" Boston,11,,D" +$0a$
menu$=menu$+" Philadelphia,12,," +$0a$
menu$=menu$+$0a$
print (sysgui) 'setmenu' menu$

In the data string, indentation is used to describe the hierarchy. Items in the menu bar are not indented. Items in the menus that drop from the menu bar are indented one space. If any items of the dropped menus have submenus, the submenus are indented one more space, and so on. Tabs may not be used. The whole group is terminated by two $0A$ characters.