Field methods

browseForFileToSubmit

If invoked on a text field for which the fileSelect flag is set (checked), opens a standard file-selection dialog box. The path entered through the dialog box is automatically assigned as the value of the text field.

If invoked on a text field in which the fileSelect flag is clear (unchecked), an exception is thrown.

Example

The following code references a text field with the file select flag checked. It is a mouse-up action of a button field.

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

   f.browseForFileToSubmit();

buttonGetCaption

Gets the caption associated with a button.

Use buttonSetCaption to set the caption.

Parameters

Returns

The caption string associated with the button.

Example

This example places pointing arrows to the left and right of the caption on a button field with icon and text.

   // A mouse enter event

   event.target.buttonSetCaption("=> "+ event.target.buttonGetCaption()

      +" <=");

   

   // A mouse exit event

   var str = event.target.buttonGetCaption();

   str = str.replace(/=> | <=/g, "");

   event.target.buttonSetCaption(str);

The same effect can be created by having the same icon for rollover and the same text, with the arrows inserted, for the rollover caption. This approach would be slower and cause the icon to flicker. The above code gives a very fast and smooth rollover effect because only the caption is changed, not the icon.

buttonGetIcon

Gets the Icon object of a specified type associated with a button.

See also the buttonSetIcon method for assigning an icon to a button.

Parameters

Returns

The Icon object.

Example

   // Swap two button icons.

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

   var g = this.getField("Button2");

   var temp = f.buttonGetIcon();

   f.buttonSetIcon(g.buttonGetIcon());

   g.buttonSetIcon(temp);

See also buttonSetIcon and buttonImportIcon.

buttonImportIcon

Imports the appearance of a button from another PDF file. If neither optional parameter is passed, the user is prompted to select a file.

See also buttonGetIcon, buttonSetIcon, addIcon, getIcon, importIcon, and removeIcon.

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, as follows:

1 — The user cancelled the dialog

0 — No error

-1 — The selected file could not be opened

-2 — The selected page was invalid

Example (Acrobat 5.0)

It is assumed that we are connected to an employee information database. We communicate with the database using the ADBC object and related objects. An employee’s record is requested and three columns are utilized, FirstName, SecondName, and Picture. The Picture column, from the database, contains a device-independent path to the employee’s picture, stored in PDF format. The script might look like this:

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

   f.buttonSetCaption(row.FirstName.value + " " + row.LastName.value);

   if (f.buttonImportIcon(row.Picture.value) != 0)

      f.buttonImportIcon("/F/employee/pdfs/NoPicture.pdf");

The button field “myPicture” has been set to display both icon and caption. The employee’s first and last names are concatenated to form the caption for the picture. Note that if there is an error in retrieving the icon, a substitute icon can be imported.

buttonSetCaption

Sets the caption associated with a button.

Use buttonGetCaption to get the current caption.

See buttonAlignX, buttonAlignY, buttonFitBounds, buttonPosition, buttonScaleHow, and buttonScaleWhen for details on how the icon and caption are placed on the button face.

Parameters

Example

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

   f.buttonSetCaption("Hello");

buttonSetIcon

Sets the icon associated with a button.

See buttonAlignX, buttonAlignY, buttonFitBounds, buttonPosition, buttonScaleHow, and buttonScaleWhen for details on how the icon and caption are placed on the button face.

Use either buttonGetIcon or doc.getIcon to get an Icon object that can be used for the oIcon parameter of this method.

Note:This method must be executed from script embedded within the document. Executing script containing buttonSetIcon in the console of the Adobe Reader, for example, will throw a NotAllowedError exception.

Parameters

Example

