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

Adds a button to the “Add-on” toolbar of Acrobat.
If there is an active document (for example, docA.pdf) open in Acrobat when this method is called to add a button, Acrobat will remove the button when docA.pdf is either no longer active or is closed. In the former case, the button will be automatically added to the toolbar if docA.pdf becomes the active document again.
The icon size is restricted to 20 by 20 pixels. If an icon of larger dimensions is used, an exception is thrown.
Note: (Acrobat 7.0) A number of changes have been made with regard to the secure use of this method. Execution of addToolButton in the console and application initialization is considered privileged execution and is trusted.
If this method is called from nonprivileged script, the warning “JavaScript Window” appears on the “Add-on” toolbar, which will not be dockable. (See Privileged versus non-privileged context.)
See also removeToolButton.
A unique language-independent identifier for the button. The language-independent name is used to access the button for other methods (for example, removeToolButton).
Note: The value of cName must be unique. To avoid a name conflict, check listToolbarButtons, which lists all toolbar button names currently installed.
An Icon Stream object.
(optional) An expression string that determines whether to enable the toolbutton. The default is that the button is always enabled. This expression should set event.rc to false to disable the button.
(optional) An expression string that determines whether the toolbutton is marked. The default is that the button is not marked. This expression should set event.rc to true to mark the button.
Note: Avoid the use of extended characters in the cTooltext string as the string may be truncated.
(optional) The button number to place the added button before in the toolbar. If nPos is -1 (the default), the button is appended to the toolbar.
Create a button from an icon graphic on the user’s hard drive. This script is executed from the console.
	// Create a document
	var myDoc = app.newDoc();
	// import icon (20x20 pixels) from the file specified 
	myDoc.importIcon("myIcon", "/C/myIcon.jpg", 0);
	// convert the icon to a stream.
	oIcon = util.iconStreamFromIcon(myDoc.getIcon("myIcon"));
	// close the doc now that we have grabbed the icon stream
	// add a toolbutton
		cName: "myToolButton",
		oIcon: oIcon,
		cExec: "app.alert('Someone pressed me!')",
		cTooltext: "Push Me!",
		cEnable: true,
		nPos: 0
See also the example following util.iconStreamFromIcon.