addToolButton

 

6.0

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.

Parameters

 

cName	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.
oIcon	An Icon Stream object. Beginning with Acrobat 7.0, this parameter is optional if a cLabel is provided.
cExec	The expression string to evaluate when the button is selected.
cEnable	(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.
cMarked	(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.
cTooltext	(optional) The text to display in the button help text when the mouse is over the toolbutton. The default is not to have a tool tip. Note: Avoid the use of extended characters in the cTooltext string as the string may be truncated.
nPos	(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.
cLabel	(optional, Acrobat 7.0) A text label to be displayed on the button to the right of the icon. The default is not to have a label.

Returns

undefined

Example

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

	myDoc.closeDoc(true);

	// add a toolbutton

	app.addToolButton({

		cName: "myToolButton",

		oIcon: oIcon,

		cExec: "app.alert('Someone pressed me!')",

		cTooltext: "Push Me!",

		cEnable: true,

		nPos: 0

	});

	app.removeToolButton("myToolButton")

See also the example following util.iconStreamFromIcon.

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/acrobat_sdk/9.1/Acrobat9_1_HTMLHelp/JS_API_AcroJS.88.134.html

Add Comment