Doc methods

addAnnot

Creates an Annotation object having the specified properties. Properties not specified are given their default values for the specified type of annotation.

Note:(Acrobat 8.0) The behavior of addAnnot is changed in the case the author property is unspecified. If addAnnot is executed in an unprivileged context, the default value of author is the string undefined; if addAnnot is executed in an privileged context, the default value of the author property is the login name of the current user.

Parameters

Returns

The new Annotation object.

Example 1

This minimal example creates a square annotation.

   var sqannot = this.addAnnot({type: "Square", page: 0});

sqannot will be created as a square annotation on the first page (using 0-based page numbering).

Example 2

Add a Text annotation with various properties.

   var annot = this.addAnnot

   ({

      page: 0,

      type: "Text",

      author: "A. C. Robat",

      point: [300,400],

      strokeColor: color.yellow,

      contents: "Need a little help with this paragraph.",

      noteIcon: "Help"

   });

Example 3

Add a Square annotation with various properties.

   var annot = this.addAnnot({

      page: 0,

      type: "Square",

      rect: [0, 0, 100, 100],

      name: "OnMarketShare",

      author: "A. C. Robat",

      contents: "This section needs revision."

});

Example 4

A fancy ink annotation in the shape of a three-leaf rose.

   var inch = 72, x0 = 2*inch, y0 = 4*inch;

   var scaledInch = .5*inch;

   var nNodes = 60;

   var theta = 2*Math.PI/nNodes;

   var points = new Array();

   for (var i = 0; i <= nNodes; i++) {

      Theta = i*theta;

      points[i] = [x0 + 2*Math.cos(3*Theta)*Math.cos(Theta)*scaledInch,

      y0 + 2*Math.cos(3*Theta)*Math.sin(Theta)*scaledInch];

   }

   var annot = this.addAnnot({

      type: "Ink",

      page: 0,

      name: "myRose",

      author: "A. C. Robat",

      contents: "Three leaf rose",

      gestures: [points],

      strokeColor: color.red,

      width: 1

   });

addField

Creates a new form field and returns it as a Field object.

Note:(Acrobat 6.0): Beginning with Acrobat 6.0, this method can be used from within Adobe Reader for documents with forms usage rights enabled. Prior to 6.0, it was not available from Adobe Reader.

Parameters

Returns

The newly created Field object.

Example

The following code might be used in a batch sequence to create a navigational icon on every page of a document, for each document in a selected set of documents.

   var inch = 72;

   for (var p = 0; p < this.numPages; p++) {

      // Position a rectangle (.5 inch, .5 inch)

      var aRect = this.getPageBox( {nPage: p} );

      aRect[0] += .5*inch;            // from upper left hand corner of page.

      aRect[2] = aRect[0]+.5*inch;    // Make it .5 inch wide

      aRect[1] -= .5*inch;

      aRect[3] = aRect[1] - 24;       // and 24 points high

   

      // Now construct a button field with a right arrow from ZapfDingbats

      var f = this.addField("NextPage", "button", p, aRect )

      f.setAction("MouseUp", "this.pageNum++");

      f.delay = true;

      f.borderStyle = border.s;

      f.highlight = "push";

      f.textSize = 0;                 // Auto-sized

      f.textColor = color.blue;

      f.fillColor = color.ltGray;

      f.textFont = font.ZapfD

      f.buttonSetCaption("\341")      // A right arrow

      f.delay = false;

   }

See the Field object setAction method for another example.

addIcon

Adds a new named Icon object to the document-level icon tree, storing it under the specified name.

See also icons, getIcon, importIcon, removeIcon, and the Field object methods buttonGetIcon, buttonImportIcon, and buttonSetIcon.

Parameters

Example

This example takes an icon already attached to a form button field in the document and assigns a name to it. This name can be used to retrieve the icon object with getIcon for use in another button, for example.

   var f = this.getField("myButton");

   this.addIcon("myButtonIcon", f.buttonGetIcon());

addLink

Adds a new link to the specified page with the specified coordinates, if the user has permission to add links to the document. See also getLinks, removeLinks and the Link object.

Parameters

Returns

The newly created Link object.

Example 1

Create simple navigational links in the lower left and right corners of each page of the current document. The link in lower left corner goes to the previous page; the one in the lower right corner goes to the next page.

   var linkWidth = 36, linkHeight = 18;

   for ( var i=0; i < this.numPages; i++)

   {

      var cropBox = this.getPageBox("Crop", i);

      var linkRect1 = [0,linkHeight,linkWidth,0];

      var offsetLink = cropBox[2] - cropBox[0] - linkWidth;

      var linkRect2 = [offsetLink,linkHeight,linkWidth + offsetLink,0]

      var lhLink = this.addLink(i, linkRect1);

      var rhLink = this.addLink(i, linkRect2);

      var nextPage = (i + 1) % this.numPages;

      var prevPage = (i - 1) % this.numPages;

      var prevPage = (prevPage>=0) ? prevPage : -prevPage;

      lhLink.setAction( "this.pageNum = " + prevPage);

      lhLink.borderColor = color.red;

      lhLink.borderWidth = 1;

      rhLink.setAction( "this.pageNum = " + nextPage);

      rhLink.borderColor = color.red;

      rhLink.borderWidth = 1;

   }

See the Link object for information on setting the properties and the action of a link.

Example 2

Search through the document for the word “Acrobat” and create a link around that word.

   for (var p = 0; p < this.numPages; p++)

   {

      var numWords = this.getPageNumWords(p);

      for (var i=0; i<numWords; i++)

      {

         var ckWord = this.getPageNthWord(p, i, true);

         if ( ckWord == "Acrobat")

         {

            var q = this.getPageNthWordQuads(p, i);

            // Convert quads in default user space to rotated

            // User space used by Links.

            m = (new Matrix2D).fromRotated(this,p);

            mInv = m.invert()

            r = mInv.transform(q)

            r=r.toString()

            r = r.split(",");

            l = addLink(p, [r[4], r[5], r[2], r[3]]);

            l.borderColor = color.red;

            l.borderWidth = 1;

            l.setAction("this.getURL('http://www.example.com/')");

         }

      }

   }

addRecipientListCryptFilter

Adds a crypt filter to the document. The crypt filter is used for encrypting Data objects.

See also the cCryptFilter parameter of the importDataObject, createDataObject, and setDataObjectContents methods.

Note:Can only be executed during a batch, application initialization or console event. See also Privileged versus non-privileged context.

Parameters

Example

This script encrypts the current document and embeds it into a PDF document.

   var Note = "Select the list of people that you want to send this"
      + " document to. Each person must have both an email address"
      + " and a certificate that you can use when creating the"
      + "envelope.";

   var oOptions = { bAllowPermGroups: false, cNote: Note,

      bRequireEmail: true };

   var oGroups = security.chooseRecipientsDialog( oOptions );

   var env = app.openDoc( "/c/temp/ePaperMailEnvelope.pdf" );

   env.addRecipientListCryptFilter( "MyFilter", oGroups );

   env.importDataObject( "secureMail0", this.path, "MyFilter" );

   var envPath = "/c/temp/outMail.pdf";

   env.saveAs( envPath );

Note:This script was executed in the console but is best executed as a folder JavaScript as part of a larger script for sending PDF documents securely.

addRequirement

Allows a PDF document to be authored so that a certain requirement is needed for the document to properly function in Acrobat.

When Acrobat opens a document containing a requirement, it will try to satisfy the requirement before allowing the user to freely interact with the document. If the requirement is not fulfilled, the application may limit the functionality of the document.

Note:This method can only be called from a console or batch event. See Privileged versus non-privileged context for details.

Parameters

Requirements enumerator object

This object lists all the possible types of requirements that a document may contain to properly function in Acrobat.

Requirement object

This generic object contains properties that describe the nature of the requirement

ReqHandler object

This generic object contains information about a requirement handler that can be used when Acrobat finds an unrecognized requirement. The viewer should delegate requirement checking for the unrecognized requirement to the first handler in the array that supports the type. If no requirement handler can be found to deal with the unrecognized requirement, a generic message should be provided by the viewer.

ReqHandlers Enumerator object

This object enumerates the types of requirement handlers a document may contain.

Example

Add a requirement to enable JavaScript in a document.

   addRequirement(this.requirements.EnableJavaScripts,

      {[{cType: reqHandlers.JS, cScriptName: "requirement"}]});

addScript

Sets a document-level script for a document. See also setAction, setPageAction, the Bookmark object setAction method, and the Field object setAction method.

Note:This method overwrites any script already defined for cName.

Parameters

Example

Create a beeping sound every time the document is opened.

   this.addScript("My Code", "app.beep(0);");

See Example 2 following the disclosed property for another example.

addThumbnails

Creates thumbnails for the specified pages in the document. See also the removeThumbnails method.

Parameters

addWatermarkFromFile

Adds a page as a watermark to the specified pages in the document and places the watermark in an optional content group (OCG). See also the OCG object.

Note:Can only be executed during a batch or console event. See also Privileged versus non-privileged context.

Parameters

Example 1

Adds the first page of watermark.pdf as a watermark to the center of all pages of the current document.

   this.addWatermarkFromFile("/C/temp/watermark.pdf");

Example 2

Adds the second page of watermark.pdf as a watermark to the first 10 pages of the current document. The watermark is rotated counterclockwise 45 degrees and positioned 1 inch down and 2 inches over from the upper-left corner of the page.

   this.addWatermarkFromFile({

      cDIPath: "/C/temp/watermark.pdf",

      nSourcePage: 4, nEnd: 9,

      nHorizAlign: app.constants.align.left,

      nVertAlign: app.constants.align.top,

      nHorizValue: 144, nVertValue: -72,

      nRotation: 45

   });

