SETMENU Mnemonic - Set or Replace Menu

Syntax

'SETMENU', menu_string$

Description

For BBj-specific information, see the SETMENU Mnemonic.

The 'SETMENU' mnemonic replaces the current window's menu with the menu defined in menu_string$|data. The window must have been created with the $0800$ (Enable Menus) flag, or this mnemonic will generate an !ERROR=29.

menu_string$ is a string that defines the menu hierarchy. Each menu item is defined with one line of text in this string. The items are separated with linefeeds ($0A$). Each item defines four parameters, which are separated by commas. The parameters are:

"title,{tag{,accelerator{,flags{,name}}}}"

All parameters except title may be empty, but all commas must be present for each item that is not empty. A comma is not needed at the end of an item, if the item is the last non-empty item, except for the title, which requires a comma after it.

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 of 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 hot key. 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 values 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$, an accelerator is not 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. But, in place of the control ID use the negative of the menu item's tag.

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$
`Cmd` + `Shift`	$9000$
`Cmd` + `Ctrl`	$A000$
`Cmd` + `Shift` + `Ctrl`	$B000$
`Cmd` + `Alt`	$C000$
`Cmd` + `Shift` + `Alt`	$D000$
`Cmd` + `Ctrl` + `Alt`	$E000$
`Cmd` + `Shift` + `Ctrl` + `Alt`	$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 example shows how to build a string and display it as a menu. The top-level menu items are "File" and "Regions", and each contains submenus:

sysgui = unt
open (sysgui)"X0"
print (sysgui)'window'(100,100,350,100,"setmenu",$00090883$)
menu$="File,1,,"+$0a$
menu$=menu$+" &New,2,," +$0a$
menu$=menu$+" separator,3,,S" +$0a$
menu$=menu$+" E&xit,4,$0151$," +$0a$
menu$=menu$+"&Regions,5,," +$0a$
menu$=menu$+" Western,6,," +$0a$
menu$=menu$+" &Los Angeles,7,,C" +$0a$
menu$=menu$+" &Seattle,8,,U" +$0a$
menu$=menu$+" Eastern,9,," +$0a$
menu$=menu$+" &Boston,10,," +$0a$
menu$=menu$+" New &York,11,,D" +$0a$
menu$=menu$+" &Philadelphia,12,," +$0a$
menu$=menu$+$0a$
print (sysgui) 'setmenu', menu$
dim event$:tmpl(sysgui)
repeat
readrecord(sysgui,siz=10)event$
print event.code$,event.id,event.flags,event.x,event.y
until event.code$="X"
release

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, they are indented one more space, and so on. Tabs may not be used. The whole group is terminated by two $0A$ characters.