This example takes every named icon in the document and creates a list box using the names. Selecting an item in the list box sets the icon with that name as the button face of the field “myPictures”. What follows is the mouse-up action of the button field “myButton”.

   var f = this.getField("myButton")

   var aRect = f.rect;

   aRect[0] = f.rect[2];             // Place list box relative to the

   aRect[2] = f.rect[2] + 144;        // position of "myButton"

   var myIcons = new Array();

   var l = addField("myIconList", "combobox", 0, aRect);

   l.textSize = 14;

   l.strokeColor = color.black;

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

      myIcons[i] = this.icons[i].name;

   l.setItems(myIcons);

   l.setAction("Keystroke",

      'if (!event.willCommit) {\r\t'

      + 'var f = this.getField("myPictures");\r\t'

      + 'var i = this.getIcon(event.change);\r\t'

      + 'f.buttonSetIcon(i);\r'

      + '}');

The named icons themselves can be imported into the document through an interactive scheme, such as the example given in addIcon or through a batch sequence.

See also buttonGetCaption for a more extensive example.

checkThisBox

Checks or unchecks the specified widget.

Only check boxes can be unchecked. A radio button cannot be unchecked using this method, but if its default state is unchecked (see defaultIsChecked) it can be reset to the unchecked state using the resetForm. method of the Doc.

Note:For a set of radio buttons that do not have duplicate export values, you can set the value to the export value of the individual widget that should be checked (or pass an empty string if none should be).

Parameters

Example

Check a check box.

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

   f.checkThisBox(0,true);

clearItems

Clears all the values in a list box or combo box.

Related methods and properties include numItems, getItemAt, deleteItemAt, currentValueIndices, insertItemAt and setItems.

Example

Clear the field “myList” of all items.

   this.getField("myList").clearItems();

defaultIsChecked

Sets the specified widget to be checked or unchecked by default.

Note:For a set of radio buttons that do not have duplicate export values, you can set the defaultValue to the export value of the individual widget that should be checked by default (or pass an empty string if none should be checked).

Parameters

Returns

true on success.

Example

Change the default of “ChkBox” to checked, then reset the field to reflect the default value.

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

   f.defaultIsChecked(0,true);

   this.resetForm(["ChkBox"]);

deleteItemAt

Deletes an item in a combo box or a list box.

For a list box, if the current selection is deleted, the field no longer has a current selection. If this method is invoked again on the same field and no parameter is specified, unexpected behavior can result because there is no current selection to delete. Therefore, it is important to make a new selection (such as by using the currentValueIndices method) for the method to behave as documented.

Parameters

Example

Delete the current item in the list, then select the top item in the list.

   var a = this.getField("MyListBox");

   a.deleteItemAt();              // Delete current item, and...

   a.currentValueIndices = 0;     // select top item in list

getArray

Gets the array of terminal child fields (that is, fields that can have a value) for this Field object, the parent field.

Returns

An array of Field objects

Example

Make a calculation of the values of the child fields of the parent field.

   // f has 3 children: f.v1, f.v2, f.v3

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

   var a = f.getArray();

   var v = 0.0;

   for (j =0; j < a.length; j++) v += a[j].value;

   // v contains the sum of all the children of field "f"

getItemAt

Gets the internal value of an item in a combo box or a list box.

The number of items in a list can be obtained from numItems. See also insertItemAt, deleteItemAt, clearItems, currentValueIndices and setItems.

Parameters

Returns

The export value or name of the specified item.

Example

In the two examples that follow, assume there are three items on “myList”: “First”, with an export value of 1; “Second”, with an export value of 2; and “Third”, with no export value.

   // Returns value of first item in list, which is 1

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

   var v = f.getItemAt(0);

The following example shows the use of the second optional parameter. By setting it to false, the item name (face value) can be obtained, even if there is an export value.

   for (var i=0; i < f.numItems; i++)

      console.println(f.getItemAt(i,true) + ":  " + f.getItemAt(i,false));

The output to the console reads:

   1:            First

   2:            Second

   Third:        Third

getLock

Gets a Lock object, a generic object that contains the lock properties of a signature field.

See also setLock.

Returns

The Lock object for the field.

insertItemAt

Inserts a new item into a combo box or a list box.

Related methods and properties include numItems, getItemAt, deleteItemAt, clearItems, currentValueIndices and setItems.