addWatermarkFromText

Adds the given text as a watermark to the specified pages in the document and places the watermark in an optional content group (OCG).

See the OCG object.

Parameters

Example 1

Adds “Confidential” as a watermark to the center of all pages of the current document.

   this.addWatermarkFromText("Confidential", 0, font.Helv, 24, color.red);

Example 2

Adds a multiline watermark to each page of the current document 1 inch down and 1 inch over from the upper-right corner.

   this.addWatermarkFromText({

      cText: "Confidential Document\rA. C. Robat",

      nTextAlign: app.constants.align.right,

      nHorizAlign: app.constants.align.right,

      nVertAlign: app.constants.align.top,

      nHorizValue: -72, nVertValue: -72

   });

addWeblinks

Scans the specified pages looking for instances of text with an http: scheme and converts them into links with URL actions.

See also the removeWeblinks method

Parameters

Returns

The number of web links added to the document.

Example

Search the entire document and convert all content that appears to be a web address into a web link. Report back the number of links created.

   var numWeblinks = this.addWeblinks();

   console.println("There were " + numWeblinks +
      " instances of text that looked like a web address,"
      +" and converted as such.");

applyRedactions

Applies redaction marks to the document, removing all underlying content, and optionally removing the marks themselves.

Parameters

Returns

true if the document was changed, false otherwise.

Example 1

Apply all redaction marks in the current document with the provided progress message

this.applyRedactions({cProgText: "Applying redactions through JS..."});

Example 2

Apply redaction marks found only on the first page, and display a confirmation first.

var markArray = Array();

var pageAnnots = this.getAnnots(0);

for (var i=0; i < pageAnnots.length; i++) {

   if (pageAnnots[i].type == "Redact") {

      markArray[markArray.length] = pageAnnots[i];

   }

}

if (markArray.length > 0) {

   this.applyRedactions({

      aMarks: markArray,

      bKeepMarks: false,

      bShowConfirmation: true,

      cProgText: "Applying page 1 redactions..."

   });

}

bringToFront

Brings an open document to the front.

Example

This example searches among the open documents for one with a title of “Annual Report” and brings it to the front.

   var d = app.activeDocs;

   for (var i = 0; i < d.length; i++)

      if (d[i].info.Title == "Annual Report") d[i].bringToFront();

calculateNow

Forces computation of all calculation fields in the current document.

When a form contains many calculations, there can be a significant delay after the user inputs data into a field, even if it is not a calculation field. One strategy is to turn off calculations at some point and turn them back on later (see example).

Example

Turn off calculations

   this.calculate = false;

   .....

Turn on calculations

   this.calculate = true;

Unless the user committed data after this.calculate is set to true, automatic calculation does not occur. Calculation can be forced to occur by using the following code.

   this.calculateNow();

certifyInvisibleSign

Adds an invisible certification to a document. This method is not available in Adobe Reader.

Parameters

Returns

Returns TRUE if the signing was successful.

Example

var myEngine = security.getHandler( "Adobe.PPKLite" );

myEngine.login( "password", "/C/Users/username/Desktop/PrivateUser.pfx" );

 

var myInfo =  {password: "password",

              reason: "SaveAs Test",

              mdp: "defaultAndComments"};

 

this.certifyInvisibleSign({

   oSig:myEngine,

   oInfo:myInfo,

   cDIPath:"/c/temp/sigSign.pdf",

   cLegalAttest: "Certified using JavaScript",

   bUI:false

});

closeDoc

Closes the document.

For Adobe Reader 5.1 or later, the method is always allowed:

• If the document was changed and no Document Save Rights are available, the document is closed without any warnings and changes are lost.

• If Document Save Rights are available, the user has the option of saving the changed file.

Note:This command does not work in browsers.

It is important to use this method carefully, because it is an abrupt change in the document state that can affect any JavaScript executing after the close. Triggering this method from a Page event or Document event could cause the application to behave strangely.

In versions of Acrobat earlier than 7.0, a document that closes itself by executing this.closeDoc terminates any script that follows it. In Acrobat 7.0, the script is allowed to continue and to terminate naturally. However, if the Doc of the closed document is referenced, an exception will be thrown.

Parameters

Example 1

From the console, close all open documents.

   var d = app.activeDocs;

   for( var i in d ) d[i].closeDoc();

The following code can be executed as a mouse-up action from an open document. It closes all disclosed open documents. The code is designed to close the active document last so that the execution of the code will not be abruptly terminated.

   var d = app.activeDocs;

   for( var i in d )

      if( d[i] != this ) d[i].closeDoc();

   if ( this.disclosed ) this.closeDoc();

Example 2

