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.