Parameters

Example

   var l = this.getField("myList");

   l.insertItemAt("sam", "s", 0); /* inserts sam to top of list l */

isBoxChecked

Determines whether the specified widget is checked.

Note:For a set of radio buttons that do not have duplicate export values, you can get the value, which is equal to the export value of the individual widget that is currently checked (or returns an empty string, if none is).

Parameters

Returns

true if the specified widget is currently checked, false otherwise.

Example

Determine the state of the check box and report back with an alert box.

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

   var cbStatus = (f.isBoxChecked(0)) ? " " : " not ";

   app.alert("The box is" + cbStatus + "checked");

isDefaultChecked

Determines whether the specified widget is checked by default (for example, when the field gets reset).

Note:For a set of radio buttons that do not have duplicate export values, you can get the defaultValue, which is equal to the export value of the individual widget that is checked by default (or returns an empty string, if none is).

Parameters

Returns

true if the specified widget is checked by default, false otherwise.

Example

Determine if the specified check box is checked by default.

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

   var cbStatus = (f.isDefaultChecked(0)) ? "Checked" : "Unchecked";

   app.alert("The Default: " + cbStatus);

setAction

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

Related methods are the Bookmark object setAction method and the Doc methods setAction, addScript, and setPageAction.

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

Parameters

Example

Set up a button field with addField, add some properties, and a mouse-up action using setAction.

   var f = this.addField("actionField", "button", 0 , [20, 100, 100, 20]);

   f.setAction("MouseUp", "app.beep(0);");

   f.delay = true;

      f.fillColor = color.ltGray;

      f.buttonSetCaption("Beep");

      f.borderStyle = border.b;

      f.lineWidth = 3;

      f.strokeColor = color.red;

      f.highlight = highlight.p;

   f.delay = false;

setFocus

Sets the keyboard focus to this field. This can involve changing the page that the user is currently on or causing the view to scroll to a new position in the document. This method brings the document in which the field resides to the front, if it is not already there.

See also bringToFront.

Example

Search for a certain open document, then focus on the field of interest. This script uses app.activeDocs, which requires the disclosed property of the documents to be true, or the script to be run during console, batch or menu events.

   var d = app.activeDocs;

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

      if (d[i].info.Title == "Response Document") {

         d[i].getField("name").value="Enter your name here: "

         // also brings the doc to front.

         d[i].getField("name").setFocus();

         break;

      }

   }

setItems

Sets the list of items for a combo box or a list box.

Related methods and properties include numItems, getItemAt, deleteItemAt, currentValueIndices and clearItems.

Parameters

Examples

Get various fields (combo or list) and set items in the list using various techniques.

   var l = this.getField("ListBox");

   l.setItems(["One", "Two", "Three"]);

   

   var c = this.getField("StateBox");    

   c.setItems([["California", "CA"],["Massachusetts", "MA"],

      ["Arizona", "AZ"]]);

   

   var c = this.getField("NumberBox");

   c.setItems(["1", 2, 3, ["PI", Math.PI]]);

setLock

Controls which fields are to be locked when a signature is applied to this signature field. No modifications can be made to locked fields. If the signature is cleared, all fields that were locked become unlocked. The property settings can be obtained using getLock.

Note:The method can be executed during a batch, application initialization, or console event. See Privileged versus non-privileged context for details.

This method cannot be applied to a field that is in a document that is already signed.

Parameters

Returns

true if successful, otherwise false or throws an exception.

Lock Object

A generic JavaScript object containing lock properties. This object is passed to setLock and returned by getLock for a signature field. It contains the following properties.

signatureGetModifications

Returns an object containing information on modifications that have been made to the document after the signature field was signed. The information includes only the difference between the current and signed state of the document. Transient objects, such as objects added after the signature but then subsequently deleted, are not reported.

Returns

An object containing modification information. The object has the following properties:

Example

