MENU ADD STRING statement

Purpose | Add a string or separator to an existing menu.
Syntax | MENU ADD STRING, hMenu, txt$, id&, state& [, AT [BYCMD] position&] [, CALL callback]
Remarks | A string may contain an optional command accelerator key, and also describe an equivalent keyboard accelerator combination.
hMenu | Handle of the parent menu to which the string should be added.

txt$

Text to display in the parent menu. An ampersand (&) may be used in the string to make the following letter into a command accelerator (hot-key). The letter is underscored to signify that it is an accelerator. To create a horizontal separator instead of a text string, set txt$ = "-", id& = 0, state& = 0.

Keyboard accelerators, as described in the ACCEL ATTACH statement, can be indicated in the text of a menu item, for the reference of the user. To include a keyboard accelerator description in a menu string, separate it from the menu item text with a $TAB { CHR$(9)} character. For example:

MENU ADD STRING, hMenu, "Cu&t" & $TAB & "CTRL+X", id&, mstate&

id& | The unique numeric identifier for the menu item. When a menu item is selected, id& is sent to the parent dialog Callback Function to notify the dialog which option was selected.

state&

The initial state of the menu item. It can be one or more of the following, combined together with the OR operator to form a bitmask:

%MFS_CHECKED | Place a checkmark next to the item.
%MFS_DEFAULT | The default menu item, displayed in bold. Only one item may be the default.
%MFS_DISABLED | Disable the menu item so that it cannot be selected.
%MFS_ENABLED | Enable the menu item so that it can be selected.
%MFS_GRAYED | Disable the menu item so that it cannot be selected, and draw it in a "grayed" state to indicate this.
%MFS_HILITE | Highlight the menu item.
%MFS_UNCHECKED | Do not place a checkmark next to the item.
%MFS_UNHILITE | Item is not highlighted.

A state value of zero (0) provides %mfs_enabled, %mfs_unchecked, and %mfs_unhilite.

position& | Optional position in the parent menu, where the menu item should be inserted. If the BYCMD option is used, the menu item is inserted prior to the menu item ID specified by position&. Otherwise, the menu item is inserted at the physical position& within the parent menu, where position& = 1 for the first position, position& = 2 for the second, and so on. If position is not specified then the popup menu is appended to the end of the menu.
callback | Optional name of a Callback Function that will be called when the menu item is selected. This callback will be ignored when used with MENU CONTEXT as it returns the id of the selected menu item.
Restrictions | The application must call the MENU DRAW BAR statement whenever a menu changes, whether or not the menu is in a displayed dialog.
See also | Dynamic Dialog Tools, ACCEL ATTACH, Menus, MENU ADD POPUP, MENU ATTACH, MENU CONTEXT, MENU DELETE, MENU DRAW BAR, MENU GET STATE, MENU GET TEXT, MENU NEW BAR, MENU NEW POPUP, MENU SET STATE, MENU SET TEXT
Example | See Menu Example.