JavaScript > JavaScript for Acrobat API Reference > JavaScript API > app > app methods > addMenuItem

addMenuItem
 
S
Adds a menu item to a menu.
Note: This method can only be executed during application initialization or console events. See the event object for a discussion of JavaScript events.
See also the addSubMenu, execMenuItem, hideMenuItem, and listMenuItems methods.
Parameters
 
The language-independent name of the menu item. This name can be used by other methods (for example, hideMenuItem) to access the menu item.
(optional) The position within the submenu to locate the new menu item. The default behavior is to append to the end of the submenu. Specifying nPos as 0 adds the menu to the top of the submenu. Beginning with Acrobat 6.0, the value of nPos can also be the language-independent name of a menu item.
(Acrobat 6.0) If the value nPos is a string, this string is interpreted as a named item in the menu (a language-independent name of a menu item). The named item determines the position at which the new menu item is to be inserted. See bPrepend for additional details.
The nPos parameter is ignored in certain menus that are alphabetized. The alphabetized menus are
Note: When nPos is a number, nPos is not obeyed in the Tools menu. A menu item introduced into the Tools menu comes in at the top of the menu. nPos is obeyed when it is a string referencing another user-defined menu item.
(optional) An expression string that is evaluated to determine whether to enable the menu item. The default is that the menu item is always enabled. This expression should set event.rc to false to disable the menu item.
(optional) An expression string that determines whether the menu item has a check mark next to it. The expression should set event.rc to false to uncheck the menu item and true to check it. The default is that the menu item is not marked.
(optional, Acrobat 6.0) Determines the position of the new menu item relative to the position specified by nPos. The default value is false. If bPrepend is true, the rules for insertion are as follows:
If nPos is a string, the new item is placed before the named item.
If nPos is a number, the new item is placed before the numbered item.
If the named item cannot be found or nPos is not between zero and the number of items in the list, inclusive, the new item is inserted as the first item in the menu (rather than at the end of the menu).
bPrepend is useful when the named item is the first item in a group.
Example 1
At the top of the File menu, add a menu item that opens an alert dialog box displaying the active document title. This menu is only enabled if a document is opened.
	app.addMenuItem({ cName: "Hello", cParent: "File",
		cExec: "app.alert(event.target.info.title, 3);",
		cEnable: "event.rc = (event.target != null);",
		nPos: 0
	});
Example 2 (Acrobat 6.0)
Place two menu items in the File menu, one before the Close item and the other after the Close item.
	// Insert after the "Close" item (the default behavior)
	app.addMenuItem( { cName: "myItem1", cUser: "My Item 1", cParent:
		"File", cExec: "_myProc1()", nPos: "Close"});
	// Insert before the "Close" item, set bPrepend to true.
	app.addMenuItem( { cName: "myItem2", cUser: "My Item 2", cParent:
		"File", cExec: "_myProc2()", nPos: "Close", bPrepend: true });