Autodocs
Libraries:
workbench.library
AddAppIconA
AddAppMenuItemA
AddAppWindowA
AddAppWindowDropZoneA
ChangeWorkbenchSelectionA
CloseWorkbenchObjectA
MakeWorkbenchObjectVisibleA
OpenWorkbenchObjectA
RemoveAppIcon
RemoveAppMenuItem
RemoveAppWindow
RemoveAppWindowDropZone
UpdateWorkbench
WBInfo
WorkbenchControlA
Include
GuruMeditation
|
Docs » Autodocs » workbench.library » AddAppMenuItemA
AddAppMenuItemA - add a menu item to Workbench's list (V36)
of AppMenuItems.
AppMenuItem = AddAppMenuItemA(id, userdata, text, msgport, taglist)
D0 D0 D1 A0 A1 A2
struct AppMenuItem *AddAppMenuItemA(ULONG, ULONG, char *,
struct MsgPort *,
struct TagItem *);
Alternate, varargs version:
struct AppMenuItem *AddAppMenuItem(ULONG, ULONG, char *,
struct MsgPort *,
tag1, data1,
tag2, data2,
...
TAG_END );
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 15 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.
Here is how you create a menu item with two sub items attached:
struct MsgPort * port;
struct AppMenuItem * item;
struct AppMenuItem * sub1;
struct AppMenuItem * sub2;
ULONG key;
/* IMPORTANT: you *must* initialize the key to zero
* for backwards compatibility!
*/
key = 0;
item = AddAppMenuItem(0,0,"AppMenu item with two sub items",port,
WBAPPMENUA_GetKey,&key,
TAG_DONE);
/* IMPORTANT: always check for the key value to be non-zero! */
if(key != 0 && item != NULL)
{
sub1 = AddAppMenuItem(0,0,"Sub item #1",port,
WBAPPMENUA_UseKey,key,
TAG_DONE);
sub2 = AddAppMenuItem(0,0,"Sub item #2",port,
WBAPPMENUA_UseKey,key,
TAG_DONE);
/* ... do something useful with the menus ... */
RemoveAppMenuItem(sub1);
RemoveAppMenuItem(sub2);
}
RemoveAppMenuItem(item);
workbench.library/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.
|