Write modification information back to the console.

   var sigField = this.getField( "mySignature" );

   var sigMods = sigField.signatureGetModifications();

   

   var formFieldsCreated = sigMods.formFieldsCreated;

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

      console.println( formFieldsCreated[i].name );

   

   var formFieldsDeleted = sigMods.formFieldsDeleted;

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

      console.println( formFieldsDeleted[i].name );

   

   var formFieldsFilledIn = sigMods.formFieldsFilledIn;

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

      console.println( formFieldsFilledIn[i].name );

   

   var formFieldsModified = sigMods.formFieldsModified;

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

      console.println( formFieldsModified[i].name );

   

   var spawnedPages = sigMods.spawnedPagesCreated;

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

      console.println( spawnedPages[i] );

   

   console.println( sigMods.numPagesDeleted );

signatureGetSeedValue

Returns a SeedValue object that contains the seed value properties of a signature field. Seed values are used to control properties of the signature, including the signature appearance, reasons for signing, and the person.

See signatureSetSeedValue.

Returns

A SeedValue object.

Example

Access the seed value for a signature field.

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

   var seedValue = f.signatureGetSeedValue();

   // displays the seed value filter and flags

   console.println( "Filter name:" + seedValue.filter);

   console.println( "Flags:" + seedValue.flags);

   // displays the certificate seed value constraints

   var certSpec = seedValue.certspec;

   console.println( "Issuer:" + certspec.issuer);

signatureInfo

Returns a SignatureInfo object that contains the properties of the signature. The object is a snapshot of the signature at the time that this method is called. A security handler may specify additional properties that are specific to the security handler.

Note:There are no restrictions on when this method can be called. However, the specified security handler, oSig, may not always be available. See the security.getHandler method for details.

Some properties of a signature handler, for example, certificates (a property of the SignatureInfo object), may return a null value until the signature is validated. Therefore, signatureInfo should be called again after signatureValidate.

Parameters

Returns

A SignatureInfo object that contains the properties of the signature. This type of object is also used when signing signature fields, signing FDF objects, or with the FDF object signatureValidate method.

Example

Access SignatureInfo object properties.

   // Get all info

   var f = getField( "Signature1" );

   f.signatureValidate();

   var s = f.signatureInfo();

   console.println( "Signature Attributes:" );

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

   

   // Get particular info

   var f = this.getField("Signature1"); // uses the ppklite sig handler

   var Info = f.signatureInfo();

   // Some standard signatureInfo properties

   console.println("name = " + Info.name);         

   console.println("reason = " + Info.reason);

   console.println("date = " + Info.date);

   

   // Additional signatureInfo properties from PPKLite

   console.println("contact info = " + Info.contactInfo);

   

   // Get the certificate; first (and only) one

   var certificate = Info.certificates[0];

   

   // Common name of the signer

   console.println("subjectCN = " +  certificate.subjectCN);

   console.println("serialNumber = " +  certificate.serialNumber);

   

   // Display some information about the distinguished name of signer

   console.println("subjectDN.cn = " + certificate.subjectDN.cn);

   console.println("subjectDN.o = " +  certificate.subjectDN.o);

signatureSetSeedValue

Sets properties that are used when signing signature fields. The properties are stored in the signature field and are not altered when the field is signed, the signature is cleared, or when resetForm is called. Use signatureGetSeedValue to obtain the property settings.

When setting seed values, keep in mind the following:

• Seed values should not be set on signed documents and cannot be set on certified documents. They are primarily used to configure fields on documents that are not yet signed.

• Setting a seed value often causes Acrobat not to display or not to use its default settings. For example, preset reasons are stored in the registry and specifying a signing reason causes the application to ignore the registry list so that only the custom reasons are displayed.

Note:The method can be executed during a batch, application initialization or console event. See Privileged versus non-privileged context for details.

Certifying signatures are signatures with a SignatureInfo object mdp property value of allowNone, default, or defaultAndComments.

Not allowed in Adobe Reader.

