AddAppMenuItemA

add a menu item to Workbench's list (V36) of AppMenuItems.

Attempt to add the text as a menu item to Workbench's list of AppMenuItems (the 'Tools' menu strip).

id

this variable is strictly for your own use and is ignored by Workbench. Typical uses in C are in switch and case statements, and in assembly language table lookup.

userdata

this variable is strictly for your own use and is ignored by Workbench.

text

text for the menu item (char *); starting with V44, any menu label consisting entirely of '-', '_' or '~' characters will result in a separator bar to be added in place of a textual item.

msgport

pointer to message port Workbench will use to send you an AppMessage message of type 'MTYPE_APPMENUITEM' when your menuitem gets selected.

taglist

ptr to a list of tag items. Must be NULL for V2.0.

WBAPPMENUA_CommandKeyString (STRPTR)

Command key to assign to this AppMenu. This must be a NUL-terminated string. If the string is empty, it will be ignored. Also, if the command key is already in use by a different menu item it will be ignored, too. In any case, only the first character of the string will be used (V44).

This tag defaults to NULL.

WBAPPMENUA_GetKey (ULONG *)

To add menus with sub menu items, you need to add a menu item first which the sub items will be added to later. In order to do this, add the item the sub items should be attached to and use the WBAPPMENUA_GetKey tag to obtain a key value. This key value is to be used later with the WBAPPMENUA_UseKey tag (V44).

This feature was introduced in workbench.library 44.1511, it does not work in any of the older Workbench releases.

This tag defaults to NULL.

WBAPPMENUA_GetTitleKey (ULONG *)

To add new entries to the Workbench menu strip you first need to create a new title to which the new menu items can be attached later. To do this, first create a new menu entry and use the WBAPPMENUA_GetTitleKey tag to obtain a key value. This key value is to be used later with the WBAPPMENUA_UseKey tag (V45).

This tag defaults to NULL.

WBAPPMENUA_UseKey (ULONG)

When adding a menu item with the WBAPPMENUA_UseKey tag, using a key value obtained by a previous invocation of AddAppMenuItemA(), the new menu item will be added as a sub item (V44).

If the key you provide was obtained via the WBAPPMENUA_GetTitleKey tag, then the item you add will be attached to the respective menu entry (V45).

This tag defaults to NULL.

AppMenuItem

a pointer to an appmenuitem structure which you pass to RemoveAppMenuItem when you want to remove the menuitem from Workbench's list of AppMenuItems. NULL if workbench was unable to add your menu item; typically happens when Workbench is not running or under low memory conditions.

Starting with V44 NULL will be returned if you attempt to add an AppMenu item to a menu which already contains 63 menu items.

For this function call to succeed, Workbench must be open. This means that the LoadWB command was executed and the Workbench screen has been opened.

You can add only a maximum of 62 menu items to the "Tools" menu. Only a maximum of 31 sub items can be added to a menu item.

When you add a new menu item which sub items should be attached to, the new menu item will not appear until after the first sub item has been attached. The same is true when adding new menu entries to the Workbench menu strip; titles will not appear until you add the first menu item.

You can add only a maximum of 27 menu entries to the Workbench menu strip. Only a maximum of 63 menu items can be added to a menu entry.

RemoveAppMenuItem()

workbench.library V37 through V40 does not limit the number of menu items to 63. Any menu items after the 63rd will not be selectable. This bug was fixed in V44.