Create a series of three test files and save them to a directory. This code must be executed in the console, because saveAs has a security restriction.

   var myDoc = app.newDoc();

   for (var i=0; i < 3; i++) {

      myDoc.info.Title = "Test File " + i;

      myDoc.saveAs("/c/temp/test"+i+".pdf);

   }

   myDoc.closeDoc(true);

See saveAs for an another example of closeDoc.

colorConvertPage

Performs color conversion on a page of the document.

Parameters

Returns

A Boolean value, returns true if the page was changed, otherwise, returns false.

Example

See getColorConvertAction for an example.

createDataObject

Creates a Data object.

Data objects can be constructed ad hoc. This is useful if the data is being created in JavaScript from sources other than an external file.

Related objects, properties, and methods are dataObjects, getDataObject, openDataObject, importDataObject, removeDataObject, getDataObjectContents, and setDataObjectContents, and the Data object.

Parameters

Example

   this.createDataObject("MyData.txt", "This is some data.");

See also the example that follows addRecipientListCryptFilter.

createTemplate

Note:In Adobe Reader 5.1 and later, this method was allowed with Advanced Form Features rights. Beginning with version 7.0 of Adobe Reader, this method is not allowed and will throw a NotAllowedError exception.

Creates a visible template from the specified page. See also the templates property, the getTemplate and removeTemplate methods, and the Template object.

Note:This method can only be executed during a batch or console event. (See Privileged versus non-privileged context.) The event object contains a discussion of JavaScript events.

Parameters

Returns

The newly created Template object.

Example

Convert all pages beginning with page 2 to hidden templates. As the templates are hidden, this.numPages is updated to reflect that change in the number of (visible) pages. Notice that in the loop below, only page 2 is made a template and then hidden. The next page will become the new page 2.

   numNewTemplates = this.numPages - 2;

   for ( var i = 0; i < numNewTemplates; i++)

   {

      var t = this.createTemplate({cName:"myTemplate"+i, nPage:2 });

      t.hidden = true;

   }

deletePages

Deletes pages from the document. If neither page of the range is specified, the first page (page 0) is deleted. See also insertPages, extractPages, and replacePages.

Note:You cannot delete all pages in a document; there must be at least one page remaining.

(Acrobat 6.0): Beginning with version 6.0, this method deletes spawned pages from within Adobe Reader for documents with forms usage rights enabled.

Parameters

Example

Delete pages 1 through 3 (base 0), inclusive.

   this.deletePages({nStart: 1, nEnd: 3});

deleteSound

Deletes the Sound object with the specified name from the document.

See also sounds, getSound, importSound, and the Sound object.

Parameters

Example

   this.deleteSound("Moo");

embedDocAsDataObject

Embeds the specified document as a Data Object in the document.

Note:For Adobe Reader 7.0 and later, this method is allowed if the document has file attachment rights, but the document to be embedded must have document Save rights in case it has changed.

Parameters

Example

An envelope file that includes a “myFilter” crypt filter has been previously authored and has been included in the current document.

   var authorEmail = "johndoe@example.com";

   var envelopeDoc = this.openDataObject( "envelope" );

   envelopeDoc.embedDocAsDataObject( "attachment", this, "myFilter" );

   envelopeDoc.title.Author = authorEmail;

   envelopeDoc.mailDoc({

      cTo: "support@example.com",

      cSubject: "Application from " + authorEmail

   });

embedOutputIntent

Embeds a color profile as a PDF/X Output Intent (see the PDF Reference).

Parameters

Example

Embed a color profile.

   this.embedOutputIntent("U.S. Sheetfed Coated v2")

encryptForRecipients

Encrypts the document for the specified lists of recipients, using the public-key certificates of each recipient. Encryption does not take place until the document is saved. Recipients can be placed into groups and each group can have its own unique permission settings. This method throws an exception if it is unsuccessful.

Note:This method is available from batch, console and app initialization events. See also Privileged versus non-privileged context.

See also the createDataObject method, the security.chooseRecipientsDialog method, and the Data object.

Parameters

Returns

true, if successful, otherwise an exception is thrown.

Group object

A generic JavaScript object that allows a set of permissions to be attached to a list of recipients for which a document or data is to be encrypted. This object is passed to encryptForRecipients and returned by security.chooseRecipientsDialog. It contains the following properties.

Permissions object

A generic JavaScript object that contains a set of permissions, used in a Group object. It contains the following properties. The default value for all Boolean properties is false.

Example

Encrypt all strings and streams in the document. This will produce a file that can be opened with Acrobat 5.0 and later:

   var sh = security.getHandler( "Adobe.PPKMS" );

   var dir = sh.directories[0];

   var dc = dir.connect();

   

   dc.setOutputFields({oFields:["certificates"]});

   var importantUsers = dc.search({oParams:{lastName:"Smith"}});

   var otherUsers = dc.search({oParams: {lastName:"Jones" }});

   

   this.encryptForRecipients({

      oGroups :

      [

         {userEntities:importantUsers,permissions:{allowAll:true }},

         {userEntities: otherUsers, permissions:{allowPrinting:"highQuality"}}

      ],

      bMetaData : true

   });

encryptUsingPolicy

Encrypts the document using a specified policy object and handler. This method may require user interaction and may result in a new security policy being created.

Note:This method can be executed only during a batch, console or application initialization event. See also Privileged versus non-privileged context.

Parameters

Returns

The value returned is a SecurityPolicyResults object, which has the following properties.

Example 1

Encrypt a newly created document using a chosen policy.

   var doc = app.newDoc();

   var policy = security.chooseSecurityPolicy();

   var results = doc.encryptUsingPolicy( { oPolicy: policy } );

   if ( results.errorCode == 0)

      console.println("The policy applied was: " + results.policyApplied.name);

Example 2

Encrypt a newly created document using a template policy. (A LiveCycle Policy Server must be configured for publishing before running this example.)

   var doc = app.newDoc();

   var groups = [ { userEntities: [{email:"jdoe@example.com"},
      {email:"bsmith@example.com"} ]}

   ];

   var policy = { policyId: "adobe_secure_for_recipients" };

   var results = doc.encryptUsingPolicy({

      oPolicy: policy,

      oGroups: groups,

      bUI: true

   });

   if ( results.errorCode == 0)

      console.println("The policy applied was: "

         + results.policyApplied.name);

exportAsFDF

Exports form fields as an FDF file to the local hard drive.

Note:If the cPath parameter is specified, this method can only be executed during batch and console events. See also Privileged versus non-privileged context. The event object contains a discussion of JavaScript events.

Parameters

Example 1

Export the entire form (including empty fields) with flags.

   this.exportAsFDF(true, true, null, true);

Example 2

Export the name subtree with no flags.

   this.exportAsFDF(false, true, "name");

This example shows a shortcut to exporting a whole subtree. By passing “name” as part of the aFields parameter, fields such as “name.title”, “name.first”, “name.middle”, and “name.last” are exported.

exportAsFDFStr

Computes the same results as calling the doc.exportAsFDF method, but returns the results as a string instead of saving to a file.

Parameters

Returns

The contents of the file as would be produced by the doc.exportAsFDF method, returned as a string. If supplied, the  cHRef parameter is inserted as the value of the F key in the FDF dictionary. If not supplied, the F key contains the value as doc.exportAsFDF would produce.

Example

Get form data for the fields FirstName, LastName and Address in FDF format as a string.

var cFDF = this.exportAsFDFStr({

   aFields: ["FirstName", "LastName", "Address"],

   cHRef: "http://www.example.com/formcatalog/ThisFormName.pdf"

});

exportAsText

Exports form fields as a tab-delimited text file to a local hard disk. The text file that is created follows the conventions specified by Microsoft Excel. In particular, exportAsText correctly handles quotes and multiline text fields.

This method writes two lines to the text file, the first line is a tab-delimited list of the names of the fields specified by aFields, the second line is a tab-delimited list of the values of the fields.

Note:If the cPath parameter is specified, this method can only be executed during a batch or console event. See also Privileged versus non-privileged context. The event object includes a discussion of JavaScript events.

Parameters

Example

To export all fields to a tab-delimited file, execute the following script in the console:

   this.exportAsText();

To create a tab-delimited file with more than just one data line, see the Example. included with getDataObjectContents

exportAsXFDF

Exports form fields as an XFDF file to the local hard drive.

XFDF is an XML representation of Acrobat form data. See the document XML Form Data Format Specification at the Acrobat Developer Center.

There is an import version of this same method, importAnXFDF.

Note:If the cPath parameter is specified, this method can only be executed during batch and console events. See Privileged versus non-privileged context for details. The event object contains a discussion of JavaScript events.

Parameters

exportAsXFDFStr

Computes the same results as calling the doc.exportAsXFDF method, but returns the results as a string instead of saving to a file.

Parameters

Returns

The contents of the file as would be produced by the doc.exportAsXFDF method, returned as a string. If supplied, the  cHRef parameter is inserted as the value of the href attribute of the f element child of the xfdf element. If not supplied, the href attribute of the f element key contains the value as doc.exportAsXFDF would produce.

Example

Get the values of the form fields FirstName, LastName and Address in XFDF format as a string.

var cXFDF = this.exportAsXFDFStr({

   aFields: ["FirstName", "LastName", "Address"],

   cHRef: "http://www.example.com/formcatalog/ThisFormName.pdf"

});

exportDataObject

Extracts the specified data object to an external file.

Related objects, properties, and methods are dataObjects, openDataObject, createDataObject, removeDataObject, importDataObject, getDataObjectContents, and setDataObjectContents, and the Data object.

Note:Beginning with Acrobat 6.0, if the parameter cDIPath is non-null, a NotAllowedError (see Error object) exception is thrown and the method fails.

If cDIPath is not passed to this method, a file selection dialog box opens to allow the user to select a save path for the embedded data object.

Parameters

Example 1

Prompt the user for a file and location to extract to.

   this.exportDataObject("MyData");

Example 2 (Acrobat 6.0)

Extract a PDF document and launch it in the viewer.

   this.exportDataObject({ cName: "MyPDF.pdf", nLaunch: 2 });

Example 3

When a file attachment is imported using the importDataObject method, the value of its Data.name property is assigned by that method’s cName parameter. However, when a file is attached using the UI, its name is automatically assigned. The attachments are assigned the sequential names “Untitled Object”, “Untitled Object 2”, “Untitled Object 3”, and so on.

To export a file attached through the UI, the name of the attachment must be found. For the code that follows, the last file attached by the UI, if any, is exported.

   var d = this.dataObjects;

   if ( d == null ) console.println("No file attachments");

   else {

      for ( var i = d.length - 1; i>=0; i--)

         if ( d[i].name.indexOf("Untitled Object") != -1 ) break;

      if ( i != -1 ) this.exportDataObject(d[i].name);

      else console.println("No attachment was embedded by UI");

   }

exportXFAData

Exports the XFA data (if any) from the document and saves it as an XDP file.

Note:When exporting XFA data from Adobe Reader, the document must have export form rights.

If the cPath parameter is specified, this method can only be executed during batch, console or menu events. See Privileged versus non-privileged context for details. The event object contains a discussion of JavaScript events.

Parameters

Example

Export XFA data. In the following example, all packets are included. However, the PDF document is referenced, not embedded:

   this.exportXFAData({

      cPath: "/c/temp/myData.xdp",

      bXDP: true,

      aPackets: ["*"]

   })

In this example, all packets are included, with the PDF document embedded in the XDP file.

   this.exportXFAData({

      cPath: "/c/temp/myData.xdp",

      bXDP: true,

      aPackets: ["*","pdf"]

   })

extractPages

Creates a new document consisting of pages extracted from the current document. If a page range is not specified, the method extracts all pages in the document.

See also deletePages, insertPages, and replacePages.

Note:If the cPath parameter is specified, this method can only be executed during a batch and console event, or through an external call (for example, OLE). See Privileged versus non-privileged context for details. The event object contains a discussion of JavaScript events.

Parameters

Returns

If cPath is not specified, returns the Doc for the new document; otherwise, returns the null object.

Example

The following batch sequence takes each of the selected files, extracts each page, and saves the page in a folder with a unique name. It could be used, for example, when the client’s one-page bills are produced by an application and placed in a single PDF file. The client wants to separate the pages for distribution or for separate printing jobs.

   /* Extract pages to folder */

   // Regular expression used to acquire the base name of file

   var re = /\.pdf$/i;

   // filename is the base name of the file Acrobat is working on

   var filename = this.documentFileName.replace(re,"");

   try {for (var i = 0; i < this.numPages; i++)

         this.extractPages({

            nStart: i,

            cPath: "/F/temp/"+filename+"_" + i +".pdf"

         });         

   } catch (e) { console.println("Aborted: " + e) }

flattenPages

Converts all annotations in a page range to page contents. If a page range is not specified, all annotations in the document are converted.

Note:Great care must be used when using this method. All annotations—including form fields, comments, and links—on the specified range of pages are flattened. They may have appearances, but they will no longer be annotations.

Parameters

Example

Flatten all pages in the document.

   this.flattenPages();

getAnnot

Returns an Annotation object contained on a specific document page.

Parameters

Returns

The Annotation object, or null if there is no such annotation.

Example

Attempt to get a particular annotation.

   var ann = this.getAnnot(0, "OnMarketShare");

   if (ann == null)

      console.println("Not Found!")

   else

      console.println("Found it! type: " + ann.type);

getAnnotRichMedia

This method gets an AnnotRichMedia object with a given name for a given page.

Parameters

Returns

An AnnotRichMedia object, or undefined if there is no such object.

See also getAnnotsRichMedia.

getAnnot3D

Gets an Annot3D object with a given name from a given page.

Parameters

Returns

The Annot3D object, or undefined if there is no such object.

getAnnots

Gets an array of Annotation objects satisfying specified criteria. See also getAnnot and syncAnnotScan.

Parameters

Returns

An array of Annotation objects, or null if none are found.

Example

Acquire all annotations on the first page, and write information to the console.

   this.syncAnnotScan();

   var annots = this.getAnnots({

      nPage:0,

      nSortBy: ANSB_Author,

      bReverse: true

   });

   console.show();

   console.println("Number of Annotations: " + annots.length);

   var msg = "%s in a %s annot said: \"%s\"";

   for (var i = 0; i < annots.length; i++)

      console.println(util.printf(msg, annots[i].author, annots[i].type,

         annots[i].contents));

getAnnotsRichMedia

This method returns an array of AnnotRichMedia objects for a given page.

Parameters

Returns

An array of AnnotRichMedia objects, or undefined if none is found.

See also getAnnotRichMedia.

getAnnots3D

This method returns an array of Annot3D objects for a page.

Caution:Do not use this method when adding Flash content to an existing 3D annotation. In such cases use getAnnotsRichMedia instead.

Parameters

Returns

An array of Annot3D objects, or undefined if none is found.

getColorConvertAction

Gets a colorConvertAction object that reflects default color conversion settings.

See colorConvertPage, which takes two arrays of colorConvertAction objects as parameters.

Returns

A colorConvertAction object

Example

Get a colorConvertAction object, set it up to convert everything to RGB. (Note that we do not convert any alternate spaces, hence the “space type” match is for anything but alternate spaces.)

   // Get a color convert action

   var toRGB = this.getColorConvertAction();

 

   // Set up the action for a conversion to RGB

   toRGB.matchAttributesAny = -1;

   toRGB.matchSpaceTypeAny = ~toRGB.constants.spaceFlags.AlternateSpace;

   toRGB.matchIntent = toRGB.constants.renderingIntents.Any;

   toRGB.convertProfile = "Apple RGB";

   toRGB.convertIntent = toRGB.constants.renderingIntents.Document;

   toRGB.embed = true;

   toRGB.preserveBlack = false;

   toRGB.useBlackPointCompensation = true;

   toRGB.action = toRGB.constants.actions.Convert;

 

   // Convert the first page of the document

   var result = this.colorConvertPage(0,[toRGB],[]);

getDataObject

Obtains a specific Data object. See also dataObjects, createDataObject, exportDataObject, importDataObject, and removeDataObject.

Parameters

Returns

The Data object corresponding to the specified name.

Example

Get a specific file attachment, and write various information to the console.

   var MyData = this.getDataObject("MyData");

   console.show(); console.clear();

   for (var i in MyData) console.println("MyData." + i + "=" + MyData[i]);

getDataObjectContents

Allows access to the contents of the file attachment associated with a DataObject.

Parameters

Returns

ReadStream object

A NotAllowedError is thrown and the method fails if it attempts to access the content of an embedded file attachment for which any of the following conditions is true (all file name extension matching is case-insensitive):

•    The attachment's file name extension is ".SWF". If a legitimate .SWF application or module run as part of Acrobat's Rich Media Annotation or PDF Portfolio navigator is allowed access to the content bytes of .SWF embedded file attachments, it is possible that the legitimate .SWF will load a malicious .SWF.

Note:If you use the Data.MIMEType property to check whether a Data object represents a .SWF file, note that the MIME type for .SWF files is application/x-shockwave-flash.

• The attachment's file name extension is ".GIF", ".JPG", ".JPEG", or ".PNG" and the first three bytes of its content have the header signature of a .SWF file ("FWS" or "CWS"). The reason for this security restriction is that the same ActionScriptflash.display.Loader class load() method that can be used to load GIF, JPEG, and PNG images can also be used to load a SWF file. If a malicious SWF file's extension has been altered to that of one of these image types, the SWF could be loaded.

Related objects, properties, and methods are dataObjects, getDataObject, openDataObject, createDataObject, importDataObject, setDataObjectContents, and removeDataObject, and the Data object.

Example

This code is part of a circulating memo. A PDF file is circulated among members on an email list. Each recipient enters a budget figure, then forwards the document to the next person on the list. Before the document is sent, the budget number is appended to an embedded tab-delimited document, budget.xls, an attachment to this document. The last recipient can open the attachment, budget.xls, in a spreadsheet application to view the various budget numbers.

   // Get the name and department of the current recipient

   var firstName = this.getField("Name.First").value;

   var lastName =  this.getField("Name.Last").value;

   var deptName =  this.getField("Dept.Name").value;

   // Get the budget number

   var deptBudget =  this.getField("Dept.Budget").value;

   if ( app.viewerVersion >= 7 ) {

      // Get the file stream object of the embedded file

      var oFile = this.getDataObjectContents("budget.xls");

      // Convert to a string

      var myBudget = util.stringFromStream(oFile, "utf-8");

      // Append current data to the end, using tabs to separate info

      var myBudget = myBudget + "\r\n" + firstName

         + "\t" + lastName + "\t" + deptName + "\t" + deptBudget;

      // Convert back to a file stream

      var oFile = util.streamFromString(myBudget, "uft-8");

      // Now "overwrite" budget.xls

      this.setDataObjectContents("budget.xls", oFile);

   } else {

         app.alert("Acrobat 7.0 or later is required."
            + " Your budget data will not be included. "

            + "Will e-mail on to the next correspondent, sorry. "

            + "Send in your budget request using traditional methods.");

   }

The rest of the code, not shown, saves the document and sends it to the next person on the mailing list.

This example uses getDataObjectContents, setDataObjectContents, util.stringFromStream, and util.streamFromString.

getField

Maps a Field object in the PDF document to a JavaScript variable.

Beginning with Acrobat 6.0, this method can return the Field object of an individual widget. For more information, see Field object.

Parameters

Returns

A Field object representing a form field in the PDF document.

Example 1

Make a text field multiline and triple its height

   var f = this.getField("myText");

   var aRect = f.rect;               // Get bounding rectangle

   f.multiline = true;               // Make it multiline

   var height = aRect[1]-aRect[3];   // Calculate height

   aRect[3] -= 2* height;            // Triple the height of the text field

   f.rect = aRect;                   // and make it so

Example 2 (Acrobat 6.0)

Attach a JavaScript action to an individual widget, in this case, a radio button:

   var f = this.getField("myRadio.0");

   f.setAction("MouseUp",

      "app.alert('Thanks for selecting the first choice.');");

Example 3

List all properties of a field. This technique can be used to programmatically duplicate a field and its properties.

   f = this.getField("myField");

   for ( var i in f ) {

      try {

         if ( typeof f[i] != "function" )    // Do not list field methods

            console.println( i + ":" + f[i] )

      } catch(e) {}           // An exception occurs when we get a property

   }                         // that does not apply to this field type.

getIcon

Obtains a specific icon object. See also the icons property, the addIcon, importIcon, and removeIcon methods, and the Field object methods buttonGetIcon, buttonImportIcon, and buttonSetIcon.

Parameters

Returns

An Icon object associated with the specified name in the document or null if no icon of that name exists.

Example

The following is a custom keystroke script from a combo box. The face names of the items in the combo box are the names of some of the icons that populate the document. As the user chooses different items from the combo box, the corresponding icon appears as the button face of the field “myPictures”.

   if (!event.willCommit) {

      var b = this.getField("myPictures");

      var i = this.getIcon(event.change);

      b.buttonSetIcon(i);

   }

See the Field object buttonSetIcon method or a more elaborate variation on this example.

getLegalWarnings

Returns the legal warnings for this document in the form of an object with entries for each warning that has been found in the document.

Note:In versions of Acrobat previous to 8.0, Document.getLegalWarnings would dirty the document.

The process that analyzes a file to determine this list of warnings is not available in Adobe Reader.

Parameters

Returns

A DocLegalWarning object containing property names and values of legal warnings. The value of each entry is the number of occurrences of this warning in the document. If bExecute is false, refer to PDF Reference for a list of possible property names. If bExecute is true, the property names correspond to PDF/SigQ level A violations listed below. Note that the warnings listed in PDF Reference intersects but significantly differ from the list below.

DocLegalWarning object

The following properties describe the PDF/SigQ1-A Violations.

Example

Process a document and get legal PDF warnings.

   var w = this.getLegalWarnings( true );

   console.println( "Actual Legal PDF Warnings:" );

   for(i in w) console.println( i + " = " + w[i] );

   

   var w1 = this.getLegalWarnings( false );

   console.println( "Declared Legal PDF Warnings:" );

   for(i in w1) console.println( i + " = " + w1[i] );

   

   // For a certification signature, note also if annotations are

   // allowed by MDP settings

   

   var f = this.getField( "AuthorSig" );

   var s = f.signatureInfo();

   if( s.mdp == "defaultAndComments" )

      console.println( "Annotations are allowed" );

   

   // What does the author have to say about all this?

   

   console.println( "Legal PDF Attestation:" );

   console.println( w1.Attestation );

getLinks

Gets an array of Link objects that are enclosed within specified coordinates on a page. See also addLink and removeLinks.

Parameters

Returns

An array of Link objects.

Example

Count the number of links in a document and report to the console.

   var numLinks=0;

   for ( var p = 0; p < this.numPages; p++)

   {

      var b = this.getPageBox("Crop", p);

      var l = this.getLinks(p, b);

      console.println("Number of Links on page " + p +" is " + l.length);

      numLinks += l.length;

   }

   console.println("Number of Links in Document is " + numLinks);

getNthFieldName

Gets the name of the nth field in the document. See also numFields.

Parameters

Returns

The name of the field in the document.

Example

Enumerate through all of the fields in the document.

   for (var i = 0; i < this.numFields; i++)

      console.println("Field[" + i + "] = " + this.getNthFieldName(i));

getNthTemplate

Note:This method is superseded by the templates property, the getTemplate method, and the Template object.

Gets the name of the nth template within the document.

Parameters

Returns

The name of the specified template.

getOCGs

Gets an array of OCG objects found on a specified page.

Related methods are getOCGOrder and setOCGOrder, and the OCG object.

Parameters

Returns

An array of OCG objects or null if no OCGs are present.

Example

Turn on all the OCGs on the given document and page.

   function TurnOnOCGsForPage(doc, nPage)

   {

      var ocgArray = doc.getOCGs(nPage);

      for (var i=0; i < ocgArray.length; i++)

         ocgArray[i].state = true;

   }

getOCGOrder

Returns this document’s OCGOrder array. This array represents how layers are displayed in the UI.

Related methods are getOCGs and setOCGOrder, and the OCG object.

Returns

An array containing OCG objects, strings, and similar subarrays, or null if no OCGs are present.

See setOCGOrder for a description of the order array.

getPageBox

Gets a rectangle in rotated user space that encompasses the named box for the page. See also setPageBoxes.

Parameters

Returns

A rectangle in rotated user space that encompasses the named box for the page.

Example

Get the dimensions of the Media box.

   var aRect = this.getPageBox("Media");

   var width = aRect[2] - aRect[0];

   var height = aRect[1] - aRect[3];

   console.println("Page 1 has a width of " + width + " and a height of "
      + height);

getPageLabel

Gets page label information for the specified page.

Parameters

Returns

Page label information for the specified page.

Example

See setPageLabels for an example.

getPageNthWord

Gets the nth word on the page.

See also getPageNumWords and selectPageNthWord.

Note:This method throws an exception if the document security is set to prevent content extraction.

Parameters

Returns

The nth word on the page.

Example

See Example 2 of spell.checkWord for an example.

getPageNthWordQuads

Gets the quads list for the nth word on the page. The quads property of the Annotation object can be used for constructing text markup, underline, strikeout, highlight and squiggly annotations. See also getPageNthWord, getPageNumWords, and selectPageNthWord.

Note:This method throws an exception if the document security is set to prevent content extraction.

Parameters

Returns

The quads list for the nth word on the page.

Example

Underline the fifth word on the second page of a document.

   var annot = this.addAnnot({

      page: 1,

      type: "Underline",

      quads:  this.getPageNthWordQuads(1, 4),

      author: "A. C. Robat",

      contents: "Fifth word on second page"

   });

See spell.checkWord for an additional example.

getPageNumWords

Gets the number of words on the page.

See also getPageNthWord, getPageNthWordQuads, and selectPageNthWord.

Parameters

Returns

The number of words on the page.

Example

Count the number of words in a document

   var cnt=0;

   for (var p = 0; p < this.numPages; p++)

      cnt += getPageNumWords(p);

   console.println("There are " + cnt + " words in this doc.");

See Example 2 of spell.checkWord for an additional example.

getPageRotation

Gets the rotation of the specified page. See also setPageRotations.

Parameters

Returns

The rotation value of 0, 90, 180, or 270.

getPageTransition

Gets the transition of the specified page. See also setPageTransitions.

Parameters

Returns

An array of three values: [ nDuration, cTransition, nTransDuration ].

• nDuration is the maximum amount of time the page is displayed before the viewer automatically turns to the next page. A duration of -1 indicates that there is no automatic page turning.

• cTransition is the name of the transition to apply to the page. See the property app.fs.transitions for a list of valid transitions.

• cTransDuration is the duration (in seconds) of the transition effect.

getPreflightAuditTrail

Gets the current embedded audit trail.

Returns

A PreflightAuditTrail object or Undefined if no audit trail exists.

getPrintParams

Gets a PrintParams object that reflects the default print settings. See the print method, which now takes the PrintParams object as its parameter.

Returns

A PrintParams object.

Example

Get the PrintParams object of the default printer.

   var pp = this.getPrintParams();

   pp.interactive = pp.constants.interactionLevel.automatic;

   this.print(pp); // Print

getSound

Gets the sound object corresponding to the specified name. See also sounds, importSound, deleteSound, and the Sound object.

Parameters

Returns

The Sound object corresponding to the specified name.

Example

Play a sound.

   var s = this.getSound("Moo");

   console.println("Playing the " + s.name + " sound.");

   s.play();

getTemplate

Gets the named template from the document. See also templates, createTemplate, removeTemplate, and the Template object.

Parameters

Returns

The Template object or null if the named template does not exist in the document.

Example

Try to get a particular template and determine if it is hidden or visible.

   var t = this.getTemplate("myTemplate");

   if ( t != null ) console.println( "myTemplate exists and is "

      + eval( '( t.hidden) ? "hidden" : "visible"' ) + ".");

   else console.println( "myTemplate is not present!");

 

getURL

Gets the specified URL over the Internet using a GET. If the current document is being viewed inside the browser or Acrobat Web Capture is not available, the method uses the Acrobat Weblink plug-in to retrieve the requested URL. If running inside Acrobat, the method gets the URL of the current document either from the baseURL, from the URL of the first page (page 0) if the document was obtained by Web Capture, or from the file system.

Note:Beginning with Acrobat 8.1, File and JavaScript URLs can be executed only when operating in a privileged context, such as during a batch or console event. File and JavaScript URLs begin with the scheme names javascript or file.

Note:This method is not available for Adobe Reader when the bAppend parameter is set to true.

This method roughly corresponds to the “open a web page” action.

A related method is app.launchURL.

Parameters

Example

   this.getURL("http://www.example.com/", false);

 

getUserUnitSize

Returns the UserUnit value of a page. The UserUnit value can be used to calculate page sizes for large pages. For example, you can use it with the pages where size exceeds 14,400 units.

The PDF reference defines UserUnit as a positive number giving the size of default user space units, in multiples of 1 / 72 inch. Since the largest page size in user space coordinates cannot exceed 14,400, the UserUnit provides a way to specify larger pages by acting as a scaling factor. You can use the getUserUnitSize with the APIs that deal with the page size (such as getPageBox), to determine the actual page size.

Parameters

Returns

A number indicating the UserUnit value for the page.

Type

Integer

Access

R

Example (Acrobat DC)

Determine the page size in inches:

var aRect = this.getPageBox("Media");

var pageHeight = aRect[1];

var pageWidth = aRect[2];

var userUnit  = this.getUserUnitSize(0);

var pageHeightInches = ((pageHeight * userUnit) / 72);

var pageWidthInches = ((pageWidth * userUnit) / 72);

console.println("\nPage 1 height : " + pageHeightInches +

         " inches \nPage 1 width : " + pageWidthInches + " inches\n");

 

gotoNamedDest

Goes to a named destination within the PDF document. For details on named destinations and how to create them, see the PDF Reference.

Parameters

Example

Open a document, and go to a named destination within that document. The example assumes the document being opened by openDoc is disclosed.

   // Open a new document
   var myNovelDoc = app.openDoc("/c/fiction/myNovel.pdf");

   // Go to a destination in this new doc

   myNovelDoc.gotoNamedDest("chapter5");

   // Close the old document

   this.closeDoc();

See Example 6 (Acrobat 8.0) following openDoc for a more efficient way of performing this same task.

importAnFDF

Imports the specified FDF file. See also importAnXFDF and importTextData.

Parameters

Example

The following code, which is an action of a Page Open event, checks whether a certain function, ProcResponse, is already defined, if not, it installs a document-level JavaScript, which resides in an FDF file.

   if(typeof ProcResponse == "undefined") this.importAnFDF("myDLJS.fdf");

Here, the path is a relative one. This technique may be useful for automatically installing document-level scripts for PDF files distilled from a PostScript file.

importAnXFDF

Imports the specified XFDF file containing XML form data.

XFDF is an XML representation of Acrobat form data. See the document XML Form Data Format (XFDF) Specification, available through the Acrobat Developer Center.

See also exportAsXFDF, importAnFDF and importTextData.

Parameters

importDataObject

Imports an external file into the document and associates the specified name with the data object. Data objects can later be extracted or manipulated.

Related objects, properties, and methods are dataObjects, getDataObject, openDataObject, createDataObject, exportDataObject, importDataObject, getDataObjectContents, and setDataObjectContents, and the Data object.

Note:If the cDIPath parameter is specified, this method can only be executed during a batch or console event, or through an external call (for example, OLE). See Privileged versus non-privileged context for details. See the event object for a discussion of JavaScript events.

When a file attachment is imported using importDataObject, the value of its Data.name is assigned by the parameter cName. However, when a file is attached using the UI, its name is automatically assigned. The attachments are assigned the sequential names “Untitled Object”, “Untitled Object 2”, “Untitled Object 3”, and so on.

Parameters

Returns

true on success. An exception is thrown on failure.

Example

Attach two files into current document, and write all Data object information to the console.

   function DumpDataObjectInfo(dataobj)

   {

      for (var i in dataobj)

         console.println(dataobj.name + "[" + i + "]=" + dataobj[i]);

   }

   // Prompt the user for a data file to embed.

   this.importDataObject("MyData");

   DumpDataObjectInfo(this.getDataObject("MyData"));

   // Embed Foo.xml (found in the parent directory for this doc).

   this.importDataObject("MyData2", "../Foo.xml");

   DumpDataObjectInfo(this.getDataObject("MyData2"));

importIcon

Imports an icon into the document and associates it with the specified name.

See also icons, addIcon, getIcon, removeIcon, the Field object methods buttonGetIcon, buttonImportIcon, buttonSetIcon, and the Icon object.

Beginning with version 6.0, Acrobat will first attempt to open cDIPath as a PDF file. On failure, Acrobat will try to convert cDIPath to PDF from one of the known graphics formats (BMP, GIF, JPEG, PCX, PNG, TIFF) and then import the converted file as a button icon.

Note:If cDIPath is specified, this method can only be executed during a batch or console event. See Privileged versus non-privileged context for details. The event object contains a discussion of Acrobat JavaScript events.

Parameters

Returns

An integer code indicating whether it was successful or not:

0 — No error

1 — The user cancelled the dialog box

-1 — The selected file could not be opened

-2 — The selected page was invalid

Example

This function is useful to populate a document with a series of named icons for later retrieval. For example, an author may want a picture of a list box state to appear next to the list box when the user selects the state in a list box. Without this function, it could be done by using a number of fields that could be hidden and shown. However, this is difficult to author. Instead, the appropriate script might be something like this:

   var f = this.getField("StateListBox");

   var b = this.getField("StateButton");

   b.buttonSetIcon(this.getIcon(f.value));

This uses a single field to perform the same effect.

A simple user interface can be constructed to add named icons to a document. Assume the existence of two fields: a field called IconName that will contain the icon name and a field called IconAdd that will add the icon to the document. The mouse-up script for IconAdd would be:

   var t = this.getField("IconName");

   this.importIcon(t.value);

The same kind of script can be applied in a batch setting to populate a document with every selected icon file in a folder.

importSound

Imports a sound into the document and associates the specified name with the sound.

Note:If cDIPath is specified, this method can only be executed during a batch or console event. See Privileged versus non-privileged context for details. The event object contains a discussion of JavaScript events.

Parameters

Example

Import two sounds and play them.

   this.importSound("Moo");

   this.getSound("Moo").play();

   this.importSound("Moof", "./moof.wav");

   this.getSound("Moof").play();

See also sounds, getSound, deleteSound, and the Sound object.

importTextData

Imports a row of data from a text file. Each row must be tab delimited. The entries in the first row of the text file are the column names of the tab delimited data. These names are also field names for text fields present in the PDF file. The data row numbers are 0-based; that is, the first row of data is row zero (this does not include the column name row). When a row of data is imported, each column datum becomes the field value of the field that corresponds to the column to which the data belongs.

See also the export version of this method, exportAsText.

Note:(Acrobat 8.0) If cPath is specified, this method can only be executed during batch and console events. See Privileged versus non-privileged context for details. The event object contains a discussion of JavaScript events.

Parameters

Returns

An integer return code.

Example 1

In this example, there are text fields named “First”, “Middle”, and “Last”, and a data file whose first row consists of the three strings, “First”, “Middle”, and “Last”, separated by tabs, along with four additional rows of tab-separated name data.

   First    Middle    Last

   A.       C.        Robat

   T.       A.        Croba

   A.       T.        Acrob

   B.       A.        Tacro

   // Import the first row of data from "myData.txt".

   this.importTextData("/c/data/myData.txt", 0)

Example (continued)

The following code is a mouse-up action for a button. Clicking on the button cycles through the text file and populates the three fields “First”, “Middle”, and “Last” with the name data.

   if (typeof cnt == "undefined") cnt = 0;

      this.importTextData("/c/data/textdata.txt", cnt++ % 4)

The data file can be a spreadsheet or a database.

importXFAData

Imports the specified XFA file. See also importAnXFDF and importTextData.

Note:This method is only allowed in batch and console events. See Privileged versus non-privileged context for details.

Parameters

insertPages

Inserts pages from the source document into the current document. If a page range is not specified, the method gets all pages in the source document.

See also deletePages and replacePages.

Note:This method can only be executed during batch and console events. See Privileged versus non-privileged context for details. The event object contains a discussion of JavaScript events.

Parameters

Example

Insert a cover page to the current document.

   this.insertPages ({

      nPage: -1,

      cPath: "/c/temp/myCoverPage.pdf",

      nStart: 0

   });

mailDoc

Saves the current PDF document and mails it as an attachment to all recipients, with or without user interaction.

See also mailForm, app.mailGetAddrs, app.mailMsg, the FDF object mail method and the Report object mail method.

Note:(Acrobat 7.0) When this method is executed in a non-privileged context, the bUI parameter is not honored and defaults to true. See Privileged versus non-privileged context for details.

(Save Rights) For Adobe Reader 5.1 and later, this method is allowed, but document Save rights are required in case the document is changed.

On Windows, the client computer must have its default mail program configured to be MAPI enabled to use this method.

Parameters

Example

Open the compose message window.

   this.mailDoc(true);

Send email with the attached PDF file to apstory@example.com and dpsmith@example.com. Beginning with Acrobat 7.0, the code below would have to be executed in a privileged context if the bUI parameter (set to false) is to be honored.

   this.mailDoc({

      bUI: false,

      cTo: "apstory@example.com",

      cCC: "dpsmith@example.com",
      cSubject: "The Latest News",

      cMsg: "A.P., attached is my latest news story in PDF."

   });

mailForm

Exports the form data and mails the resulting FDF file as an attachment to all recipients, with or without user interaction. The method does not support signed signature fields.

See also mailDoc, app.mailGetAddrs, app.mailMsg, the FDF object mail method and the Report object mail method.

Note:On Windows, the client machine must have its default mail program configured to be MAPI enabled to use this method.

Parameters

Example

Open the compose message window.

   this.mailForm(true);

Send the mail with the attached FDF file to fun1@example.com and fun2@example.com.

   this.mailForm(false, "fun1@example.com; fun2@example.com", "", "",

      "This is the subject", "This is the body of the mail.");

movePage

Moves a page within the document.

Parameters

Example

Reverse the pages in the document.

   for (i = this.numPages - 1; i >= 0; i--) this.movePage(i);

newPage

Adds a new page to the active document.

Note:This method can only be executed during batch and console events. See Privileged versus non-privileged context for details.

Parameters

Example

Add a new page to match the page size of the doc.

   var Rect = this.getPageBox("Crop");

   this.newPage(0, Rect[2], Rect[1]);

openDataObject

Returns the Doc of a PDF document that is an embedded data object (an attachment) within the document that this method is being called for.

The method can throw an exception instead of returning a Doc if any of the following conditions are true:

• The document that this method is being called for does not contain the requested embedded data object.

• The data object is not a PDF document.

• Permissions forbid opening attachments by means of JavaScript.

The document should be closed (using closeDoc) after it is no longer needed.

Parameters

The name of a data object is a property of the Data object. A name is given to the object when it is embedded, automatically by the Acrobat UI, or programmatically by the JavaScript methods createDataObject or importDataObject.

Returns

Doc or an exception is thrown.

Related objects, properties, and methods are dataObjects, getDataObjectContents, setDataObjectContents, createDataObject, and importDataObject, and the Data object.

Example

Open a PDF attachment and extract form data from it.

   var oDoc = this.openDataObject("myAttachment");

   try {

      var myField = this.getField("myTextField");

      // Get the value of "yourTextField" in PDF attachment

      var yourField = oDoc.getField("yourTextField");

      // View this value in "myTextField"

      myField.value = yourField.value;

      oDoc.closeDoc();

   } catch(e) { app.alert("Operation failed");}

See also Example 5 (Acrobat 7.0) following the submitForm method.

preflight

Runs a Preflight profile for the document. An exception is thrown if the Preflight run fails.

Parameters

Returns

A PreflightResult object.

Example

Run a Preflight profile and show the progress of the operation.

var oProfile = Preflight.getProfileByName("Magazine Ads")

if( oProfile != undefined )

{

   var oThermometer = app.thermometer;

   var myPreflightResult = this.preflight( oProfile, false, oThermometer);

   if( myPreflightResult.numErrors > 0 ) {

   console.println( "Preflight found " + myPreflightResult.numErrors + " Errors.");

} else {

   console.println( "Preflight found no Errors.");

}

 

print

Prints all or a specific number of pages of the document.

Beginning with Acrobat 6.0, the method can print the document using the settings contained in a PrintParams object, rather than through the other parameters. The permanent print settings are not altered.

Note:(Acrobat 6.0) When printing to a file, the path must be a safe path (see Safe path). The print method will not overwrite an existing file.

(Acrobat 7.0) Non-interactive printing can only be executed during batch, console, and menu events. Printing is made non-interactive by setting bUI to false or by setting the interactive property to silent, for example:

         var pp = this.getPrintParams();

         pp.interactive = pp.constants.interactionLevel.silent;

Outside of batch, console, and menu events, the values of bUI and of interactive are ignored and a print dialog box will always be presented.

See also Privileged versus non-privileged context.

Note:On a Windows platform, the file name must include an extension of .ps or .prn (case insensitive). Additionally, the print method will not create a file directly in the root directory, the windows directory, or the windows system directory.

An InvalidArgsError (see Error object) exception will be thrown and print will fail if any of the above security restrictions are not met.

Parameters

Example 1

Print the current page.

   this.print(false, this.pageNum, this.pageNum);

   // Print a file silently

   this.print({bUI: false, bSilent: true, bShrinkToFit: true});

Example 2 (Acrobat 6.0)

Print current document to a known printer.

   var pp = this.getPrintParams();

   pp.interactive = pp.constants.interactionLevel.automatic;

   pp.printerName = "hp officejet d series";

   this.print(pp);

Note:If printerName is an empty string and fileName is nonempty, the current document is saved to disk as a PostScript file.

Example 3 (Acrobat 6.0)

Save the current document as a PostScript file.

   var pp = this.getPrintParams();

   pp.fileName = "/c/temp/myDoc.ps";

   pp.printerName = "";

   this.print(pp);

removeDataObject

Deletes the data object corresponding to the specified name from the document.

Related objects, properties, and methods are dataObjects, getDataObject, openDataObject, createDataObject, removeDataObject, importDataObject, getDataObjectContents, and setDataObjectContents, and the Data object.

Parameters

The name of a data object is a property of the Data object. A name is given to the object when it is embedded, either automatically by the Acrobat UI or programmatically by the JavaScript methods createDataObject or importDataObject.

Example

this.removeDataObject("MyData");

removeField

Removes the specified field from the document. If the field appears on more than one page, all representations are removed.

Note:(Acrobat 6.0): Beginning with Acrobat 6.0, removeField can be used from within Adobe Reader for documents with forms usage rights.

Parameters

Example

   this.removeField("myBadField");

removeIcon

Removes the specified named icon from the document.

See also icons, addIcon, getIcon, and importIcon, the Field object methods buttonGetIcon, buttonImportIcon, and buttonSetIcon, and the Icon object.

Parameters

The name of the icon is a property of the Icon object. A name is given to the object either by importIcon, when the icon file is imported into the document, or by addIcon, which names an icon that is not in the document-level named icons tree.

Example

Remove all named icons from the document.

   for ( var i = 0; i < this.icons.length; i++)

      this.removeIcon(this.icons[i].name);

removeLinks

If the user has permission to remove links from the document, removes all the links on the specified page within the specified coordinates

See also addLink, getLinks, and the Link object.

Parameters

Example

Remove all links from the document.

   // Remove all links from the document

   for ( var p = 0; p < this.numPages; p++)

   {

      var b = this.getPageBox("Crop", p);

      this.removeLinks(p, b);

   }

Use getLinks to help count the number of links removed.

removePreflightAuditTrail

Removes the current audit trail from the document.

Returns

true if successfully removed, false otherwise.

removeRequirement

Removes an existing requirement present in a PDF document. Removing a requirement frees Acrobat from having to fulfill it to open the document. The document may not function properly if a requirement is removed.

Note:This method can only be called from a console or batch event.

Parameters

removeScript

Removes a document-level JavaScript, if permissions for script removal is granted.

Parameters

Returns

The value undefined on success. The method throws an exception if the script is not found.

Example

Add a document-level script, then remove it.

   this.addScript("myScript", "app.alert('A.C. Robat welcomes you!')");

Now remove this script:

   this.removeScript("myScript");

removeTemplate

Removes the named template from the document.

See also templates, createTemplate, getTemplate, and the Template object.

Note:This method can only be executed during a batch or console event. See Privileged versus non-privileged context for details. See the event object for a discussion of JavaScript events.

Parameters

The template name is a property of the Template object. A name is given to a template when it is created, either by the Acrobat UI or by the JavaScript method getTemplate.

removeThumbnails

Deletes thumbnails for the specified pages in the document. See also addThumbnails.

Parameters

removeWeblinks

Scans the specified pages looking for links with actions to go to a particular URL on the web and deletes them. See also addWeblinks.

Note:This method only removes weblinks authored in the application using the UI. Web links that are executed through JavaScript (for example, using getURL) are not removed.

Parameters

Returns

The number of web links removed from the document.

Example

Remove all web links from the document and report results to the console window.

   var numWeblinks = this.removeWeblinks();

   console.println("There were " + numWeblinks +
      " web links removed from the document.");

replacePages

Replaces pages in the current document with pages from the source document.

See also deletePages, extractPages, and insertPages.

Note:This method can only be executed during a batch or console event. See Privileged versus non-privileged context for details. See the event object for a discussion of JavaScript events.

Parameters

resetForm

Resets the field values within a document. Resetting a field causes it to take on its default value (which, in the case of text fields, is usually blank).

Note:If the form contains signature fields, signature rights are required to use the method in Adobe Reader.

Parameters

Example 1

Select fields to be reset and reset them.

   var fields = new Array();

   fields[0] = "P1.OrderForm.Description";

   fields[1] = "P1.OrderForm.Qty";

   this.resetForm(fields);

The same fields can be reset using only one line of code:

   this.resetForm(["P1.OrderForm.Description","P1.OrderForm.Qty"]);

Example 2

This example shows how to reset a whole subtree. For example, if you pass “name” as part of the fields array, all name fields, such as name.first and name.last, are reset.

   this.resetForm(["name"]);

saveAs

Saves the file to the device-independent path specified by the required parameter, cPath. The file is not saved optimized for the web. Beginning with Acrobat 6.0, the document can be converted to another file type (other than PDF) and saved as specified by the value of the cConvID parameter.

Note:This method can only be executed during a batch or console event. See Privileged versus non-privileged context for details. The event object contains a discussion of JavaScript events.

(Adobe Reader S): This method is available in Adobe Reader for documents that have Save usage rights.

Parameters

Returns

The value undefined is returned on success. An exception is thrown if an error occurs. For example, this method will throw a NotAllowedError (see Error object) if the user disallows an overwrite.

Note:Prior to Acrobat 7.0, this method had no return value.

Values of cConvID and Valid Extensions

Deprecated Values of cConvID (as of Acrobat 10)

The conversion IDs listed below are deprecated in Acrobat 10. They are not registered but (only when used with the JavaScript doc.saveAs call) are internally mapped to valid, registered conversion IDs. Support for the deprecated conversion IDs will be fully removed in subsequent Acrobat releases.

Note:When the conversion ID corresponds to jpeg, jp2k, png, or tiff, this method saves each page individually under a file name obtained by appending "_Page_#" to the basename of the file name provided. For example, if the value of the cPath is "/C/temp/mySaveAsDocs/myJPGs.jpg", the names of the files generated will be myJPGs_Page_1.jpg, myJPGs_Page_2.jpg, and so on.

Example 1

The following code, which could appear as a batch sequence, is an outline of a script. It assumes a PDF file containing form fields is open. The fields must be populated from a database and the document saved.

   // code lines to read from a database and populate the form with data

   // now save file to a folder; use customerID from database record

   // as name

   var row = statement.getRow();

   .......

   this.saveAs("/c/customer/invoices/" + row.customerID + ".pdf");

Example 2

You can use newDoc and addField to dynamically lay out a form, then populate it from a database and save.

   var myDoc = app.newDoc()

   // layout some dynamic form fields

   // connect to database, populate with data, perhaps from a database

   ..........

   // save the doc and/or print it; print it silently this time

   // to default printer

   myDoc.saveAs("/c/customer/invoices/" + row.customerID + ".pdf");

   myDoc.closeDoc(true);       // close the doc, no notification

Example 3 (Acrobat 6.0)

Save the current document in rich text format:

   this.saveAs("/c/myDocs/myDoc.rtf", "com.adobe.acrobat.rtf");

See fromPDFConverters for a listing of supported conversion ID strings.

Example 3 (Acrobat 7.0)

Save the document to a WebDAV folder.

   this.saveAs({

      cPath: "http://www.example.com/WebDAV/myDoc.pdf",

      bPromptToOverwrite: true,

      cFS: "CHTTP"

   });

scroll

Scrolls the specified point on the current page into the middle of the current view. These coordinates must be defined in rotated user space. See the PDF Reference for details.

Parameters

selectPageNthWord

Changes the current page number and selects the specified word on the page.

See also getPageNthWord, getPageNthWordQuads, and getPageNumWords.

Parameters

Example

Get and select a particular word.

   // Get the 20th word on page 2 (page 1, 0-based)

   var cWord = this.getPageNthWord(1, 20);

   // Select that word (highlight) for the user to see, and change the page if
   // necessary.

   this.selectPageNthWord(1, 20);

setAction

Sets the JavaScript action of the document for a given trigger.

See also addScript, setPageAction, the Bookmark object setAction method, and the Field object setAction method.

Note:This method will overwrite any action already defined for the selected trigger.

Parameters

Example

Insert WillSave and DidSave actions. The code gets the file size before saving and after saving, and compares the two.

   // WillSave script

   var myWillSave = 'var filesizeBeforeSave = this.filesize;\r'

      + 'console.println("File size before saving is " + '

      + ' filesizeBeforeSave );';

   

   // DidSave script

   var myDidSave =  'var filesizeAfterSave = this.filesize;\r'

      + 'console.println("File size after saving is "'
      + 'filesizeAfterSave);\r'

      + 'var difference = filesizeAfterSave - filesizeBeforeSave;\r'

      + 'console.println("The difference is " + difference );\r'

      + 'if ( difference < 0 )\r\t'

      + 'console.println("Reduced filesize!");\r'

      + 'else\r\t'

      + 'console.println("Increased filesize!");'

   

   // Set document actions...

   this.setAction("WillSave", myWillSave);

   this.setAction("DidSave", myDidSave);

setDataObjectContents

Replaces the file attachment specified by the parameter cName with the contents of the oStream parameter.

Parameters

Example 1

See the Example following getDataObjectContents.

Example 2

This document has a file attachment named Acrobat.xml. The attachment is opened, the XML data is updated, then the new XML document is saved back to the attachment. It is possible to submit this XML file attachment. See Example 5 (Acrobat 7.0), following the submitForm method. This example uses the XML data defined in the Example following XMLData.applyXPath.

   // Get the file stream object of the attachment

   var Acrobat = this.getDataObjectContents("Acrobat.xml");

   

   // Convert to a string

   var cAcrobat = util.stringFromStream(Acrobat, "utf-8");

   

   // Parse this and get XFAObject

   var myXML = XMLData.parse(cAcrobat,false);

   

   // Change the value of grandad's income

   myXML.family.grandad.personal.income.value = "300000";

   

   // Save the XML document as a string, cAcrobat

   var cAcrobat = myXML.saveXML('pretty');

   

   // Convert to a file stream

   var Acrobat = util.streamFromString(cAcrobat, "utf-8");

   

   // Now "update" the attachment Acrobat.xml with this file stream

   this.setDataObjectContents("Acrobat.xml", Acrobat);

Related objects, properties, and methods are dataObjects, getDataObject, openDataObject, createDataObject, importDataObject, getDataObjectContents, and removeDataObject, and the Data object.

setOCGOrder

Sets this document’s OCGOrder array. This array represents how layers are displayed in the UI.

The simplest order array is a flat array of OCG objects. In this case, the listed OCGs are displayed in the UI as a flat list in the same order. If a subarray is present in the order array and the first element of the array is a string, the string will be listed with the rest of the array nested underneath it. If the first element of the array is not a string, the entire array will appear nested underneath the OCG preceding the subarray.

Related methods are getOCGs and getOCGOrder, and the OCG object.

Parameters

Example

Reverse the order of OCGs as listed in the UI.

   var ocgOrder = this.getOCGOrder();

   var newOrder = new Array();

   for (var j=0; j < ocgOrder.length; j++)

      newOrder[j] = ocgOrder[ocgOrder.length-j-1];

   this.setOCGOrder(newOrder);

setPageAction

Sets the action of a page in a document for a given trigger.

See also setAction, addScript, the Bookmark object setAction method, and the Field object setAction method.

Note:This method will overwrite any action already defined for the chosen page and trigger.

Parameters

Example

This example causes the application to beep when the first page is opened.

   this.setPageAction(0, "Open", "app.beep(0);");

setPageBoxes

Sets a rectangle that encompasses the named box for the specified pages.

See also getPageBox.

Parameters

setPageLabels

Establishes the numbering scheme for the specified page and all pages following it until the next page with an attached label is encountered.

See also getPageLabel.

Parameters

Example 1

For the ten pages in the document, label the first three with small roman numerals, the next five with numbers (starting at 1) and the last two with an “Appendix-” prefix and alphabetics.

   this.setPageLabels(0, [ "r", "", 1]);

   this.setPageLabels(3, [ "D", "", 1]);

   this.setPageLabels(8, [ "A", "Appendix-", 1]);

   var s = this.getPageLabel(0);

   for (var i = 1; i < this.numPages; i++)

      s += ", " + this.getPageLabel(i);

   console.println(s);

The example will produce the following output on the console:

   i, ii, iii, 1, 2, 3, 4, 5, Appendix-A, Appendix-B

Example 2

Remove all page labels from a document.

   for (var i = 0; i < this.numPages; i++) {

      if (i + 1 != this.getPageLabel(i)) {

         // Page label does not match ordinal page number.

         this.setPageLabels(i);

      }

   }

setPageRotations

Rotates the specified pages in the current document.

See also getPageRotation.

Parameters

Example

Rotate pages 0 through 10 of the current document.

   this.setPageRotations(0, 10, 90);

setPageTabOrder

Sets the tab order of the form fields on a page. The tab order can be set by row, by column, or by structure.

If a PDF 1.4 document is viewed in Acrobat 6.0, tabbing between fields is in the same order as it is in Acrobat 5.0. Similarly, if a PDF 1.5 document is opened in Acrobat 5.0, the tabbing order for fields is the same as it is in Acrobat 6.0.

Parameters

Example

Set the page tab order for all pages to rows.

   for (var i = 0; i < this.numPages; i++)

      this.setPageTabOrder(i, "rows");

setPageTransitions

Sets the page transition for a specific range of pages.

See also getPageTransition.

Parameters

Example

Put the document into full screen mode and apply some transitions:

   this.setPageTransitions({ aTrans: [-1, "Random", 1] } );

   app.fs.isFullScreen=true;

spawnPageFromTemplate

Note:This method has been superseded by templates, createTemplate, and the Template object spawn method.

Spawns a page in the document using the given template, as returned by getNthTemplate. The template feature does not work in Adobe Reader.

Parameters

Returns

Prior to Acrobat 6.0, this method returned nothing. Now, this method returns an object representing the page contents of the page spawned. This return object can then be used as the value of the optional parameter oXObject for subsequent calls to spawnPageFromTemplate.

Note:Repeatedly spawning the same page can cause a large increase in file size. To avoid this problem, spawnPageFromTemplate now returns an object that represents the page contents of the spawned page. This return value can be used as the value of the oXObject parameter in subsequent calls to the spawnPageFromTemplate method to spawn the same page.

Example 1

Spawn each template page in the current document.

   var n = this.numTemplates;

   var cTempl;

   for (i = 0; i < n; i++) {

      cTempl = this.getNthTemplate(i);

      this.spawnPageFromTemplate(cTempl);

   }

Example 2 (Acrobat 6.0)

The following example spawns the same template 31 times using the oXObject parameter and return value. Using this technique avoids overly inflating the file size.

   var t = this.getNthTemplate(0)

   var XO = this.spawnPageFromTemplate(t, this.numPages, false, false);

   for (var i=0; i < 30; i++)

      this.spawnPageFromTemplate(t,this.numPages, false, false, XO);

submitForm

Submits the form to a specified URL. To call this method, you must be running inside a web browser or have the Acrobat Web Capture plug-in installed. (If the URL uses the “mailto” scheme, it will be honored even if not running inside a web browser, as long as the SendMail plug-in is present.) Beginning with Adobe Reader 6.0, you need not be inside a web browser to call this method.

Note:(Acrobat 6.0) Depending on the parameters passed, there are restrictions on the use of this method. See the notes embedded in the description of the parameters.

The https protocol is supported for secure connections.

Parameters

Example 1

Submit the form to the server.

   this.submitForm("http://www.example.com/cgi-bin/myscript.cgi#FDF");

Example 2

Submit selected form fields to a server-side script as FDF.

   var aSubmitFields = new Array( "name", "id", "score" );

   this.submitForm({

      cURL: "http://www.example.com/cgi-bin/myscript.cgi#FDF",

      aFields: aSubmitFields,

      cSubmitAs: "FDF" // the default, not needed here

   });

Example 3

This example shows a shortcut to submitting a whole subtree. Passing “name” as part of the field parameter, submits "name.title", "name.first", "name.middle" and "name.last".

   this.submitForm("http://www.example.com/cgi-bin/myscript.cgi#FDF",

      true, false, "name");

Example 4

Submit form as XFDF to a server-side script.

   this.submitForm({

      cURL: "http://www.example.com/cgi-bin/myscript.cgi#FDF",

      cSubmitAs: "XFDF"

   });

Example 5 (Acrobat 7.0)

For a PDF file that contains several XFA forms as attachments, the following script gathers the XML data from each attachment and concatenates them. The combined data is then submitted.

   var oParent = event.target;

   var oDataObjects = oParent.dataObjects;

   if (oDataObjects == null)

      app.alert("This form has no attachments!");

   else {

      var nChildren = oDataObjects.length;

      var oFirstChild = oParent.openDataObject(oDataObjects[0].name);

      var oSubmitData = oFirstChild.xfa.data.nodes.item(0).clone(true);
      for (var iChild = 1; iChild < nChildren; iChild++) {

         var oNextChild = oParent.openDataObject(

            oDataObjects[iChild].name);
         oSubmitData.nodes.append(oNextChild.xfa.data.nodes.item(0));
         oNextChild.closeDoc();

      }

      oParent.submitForm({

      cURL: "http://www.example.com/cgi-bin/myCGI.pl#FDF",
      cSubmitAs: "XML",
      oXML: oSubmitData

      });

      oFirstChild.closeDoc();

   }

This example uses dataObjects, openDataObject and properties and methods of the XFA object.

Example 6 (Acrobat 7.0)

Submits current document as a PDF. This script uses cPermID, cInstID and cUsageRights.

   this.submitForm({

      cUrl: myURL,

      cSubmitAs: "PDF",

      cPermID: someDoc.docID[0],

      cInstID: someDoc.docID[1],

      cUsageRights: submitFormUsageRights.RMA });

syncAnnotScan

Guarantees that all annotations will be scanned by the time this method returns.

To show or process annotations for the entire document, all annotations must have been detected. Normally, a background task runs that examines every page and looks for annotations during idle time, as this scan is a time-consuming task. Much of the annotation behavior works gracefully even when the full list of annotations is not yet acquired by background scanning.

In general, you should call this method if you want the entire list of annotations.

See also getAnnots.

Example

Wait for all annotations to be scanned, then get the array of annotations in the document and sort by author.

The second line of code is not executed until syncAnnotScan returns, which does not occur until the annotation scan of the document is completed.

   this.syncAnnotScan();

   annots = this.getAnnots({nSortBy:ANSB_Author});

   // Now, do something with the annotations.

timestampSign

Adds an invisible timestamp to a document.

Parameters

Returns

Returns TRUE if the signing was successful.

Example

var myEngine = security.getHandler( "Adobe.PPKLite" );

// Note that login is not required

 

this.timestampSign({

   oSig:myEngine,

   cDIPath:"/c/temp/TSsigSign.pdf",

   bUI:false

});

validatePreflightAuditTrail

Validates the current embedded audit trail.

Returns

The validity status ofthe current embedded audit trail. Validity values are.