Refer to the Acrobat 8.0 Security Feature User Reference to obtain a deeper understanding of the use of signature seed values.

Parameters

SeedValue Object

A generic JavaScript object, passed to signatureSetSeedValue and returned by signatureGetSeedValue, which represents a signature seed value. It has the following properties:

CertificateSpecifier Object

This generic JavaScript object contains the certificate specifier properties of a signature seed value. Used in the certSpec property of the SeedValue object. This object contains the following properties:

Seed value timeStamp specifier object

The properties of the seed value timeStamp specifier object are as follows:

Example 1

Seed the signature field, which has yet to be signed, with MDP, legal attestations, and permitted reasons for signing.

   // Obtain the signature Field object:

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

   f.signatureSetSeedValue({

      mdp: "defaultAndComments",

      legalAttestations: ["Trust me and be at ease.",

         "You can surely trust the author."],

      reasons: ["This is a reason", "This is a better reason"],

      flags: 8

   })

Example 2

Sets the signing handler as PPKMS and the format as “adbe.pkcs7.sha1”.

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

   

   f.signatureSetSeedValue({

      filter: "Adobe.PPKMS",

      subFilter: ["adbe.pkcs7.sha1"],

      flags: 3

});

Example 3

Sets the signing handler as PPKLite and the issuer of the signer’s certificate as caCert. Both are mandatory seed values and signing will fail if either constraint is not met.

   var caCert = security.importFromFile("Certificate", "/C/temp/CA.cer");

   f.signatureSetSeedValue({

      filter: "Adobe.PPKLite",

      certspec: {

         issuer: [caCert],

         url: "http://www.example.com/enroll.html",

         flags : 2

      },

      flags: 1

   });

signatureSign

Signs the field with the specified security handler. See also security.getHandler and securityHandler.login.

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

Signature fields cannot be signed if they are already signed. Use resetForm to clear signature fields.

Parameters

Returns

true if the signature was applied successfully, false otherwise.

Example 1

Sign the “Signature” field with the PPKLite signature handler:

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

   myEngine.login( "dps017", "/c/profile/dps.pfx" );

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

   

   // Sign the field

   f.signatureSign( myEngine,

      {   password: "dps017",             // provide password

         location: "San Jose, CA",       // ... see note below

         reason: "I am approving this document",

         contactInfo: "dpsmith@example.com",

         appearance: "Fancy"});

Note:In the above example, a password was provided. This may or may not have been necessary depending whether the Password Timeout had expired. The Password Timeout can be set programmatically by securityHandler.setPasswordTimeout.

Example 2

Sign an certification signature field.

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

   myEngine.login( "dps017", "/c/profile/dps.pfx" );

   

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

   var s = { reason: "I am the author of this document",

         mdp: "allowNone" };

   f.signatureSign({

      oSig: myEngine,

      oInfo: s,

      bUI: false,

      cLegalAttest: "To reduce file size, fonts are not embedded."

   });

signatureValidate

Validates and returns the validity status of the signature in a signature field. This routine can be computationally expensive and take a significant amount of time depending on the signature handler used to sign the signature.

Note:There are no restrictions on when this method can be called. However, the parameter oSig is not always available. See security.getHandler for details.

Parameters

Returns

The validity status of the signature. Validity values are:

-1 — Not a signature field

0 — Signature is blank

1 — Unknown status

2 — Signature is invalid

3 — Signature of document is valid, identity of signer could not be verified

4 — Signature of document is valid and identity of signer is valid.

See the signVisible and statusText properties of the SignatureInfo object.

SignatureParameters object

A generic object with the following properties that specify which security handlers are to be used for validation by signatureValidate:

Example

Validate a signature, then report to the console.

   var f = this.getField("Signature1") // Get signature field

   var status = f.signatureValidate();

   var sigInfo = f.signatureInfo();

   if ( status < 3 )

       var msg = "Signature not valid! " + sigInfo.statusText;

   else

      var msg = "Signature valid! " + sigInfo.statusText;

   app.alert(msg);