a1200   NEWS   APPS   DOCS   ABOUT
a1200
----
a1200
----
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

NAME

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

SYNOPSIS

	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 );

FUNCTION

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

INPUTS

	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.

TAGS

	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.

RESULT

	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.

NOTES

	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.

EXAMPLE

	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);

SEE ALSO

workbench.library/RemoveAppMenuItem()

BUGS

	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.

Comments

Name:
E-mail: Use this if you want a message if you get a response, will not be shown.
Comment:
Select correct short for:

Fairlight

FLT
RZR
FC
ATX

Comments:

$VER: d0.se 1.14 Copyright © 2011-2020 Tobias Geijersson support at d0 dot se