data-id=javascript-apis

data-id=id1

JavaScript APIs

• Annotation APIs
• Security and Signature APIs
• App APIs
• Event APIs

data-id=53810

data-id=alerter

data-id=id2

Alerter

The Acrobat multimedia plug-in displays error alerts under various conditions such as a missing media file. JavaScript code can customize these alerts, either for an entire document or for an individual media player.

In an alert situation, the internal function app.media.alert is called with parameters containing information about the alert. The app.media.alert method handles the alert by looking for alerter objects and calling their dispatch methods, in this order:

args.alerter
doc.media.alerter
doc.media.stockAlerter

To handle alerts for a specific player, provide an alerter object in args.alerter when you call app.media.createPlayer or app.media.openPlayer.

To handle alerts for an entire document, set doc.media.alerter to an alerter object.

All alerts can be suppressed for a player or document by setting args.alerter or doc.media.alerter to null.

doc.media.stockAlerter provides the default alerts that are used if a custom alerter is not specified. This property is initialized automatically by app.media.alert. Normally, doc.media.stockAlerter would not be referenced in developer code.

data-id=alerter-methods

data-id=id3

Alerter methods

data-id=41501

data-id=dispatch

data-id=id4

dispatch

Called by app.media.alert to handle alert situations.

Parameters

• alert An Alert object (see below).

Returns

A Boolean value, true to stop further alert processing, false to continue processing.

data-id=41949

Alert object

Example 1: Open a media player and suppress all alerts for this player.

app.media.openPlayer({ alerter: null });

// A more elaborate way to do the same thing
app.media.openPlayer(
{
    alerter:
    {
        dispatch() { return true; }
    }
});

Example 2: For all players in this document, log any alerts to a text field and allow the normal alert box to be displayed.

function logAlerts( doc )
{
    count = 0;
    doc.alerter =
    {
        dispatch( alert )
        {
            doc.getField("AlertLog").value += "Alert #"
                + ++count + ": " + alert.type + "n";
        }
    }
}
logAlerts( this );

// Another way to keep the counter
function logAlerts( doc )
{
    doc.alerter =
    {
        count = 0,
        dispatch( alert )
        {
            doc.getField("AlertLog").value += "Alert #"
                + ++this.count + ": " + alert.type + "n";
        }
    }
}
logAlerts( this );

Example 3: Handle the PlayerError alert here, with defaults for other alerts.

this.media.alerter =
{
    dispatch( alert )
    {
        switch( alert.type )
        {
            case "PlayerError":
            app.alert( "Player error: " + alert.errorText );
            return true;
        }
    }
}

data-id=15210

data-id=alternatepresentation

data-id=id5

AlternatePresentation

This object provides an interface to the document’s particular alternate presentation. Use the Doc object method alternatePresentations to acquire an AlternatePresentation object.

See the PDF Reference for additional details on alternate presentations.

data-id=alternatepresentation-properties

data-id=id6

AlternatePresentation properties

data-id=45263

data-id=active

data-id=id7

active

This property is true if the presentation is currently active and false otherwise. When a presentation is active, it controls how the document that owns it is displayed.

Example: See the start method for an example.

data-id=39659

data-id=type

data-id=id8

type

The type of the alternate presentation. Currently, the only supported type is “SlideShow”.

data-id=alternatepresentation-methods

data-id=id9

AlternatePresentation methods

data-id=63957

data-id=start

data-id=id10

start

Switches the document view into the alternate presentation mode and sets the active property to true. An exception is thrown if this or any other alternate presentation is already active.

Parameters

Example: Assume there is a named presentation called “MySlideShow” within the document.

// oMySlideShow is an AlternatePresentation object
oMySlideShow = this.alternatePresentations.MySlideShow;
if (!oMySlideShow.active) oMySlideShow.start();

Note that this.alternatePresentations is used to access the specified presentation by property name.

data-id=40183

data-id=stop

data-id=id11

stop

Stops the presentation and switches the document into normal (PDF) presentation. An exception is thrown if this presentation is not active.

Example: In this example, oMySlideShow is an AlternatePresentations object. See start for a related example.

// Stop the show if already active
if (oMySlideShow.active) oMySlideShow.stop();

data-id=49491

data-id=bookmark

data-id=id237

Bookmark

A Bookmark object represents a node in the bookmark tree that appears in the bookmarks navigational panel. Bookmarks are typically used as a table of contents allowing the user to navigate quickly to topics of interest.

data-id=bookmark-properties

data-id=id238

Bookmark properties

data-id=98065

data-id=children

data-id=id239

children

An array of Bookmark objects that are the children of this bookmark in the bookmark tree. If there are no children of this bookmark, this property has a value of null.

See also the parent and bookmarkRoot properties.

Example: Dump all bookmarks in the document.

function DumpBookmark(bkm, nLevel)
{
    var s = "";
    for (var i = 0; i < nLevel; i++) s += " ";
    console.println(s + "+-" + bkm.name);
    if (bkm.children != null)
        for (var i = 0; i < bkm.children.length; i++)
            DumpBookmark(bkm.children[i], nLevel + 1);
}
console.clear(); console.show();
console.println("Dumping all bookmarks in the document.");
DumpBookmark(this.bookmarkRoot, 0);

data-id=71326

data-id=color

data-id=id240

color

Specifies the color for a bookmark. Values are defined by using gray, RGB or CMYK color. See Color arrays for information on defining color arrays and how values are used with this property. See also the style property.

Example: The following fun script colors the top-level bookmark red, green, and blue.

var bkm = this.bookmarkRoot.children[0];
bkm.color = color.black;
var C = new Array(1, 0, 0);
var run = app.setInterval(
    'bkm.color = ["RGB",C[0],C[1],C[2]]; C.push(C.shift());', 1000);
var stoprun=app.setTimeOut(
    "app.clearInterval(run); bkm.color=color.black",12000);

data-id=40682

data-id=id241

data-id=id242

doc

The Doc that the bookmark resides in.

data-id=76081

data-id=id243

data-id=id244

name

The text string for the bookmark that the user sees in the navigational panel.

Example: Put the top-level bookmark in bold.

var bkm = this.bookmarkRoot.children[0];
console.println( "Top-level bookmark name: " + bkm.name );

The example that follows the children property also uses the name property.

data-id=57280

data-id=open

data-id=id245

open

Determines whether the bookmark shows its children in the navigation panel (open) or whether the children subtree is collapsed (closed).

data-id=36697

data-id=parent

data-id=id246

parent

The parent bookmark of the bookmark or null if the bookmark is the root bookmark. See also the children and bookmarkRoot properties.

data-id=86167

data-id=id247

data-id=id248

style

Specifies the style for the bookmark’s font: 0 is normal, 1 is italic, 2 is bold, and 3 is bold-italic. See also the color property.

Example: The following code puts the top-level bookmark in bold.

var bkm = this.bookmarkRoot.children[0];
bkm.style = 2;

data-id=bookmark-methods

data-id=id249

Bookmark methods

data-id=81576

data-id=createchild

data-id=id250

createChild

Creates a new child bookmark at the specified location.

See also the children property and the insertChild and remove methods.

Parameters

Example: Create a bookmark at the top of the bookmark panel that takes you to the next page in the document.

this.bookmarkRoot.createChild("Next Page", "this.pageNum++");

data-id=81661

data-id=execute

data-id=id251

execute

Executes the action associated with this bookmark. This can have a variety of behaviors. See the PDF Reference for a list of common action types. See also the createChild method.

Example: Implement a simple search of the bookmarks. If successful, the action associated with the bookmark is executed.

// Document-level or folder-level JavaScript.
function searchBookmarks(bkm, nLevel, bkmName)
{
    if ( bkm.name == bkmName ) return bkm;
    if (bkm.children != null) {
        for (var i = 0; i < bkm.children.length; i++)
        {
            var bkMark = searchBookmarks(
                bkm.children[i], nLevel + 1, bkmName);
            if ( bkMark != null ) break;
        }
        return bkMark;
    }
    return null;
}
// Redefine this function for a more sophisticated compare.
function bmkCompare( name1, name2 )
{
        return ( name1 == name2 );
}

The following code initiates the search. This code could be executed as field-level JavaScript or be executed as a menu action.

var bkmName = app.response({
    cQuestion: "Enter the name of the bookmark to find",
    cTitle: "Bookmark Search and Execute"
});
if ( bkmName != null ) {
    var bkm = searchBookmarks(this.bookmarkRoot, 0, bkmName );
    if ( bkm != null ) bkm.execute();
    else app.alert("Bookmark not found");
}

data-id=61060

data-id=insertchild

data-id=id253

insertChild

Inserts the specified bookmark as a child of this bookmark. If the bookmark already exists in the bookmark tree, it is unlinked before inserting it back into the tree. In addition, the insertion is checked for circularities and disallowed if one exists. This prevents users from inserting a bookmark as a child or grandchild of itself. See also the children property and the createChild and remove methods.

Parameters

Example: Take the first child bookmark and move it to the end of the bookmarks.

var bm = bookmarkRoot.children[0];
bookmarkRoot.insertChild(bm, bookmarkRoot.children.length);

data-id=43068

data-id=remove

data-id=id254

remove

Removes the bookmark and all its children from the bookmark tree. See also the children property and the createChild and insertChild methods.

Example: Remove all bookmarks from the document.

bookmarkRoot.remove();

data-id=52228

data-id=setaction

data-id=id255

setAction

Sets a JavaScript action for a bookmark.

See also the Doc addRequirement and setPageAction methods and the Field object setAction method.

Note

This method overwrites any action already defined for this bookmark.

Parameters

Example: Attach an action to the topmost bookmark.

var bm = bookmarkRoot.children[0]
bm.setAction("app.beep(0);");

data-id=33812

data-id=catalog

data-id=id256

catalog

A static object that accesses the functionality provided by the Acrobat Catalog plug-in. This plug-in must be installed to interface with the catalog object.

Note

The Catalog plug-in (and the catalog object) is available only in Acrobat Pro.

See also the Index object, which is used to invoke various indexing operations provided by the Catalog plug-in, and the CatalogJob object.

data-id=catalog-properties

data-id=id257

catalog properties

data-id=59187

data-id=isidle

data-id=id258

isIdle

Returns true when Catalog is not busy with an indexing job.

data-id=22300

data-id=jobs

data-id=id259

jobs

Gets information about the Catalog jobs. Catalog maintains a list of its pending, in-progress, and completed jobs for each Acrobat session. Returns an array of CatalogJob objects.

data-id=catalog-methods

data-id=id260

catalog methods

data-id=87258

data-id=getindex

data-id=id261

getIndex

Uses a specified path of a Catalog index to get an Index object. The returned object can be used to perform various indexing operations such as building or deleting an index.

Parameters

Returns

The Index object.

data-id=37233

data-id=id262

data-id=id263

remove

Removes the specified CatalogJob object from Catalog’s job list. Catalog maintains a list of pending, in-progress, and completed jobs for each Acrobat session.

Parameters

Example: Delete all jobs that are pending and need complete rebuild.

if (typeof catalog != undefined)  {
    for (var i=0; i<catalog.jobs.length; i++){
        var job = catalog.jobs[i];
        console.println("Index: ", job.path);

        if (job.status == "Pending" && job.type == "Rebuild")
            catalog.remove(job);
    }
}

data-id=13857

data-id=catalogjob

data-id=id264

CatalogJob

This generic JavaScript object provides information about a job submitted to Catalog. It is returned by the build method of the Index object and the catalog.jobs property, and passed to catalog.remove.

data-id=catalogjob-properties

data-id=id265

CatalogJob properties

data-id=49309

data-id=path

data-id=id266

path

Device-independent path of the index associated with the job

data-id=58696

data-id=id267

data-id=id268

type

Type of indexing operation associated with the job.

Possible values are:

Build
Rebuild
Delete

data-id=20317

data-id=id269

data-id=id270

status

The status of the indexing operation.

Possible values are:

Pending
Processing
Completed
CompletedWithErrors

data-id=44855

data-id=certificate

data-id=id271

Certificate

The Certificate object provides read-only access to the properties of an X.509 public key certificate.

Related objects and methods are:

• security object: importFromFile and getSecurityPolicies
• DirConnection object: search

Field object: signatureInfo * FDF object: signatureValidate * RDN object

• Usage Object

Note

There are no security restrictions on this object.

data-id=certificate-properties

data-id=id272

Certificate properties

data-id=96257

data-id=binary

data-id=id273

binary

The raw bytes of the certificate, as a hex encoded string.

data-id=20527

data-id=issuerdn

data-id=id274

issuerDN

The distinguished name of the issuer of the certificate, returned as an RDN object.

data-id=87992

data-id=keyusage

data-id=id275

keyUsage

An array of strings indicating the value of the certificate key usage extension. Possible values are

kDigitalSignature    kDataEncipherment    kCRLSign
kNonRepudiation      kKeyAgreement        kEncipherOnly
kKeyEncipherment     kKeyCertSign         kDecipherOnly

data-id=40392

data-id=md5hash

data-id=id276

MD5Hash

The MD5 digest of the certificate, represented as a hex-encoded string. This provides a unique fingerprint for this certificate.

data-id=62254

data-id=privatekeyvalidityend

data-id=id277

privateKeyValidityEnd

The date before which it’s legal to use the private key associated with this certificate. If the PKUP extension is not present or this property isn’t present in the extension, this represents the validity end date of the certificate itself. Before a digital ID can be used for signing, Acrobat ensures that the signing time is prior to the privateKeyValidityEnd date.

data-id=63122

data-id=privatekeyvaliditystart

data-id=id278

privateKeyValidityStart

The date after which it’s legal to use the private key associated with this certificate. If the Private Key Usage Period (PKUP) certificate extension is not present, this represents the validity start date of the certificate itself. Before a digital ID can be used for signing, Acrobat ensures that the signing time is more recent than the privateKeyValidityStart date.

data-id=34510

data-id=sha1hash

data-id=id279

SHA1Hash

The SHA1 digest of the certificate, represented as a hex-encoded string. This provides a unique fingerprint for this certificate.

data-id=68894

data-id=serialnumber

data-id=id280

serialNumber

A unique identifier for this certificate, used in conjunction with issuerDN.

data-id=31991

data-id=subjectcn

data-id=id281

subjectCN

The common name of the signer.

data-id=23415

data-id=subjectdn

data-id=id282

subjectDN

The distinguished name of the signer, returned as an RDN object.

data-id=50891

data-id=ubrights

data-id=id283

ubRights

The application rights that can be enabled by this certificate, returned as a generic Rights object.

data-id=36240

Rights Object

A Rights object has the following properties.

data-id=81656

data-id=usage

data-id=id284

usage

The purposes for which this certificate may be used within the Acrobat environment returned as a Usage object.

data-id=87917

Usage Object

This generic JavaScript object represents a certificate usage value in the certificate.usage property. It has the following properties.

Example: Encrypt the currently open document for everyone in the address book. Address book entries that contain sign-only certificates, CA certificates, no certificates, or are otherwise unsuitable for encryption, are not included in the final recipient list.

var eng = security.getHandler( "Adobe.AAB" );
var dc = eng.directories[0].connect();
var recipients = dc.search();

var filteredRecipients = new Array();
for( i = 0; i < recipients.length; ++i ) {
    if( recipients[i].defaultEncryptCert &&
        recipients[i].defaultEncryptCert.usage.endUserEncryption ) {
        filteredRecipients[filteredRecipients.length] = recipients[i];
        continue;
    }
    if(recipients[i].certificates) {
        for( j = 0; j < recipients[i].certificates.length; ++j )
            if( recipients[i].certificates[j].usage.endUserEncryption ) {
                filteredRecipients[filteredRecipients.length]

                     = recipients[i];
                continue;
            }
    }
}
this.encryptForRecipients({
    oGroups:[{userEntities: filteredRecipients}]
});

data-id=74572

data-id=validityend

data-id=id285

validityEnd

The validity end date of the certificate. Before a digital ID can be used for signing, Acrobat ensures that the signing time is prior to the validityEnd date.

data-id=55071

data-id=validitystart

data-id=id286

validityStart

The validity start date of the certificate. Before a digital ID can be used for signing Acrobat, ensures that the signing time is more recent than the validityStart date.

data-id=29350

data-id=collab

data-id=id287

Collab

This static object represents the collaboration functionality.

data-id=collab-methods

data-id=id288

Collab methods

data-id=49904

data-id=addstatemodel

data-id=id289

addStateModel

Adds a new state model to Acrobat. A state model describes the valid states that an annotation using the model can have (see the Annotation object for details about getting and setting the state of an annotation). State models can be used to describe the workflow that a document review goes through and can be used for review management.

See also removeStateModel, getStateInModel, and transitionToState.

Parameters

data-id=10552

States object

This generic object represents a set of states in a state model and is passed as the oStates parameter. The elements in the object literal are the unique state identifiers and the values are objects having the following properties:

Example: Add a new state model with a unique name of “ReviewStates”:

Collab.addStateModel({
    cName: "ReviewStates",
    cUIName: "My Review",

     oStates:
    {
        "initial": {cUIName: "Haven't reviewed it"},
        "approved": {cUIName: "I approve"},
        "rejected": {cUIName: "Forget it"},
        "resubmit": {cUIName: "Make some changes"}
    },
    cDefault: "initial"
});

A state model can be removed with Collab.removeStateModel.

data-id=77375

data-id=documenttostream

data-id=id290

documentToStream

Saves a copy of a Doc and returns the contents as a stream object.

The document dirty property is preserved after this method is called and the original document is not modified.

Parameters

Returns

A ReadStream object.

data-id=90340

data-id=removestatemodel

data-id=id291

removeStateModel

Removes a state model that was previously added by calling addStateModel. Removing a state model does not remove the state information associated with individual annotations. If the model is removed and added again, all of the state information for the annotations is still available.

See also addStateModel, getStateInModel, and transitionToState.

Parameters

Example: Continuing the example in addStateModel, remove the state model “ReviewStates”:

// Remove the state model
Collab.removeStateModel("ReviewStates");

data-id=37083

data-id=id292

data-id=id293

color

The color object is a convenience static object that defines the basic colors. Use this object to set a property or call a method that requires a color array.

data-id=98898

data-id=color-arrays

data-id=id294

Color arrays

A color is represented in JavaScript as an array containing 1, 2, 4, or 5 elements corresponding to a Transparent, Gray, RGB, or CMYK color space, respectively. The first element in the array is a string denoting the color space type. The subsequent elements are numbers that range between zero and one inclusive. For example, the color red can be represented as ["RGB", 1, 0, 0].

Invalid strings or insufficient elements in a color array cause the color to be interpreted as the color black.

data-id=color-properties

data-id=id295

color properties

The color object defines the following colors.

Example: This example sets the text color of the field to red if the value of the field is negative, or to black if the field value is nonnegative.

var f = event.target; /* field that the event occurs at */
f.target.textColor = event.value < 0 ? color.red : color.black;

data-id=color-methods

data-id=id296

color methods

• convert
• equal

data-id=16408

data-id=convert

data-id=id297

convert

Converts the color space and color values specified by the color object to the specified color space:

• Conversion to the gray color space is lossy (in the same fashion that displaying a color TV signal on a black-and-white TV is lossy).
• The conversion of RGB to CMYK does not take into account any black generation or undercolor removal parameters.

Parameters

Returns

A color array.

Example: The return value of the code line below is the array ["CMYK", 0, 1, 1, 0].

color.convert(["RGB",1,0,0], "CMYK");

data-id=10606

data-id=equal

data-id=id298

equal

Compares two Color Arrays to see if they are the same. The routine performs conversions, if necessary, to determine if the two colors are indeed equal (for example, ["RGB",1,1,0] is equal to ["CMYK",0,0,1,0]).

Parameters

Returns

true if the arrays represent the same color, false otherwise.

Example:

var f = this.getField("foo");
if (color.equal(f.textColor, f.fillColor))
    app.alert("Foreground and background color are the same!");

data-id=40112

data-id=colorconvertaction

data-id=id299

colorConvertAction

This object describes a single color conversion action.

You can obtain colorConvertAction object from the Doc object method getColorConvertAction. The returned object can then be modified. A color conversion action is divided into a “match” section and an “action” section. The “match” section describes what sorts of objects can match this action. The Doc object method colorConvertPage, accepts an array of these actions, against which matches are attempted until a match is found.

data-id=colorconvertaction-properties

data-id=id300

colorConvertAction properties

data-id=60292

data-id=action

data-id=id301

action

Describes the action to perform if a match occurs.

The value of action is accessed through the constants.actions object of the colorConvertAction object as the following constants:

constants.actions object

data-id=95592

data-id=alias

data-id=id302

alias

If this action is an ink action then this describes the ink’s alias.

data-id=66014

data-id=colorantname

data-id=id303

colorantName

If this action is an ink action then this describes the colorant name.

See the related property isProcessColor.

data-id=41068

data-id=convertintent

data-id=id304

convertIntent

Defines the rendering intent used to color convert the object. For a detailed description of rendering intents, please see Table 4.20 of the PDF Reference.

The value of convertIntent is accessed through the constants.renderingIntents object of the colorConvertAction object.

data-id=84007

data-id=convertprofile

data-id=id305

convertProfile

Describes the color profile to which matching objects should be converted if the action is Convert. A list of available color profiles can be obtained from the printColorProfiles property of the app object

data-id=29705

data-id=embed

data-id=id306

embed

If the matched object is to be converted and embed is true, the resulting object will have a color profile embedded in the file. Otherwise, the object will be stored as the corresponding device color space for the profile to which the object was converted.

data-id=85716

data-id=isprocesscolor

data-id=id307

isProcessColor

If this action is an ink action and if isProcessColor is true, the ink represents a process color, and the colorantName should be one of Cyan, Magenta, Yellow, Black, Red, Green or Blue.

data-id=68063

data-id=matchattributesall

data-id=id308

matchAttributesAll

The value of the matchAttributesAll property is a bitmap containing object attributes (flags) to be matched. A match occurs if all flags match, i.e. if there is a complete match.

The flags are accessed through the constants.objectFlags object of the colorConvertAction object and are defined as follows:

data-id=47626

constants.objectFlags object

Note

The value of matchAttributesAll can be set by using the bitwise operators with the bit flags of constants.objectFlags.

Example: Match images that overprint.

var action = this.getColorConvertAction();
action.matchAttributesAll = action.constants.objFlags.ObjImage
               action.constants.objFlags.ObjOverprinting;

data-id=55787

data-id=matchattributesany

data-id=id309

matchAttributesAny

The value of the matchAttributesAny property is a bitmap containing object attributes to be matched. A match occurs if any of the flags match.

The flags are accessed through the constants.objectFlags object of the colorConvertAction object.

Note

The value of matchAttributesAny can be set by using the bitwise operators with the bit flags of constants.objectFlags.

data-id=23732

data-id=matchintent

data-id=id310

matchIntent

Matches the rendering intent used for the object. For a detailed description of rendering intents, please see Table 4.20 of the PDF Reference.

The value of matchIntent is accessed through the constants.renderingIntents object of the colorConvertAction object and are defined as follows:

data-id=56390

constants.renderingIntents object

data-id=45157

data-id=matchspacetypeall

data-id=id311

matchSpaceTypeAll

The value of the matchSpaceTypeAll property is a bitmap containing color space attributes (flags) to be matched. A match occurs if all flags match, i.e. if there is a complete match.

These two fields are bitmaps containing color space attributes to be matched. The first field will only match if all flags match, i.e. if there is a complete match. The second field will match if any of the flags match.

The flags are accessed through the constants.spaceFlags object of the colorConvertAction object and are defined as follows:

data-id=76159

constants.spaceFlags object

Note

The value of matchSpaceTypeAll can be set by using the bitwise operators with the bit flags of constants.spaceFlags.

data-id=78757

data-id=matchspacetypeany

data-id=id312

matchSpaceTypeAny

The value of the matchSpaceTypeAny property is a bitmap containing color space attributes (flags) to be matched. A match occurs if any of the flags match.

The flags are accessed through the constants.spaceFlags object of the colorConvertAction object.

Note

The value of matchSpaceTypeAny can be set by using the bitwise operators with the bit flags of constants.spaceFlags.

data-id=36011

data-id=preserveblack

data-id=id313

preserveBlack

If the matched object is to be converted and preserveBlack is true, the conversion will be done using a “black-preserving” transform, in which text or line art objects are handled specially. If a CMYK color is (0.0, 0.0, 0.0, 1.0), an RGB color is (0.0, 0.0, 0.0) or a gray color is (0.0), and preserveBlack is true, that color is considered special-case black, and is converted straight to black without using the conversion profile. The resulting color will be as described for the matching black color for the corresponding profile target color space, for example, if the convert profile is RGB, the resulting color will be (0.0, 0.0, 0.0) no matter what the color profile says.

data-id=66694

data-id=useblackpointcompensation

data-id=id314

useBlackPointCompensation

If useBlackPointCompensation is true, use black point compensation for all color conversions. The effect of this flag depends on the color management method (CMM) being used, but if the Adobe CMM is being used, colorimetric transforms are scaled such that black remains black no matter what the media black point of the source profile.

data-id=26749

data-id=collection

data-id=id315

Collection

A collection object is obtained from the Doc. collection property. Doc. collection returns a null value when there is no PDF collection (also called PDF package and PDF portfolio).

The collection object is used to set the initial document in the collection, set the initial view of the collection, and to get, add, and remove collection fields (or categories).

data-id=collection-properties

data-id=id316

Collection properties

data-id=67804

data-id=fields

data-id=id317

fields

The fields property is an array of collectionField objects in the collection.

Example: Enumerate all the collectionFields in a collection.

for (var i in collection.fields)

console.println(i);

data-id=10634

data-id=initialdoc

data-id=id318

initialDoc

Use the initialDoc property to specify the document in the collection that is initially viewed when the collection is opened. The value of initialDoc is the name property of the Data object of the initial document, or null if no initial document is specified.

Example: Set the initial document to the third file in the collection.

this.collection.initialDoc = this.dataObjects[2].name;

data-id=11002

data-id=initialview

data-id=id319

initialView

A string describing the initial collection view. Possible values include Tile, Details, Hidden, Custom, or null. The values of Tile and Details are built-in views, while Custom indicates that a document-based Navigator is preferred.

Example: Set the initial view to Details.

this.collection.initialView = "Details";

data-id=collection-methods

data-id=id320

Collection methods

data-id=23829

data-id=addfield

data-id=id321

addField

Adds a new field (or category) to the collection schema. The method throws an exception if the field already exits.

Returns

The collectionField object of the newly created field.

Example: Create a new field in the collection called "to" using object literal techniques.

this.collection.addField({name:"to", order:3, text:"To", type:"S"});

// The same example as above, but using ordered parameters.
this.collection.addField("to", "To", "S", 3);

data-id=87286

data-id=getfield

data-id=id322

getField

The getField method returns the collectionField object corresponding to the name of a collection field.

Parameters

Returns

A collectionField object, or null if the field is not found.

Example: Get the collectionField object of the "from" field.

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

data-id=70653

data-id=removefield

data-id=id323

removeField

Remove a field from the collection schema.

Parameters

Example: Remove the "from" field from the collection schema.

this.collection.removeField("from");

data-id=31572

data-id=collectionfield

data-id=id324

collectionField

The properties of the collectionField object are the fields (or categories) used by the collection. The text property (see below) is the (display) string the user sees in the user-interface with viewing a listing of the files files in the collection. Use the collectionField object to set the order the fields are listed in the user-interface, the sort order of the listing of the files, or to set a field as read only.

The collection field values for embedded files in the collection can be got or set through getFieldValue and setFieldValue methods of the Data object.

data-id=collectionfield-properties

data-id=id325

collectionField properties

data-id=50349

data-id=id326

data-id=id327

name

The string that specifies the name of the field.

data-id=70457

data-id=order

data-id=id328

order

Specifies the order the field is listed in relation to other fields. Field order is 0-based. When changing the value, if needed, the order of other fields will be incremented to prevent duplicates.

data-id=30423

data-id=id329

data-id=id330

readOnly

A Boolean value that specifies whether the user may change values of the field in the user interface. When readonly is true, no changes are allowed.

data-id=94450

data-id=sort

data-id=id331

sort

The value of sort specifies how this field contributes to the ordering of files in the collection.

If the value is 0, this field is not used to sort the files. If the absolute value is 1, this field is the primary sort field. If the absolute value is 2, the field is the secondary sort field (used to break ties on the primary sort field), and so on. Additionally, the sign of value indicates the direction in which the files should be sorted. Positive values indicate that the files are sorted in ascending order, and negative values indicate that files are sorted in descending order.

Example: To illustrate the sorting scheme, consider a simple set of 4 fields that describe an email inbox: From, Subject, To, and Received. Each file in the collection represents a single email message. Set the sort order for each of these fields as indicated below:

• From: 0
• To: 0
• Subject: 1
• Received: -2

The above sort order indicates that the primary sort field is "Subject" (the absolute value of the field is 1) and that files should be sorted in ascending order (the sign is positive). If two files have the same subject, the secondary sort field is consulted. In this case, the secondary sort field is "Received" (the absolute value of the field is 2) and it is specified to sort in descending order. The files are sorted by Subject in ascending order. Any files that have identical Subjects will be sorted in a subgroup by their Received field, but in descending order. The other fields do not contribute to the sort, since they are 0.

data-id=56468

data-id=text

data-id=id332

text

The value of text specifies the display text used by the field in the user-interface.

data-id=20646

data-id=id333

data-id=id334

type

A text string that specifies the type of data stored in the field. Possible values include:

• S, the value of this field is a string type.
• D, the value of this field is a date type.
• N, the value of this field is a number type.
• F, the value of this field is the file name of a member of the collection.
• Desc, the value of this field is a description string of a member of the collection.
• Size, the value of this field is the file size of a member of the collection.
• ModDate, the value of this field is the modification date of a member of the collection.
• CreationDate, the value of this field is the creation date of a member of the collection.
• CompressedSize, the value of this field is the compressed file size of a member of the collection.

The value of this property cannot be changed for a field that already exists. When a new field is created using the addField method, the type can be set.

Example: Modify and examine the properties of user-defined field "from".

var f = this.collection.getField("from");
f.visible = true;
f.order = 1;
f.text = "From";
console.println("Field name: " + f.name);
console.println("Field type: " + f.type);

data-id=78269

data-id=column

data-id=id335

Column

This generic JavaScript object contains the data from every row in a column. A column object is returned by the getColumn and getColumnArray methods of the Statement object. See also the ColumnInfo object.

data-id=column-properties

data-id=id336

Column properties

data-id=53313

data-id=columnnum

data-id=id337

columnNum

START HERE

The number identifying the column.

data-id=16818

data-id=id338

data-id=id339

name

The name of the column.

data-id=15970

data-id=id340

data-id=id341

type

One of the SQL Types for the data in the column.

data-id=45830

data-id=typename

data-id=id342

typeName

The name of the type of data the column contains.

data-id=56665

data-id=value

data-id=id343

value

The value of the data in the column, in the format in which the data was originally retrieved.

data-id=73870

data-id=columninfo

data-id=id344

ColumnInfo

This generic JavaScript object contains basic information about a column of data. It is returned by the getColumnList method of the Connection object. See also the Column object.

data-id=columninfo-properties

data-id=id345

ColumnInfo properties

data-id=87257

data-id=id346

data-id=id347

name

A string that represents the identifying name of a column. This string can be used in a call to the getColumn method of the Statement object identify the associated column.

data-id=33941

data-id=description

data-id=id348

description

A string that contains database-dependent information about the column.

data-id=62088

data-id=id349

data-id=id350

type

A numeric value identifying one of the ADBC SQL Types that applies to the data contained in the column associated with the ColumnInfo object.

data-id=22487

data-id=id351

data-id=id352

typeName

A string identifying the type of the data contained in the associated column. It is not one of the SQL Types (see type above), but a database-dependent string representing the data type. This property may give useful information about user-defined data types.

data-id=92099

data-id=console

data-id=id353

console

The console object is a static object that enables access to the Acrobat JavaScript Console for executing JavaScript and displaying debug messages.

This object does not function in Adobe Reader versions earlier than 7.0. Beginning with version 7.0, Adobe Reader has a console window. Its primary function is to report errors and messages. This capability is controlled by the JavaScript preference Show Console on Errors and Messages. Though the console is not interactive, the methods of the console object function as they do in Acrobat.

The debugging capability of the Acrobat JavaScript Debugging window can be made available for Adobe Reader for the Windows and Mac OS platforms. To debug within Adobe Reader, the JavaScript file debugger.js must be installed and the Windows registry must be edited appropriately. See the JavaScript Developer Guide for technical details.

See also the dbg object.

data-id=console-methods

data-id=id354

console methods

data-id=68659

data-id=clear

data-id=id355

clear

Clears the console windows buffer of any output.

data-id=70690

data-id=hide

data-id=id356

hide

Closes the console window.

data-id=92823

data-id=println

data-id=id357

println

Prints a string value to the console window with an accompanying carriage return.

Parameters

Example 1: This example prints the value of a field to the console window. The script could be executed during a mouse-up event.

var f = this.getField("myText");
console.clear(); console.show();
console.println("Field value = " + f.value);

Example 2: The console can be used as a debugging tool. For example, you can write values of variables to the console. The following script is at the document level:

var debugIsOn = true;
function myFunction ( n, m )
{
    if (debugIsOn)
    {
        console.println("Entering function: myFunction");
        console.println(" Parameter 1: n = " + n);
        console.println(" Parameter 2: m = " + m);
    }
    ....
    ....
    if (debugIsOn) console.println(" Return value: rtn = " + rtn);
    return rtn;
}

Beginning with Acrobat 6.0, debugging can also be accomplished with the JavaScript Debugger. See the dbg object.

data-id=54323

data-id=show

data-id=id358

show

Shows the console window.

Example: Clear and show the console window:

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

data-id=69212

data-id=data

data-id=id359

Data

The Data object is the representation of an embedded file or data stream that is stored in the document. See the PDF Reference for details.

Using Data objects is a good way to associate and embed source files, metadata, and other associated data with a document. Data objects can be inserted from the external file system, queried, and extracted.

See the following Doc properties and methods:

• createDataObject, dataObjects, exportDataObject, getDataObject, importDataObject, removeDataObject, openDataObject, getDataObjectContents, and setDataObjectContents.

The following objects, properties and methods support PDF portfolios (also called PDF collections or PDF packages):

• app.newCollection, Doc. collection, Collection object, and collectionField object

Note

The Data object methods were implemented in Acrobat 5.0. However, the ability to use them in Adobe Reader with additional usage rights only became available in Adobe Reader 6.0.

data-id=data-properties

data-id=id361

Data properties

data-id=35317

data-id=id362

data-id=id363

creationDate

The creation date of the file that was embedded.

data-id=89891

data-id=id364

data-id=id365

description

The description associated with this data object.

data-id=45643

data-id=id366

data-id=id367

MIMEType

The MIME type associated with this data object.

data-id=17649

data-id=id368

data-id=id369

modDate

The modification date of the file that was embedded.

data-id=27704

data-id=id370

data-id=id371

name

The name associated with this data object.

Example: Display the names of file attachments to this document.

console.println("Dumping all data objects in the document.");
var d = this.dataObjects;
for (var i = 0; i < d.length; i++)
    console.println("DataObject[" + i + "]=" + d[i].name);

data-id=11291

data-id=id372

data-id=id373

path

The file name and extension of the file that was embedded.

data-id=68523

data-id=id374

data-id=id375

size

The size, in bytes, of the uncompressed data object.

data-id=data-methods

data-id=id376

Data methods

data-id=72277

data-id=getfieldvalue

data-id=id377

getFieldValue

Get the value of the field as specified by the name parameter for this embedded file. When attempting to get a field value that is not defined in the collection schema, null is returned.

Parameters

Returns

The value of the field, or null if field is not present in schema.

data-id=16110

data-id=setfieldvalue

data-id=id378

setFieldValue

Type conversion is performed when setting field values. The type conversion is determined by the collectionField in the schema. When attempting to set a field value that is not defined in the schema, an exception is raised.

Parameters

Returns

The value of the field, or null if field is not present in schema.

Example: Get and set field values of the first data object in this collection.

var d = this.dataObjects[0];
d.setFieldValue("subject", "New laptop!", "RE: ");

// Now get the same field value we just set. Here s = "RE: New laptop!"
var s = d.getFieldValue({ name:"subject", includePrefix:true });

// Get the same field value, with includePrefix set to false, the default
// Now the value of s is "New laptop!".
s = d.getFieldValue("subject");

// Sets subject to "A. C. Robat" and clears prefix
d.setFieldValue("subject", "A. C. Robat");

data-id=80986

data-id=datasourceinfo

data-id=id379

DataSourceInfo

This generic JavaScript object contains basic information about a database. The ADBC.getDataSourceList method returns an array of these objects.

data-id=datasourceinfo-properties

data-id=id380

DataSourceInfo properties

data-id=59989

data-id=id381

data-id=id382

name

A string that represents the identifying name of a database. This string can be passed to newConnection to establish a connection to the database that the DataSourceInfo object is associated with.

data-id=21861

data-id=id383

data-id=id384

description

A string that contains database-dependent information about the database.

data-id=65262

data-id=dbg

data-id=id385

dbg

The dbg object is a static object that can be used to control the JavaScript Debugger from a command-line console. Its methods provide the same functionality as the buttons in the JavaScript Debugger dialog box toolbar. In addition, breakpoints can be created, deleted, and inspected using the dbg object.

The dbg object and the JavaScript Debugger are only available in Acrobat Pro.

Note

If the viewer locks up during a debugging session, pressing Esc may resolve the problem.

Debugging is not possible with a modal dialog box open; for example, when debugging a batch sequence.

Debugging a script with a running event initiated by either app.setInterval or app.setTimeOut may cause recurring alert boxes to appear. Use Esc after the modal dialog box is dismissed to resolve the problem.

(Acrobat 7.0) While the Debugger is open and a debugging session is under way, the Acrobat application is unavailable.

data-id=dbg-properties

data-id=id386

dbg properties

data-id=45894

data-id=bps

data-id=id387

bps

An array of breakpoint generic objects corresponding to breakpoints set in the debugger. This object contains the following properties and methods.

Example: List all currently active breakpoints.

var db = dbg.bps
for ( var i = 0; i < db.length; i++ )
{
    for ( var o in db[i] ) console.println(o + ": " + db[i][o]);
    console.println("------------------------------------");
}

See sb for another example of usage.

data-id=dbg-methods

data-id=id388

dbg methods

data-id=24979

data-id=c

data-id=id389

c

The c (continue) method resumes execution of a program stopped in the debugger. The JavaScript program may either stop again, depending on where the breakpoints are set, or reach execution end.

data-id=54263

data-id=cb

data-id=id390

cb

The cb (clear breakpoint) method clears a breakpoint in the debugger. The dbg.cb method dirties the document only if breakpoints are stored in the document, as set through the user preferences, Edit > Preferences > JavaScript.

Parameters

data-id=14994

data-id=q

data-id=id391

q

The q (quit) method quits debugging and executing the current JavaScript. It additionally dismisses the debugger dialog box.

data-id=85448

data-id=sb

data-id=id392

sb

The sb (set breakpoint) method sets a new breakpoint in the debugger. The dbg.sb method dirties the document only if breakpoints are stored in the document, as set through the user preferences, Edit > Preferences > JavaScript.

Parameters

Example 1: Some script is run and an exception is thrown due to some error. A breakpoint is programmatically set using the information given in the error message.

SyntaxError: missing ; before statement 213:Document-Level: myDLJS
// now set a breakpoint using the console
dbg.sb({
    fileName: "Document-Level: myDLJS",
    lineNum: 213,
    condition: "true"
});

Example 2: Simulate the functionality of the Store Breakpoints in PDF File check box in the JavaScript user preferences.

// Save breakpoints in PDF file
this.addScript("myBreakpoints", "var myBPS = " + dbg.bps.toSource());

// Now reset the breakpoints
for ( var i = 0; i < myBPS.length; i++ ) dbg.sb( myBPS[i] );

Example 3: Set a conditional break. Consider the following code, which is a mouse-up action.

for (var i=0; i<100; i++)
    myFunction(i);          // defined at document level

// In the console, set a conditional break. Here, we break when the

 // index of the loop is greater than 30.
dbg.sb({
    fileName:"AcroForm:Button1:Annot1:MouseUp:Action1",
    lineNum:2,
    condition:"i > 30"
})

data-id=70905

data-id=si

data-id=id393

si

The si (step in) method advances the program pointer to the next instruction in the JavaScript program, entering each function call for which there is a script defined. (Native JavaScript calls cannot be stepped into.)

data-id=67180

data-id=sn

data-id=id394

sn

The sn (step instruction) method advances the program pointer to the next bytecode in the JavaScript program. (Each JavaScript instruction is made up of several bytecodes as defined by the JavaScript interpreter.)

data-id=47502

data-id=so

data-id=id395

so

The so (step out) method executes the program until it exits the current function. Execution stops at the instruction immediately following the call to the current function. If the scope currently under debug is the top-level scope, the program either continues executing until it ends or stops again when it reaches a breakpoint.

data-id=92782

data-id=sv

data-id=id396

sv

The sv (step over) method advances the program pointer to the next instruction in the JavaScript program. If a function call is encountered, the debugger does not step into the instructions defined inside that function.

data-id=26032

data-id=dialog

data-id=id397

Dialog

An instance of this object is passed as a parameter to dialog box handlers (see Dialog box handlers). These handlers include the initialize, validate, commit, destroy and ItemID methods of the dialog box descriptor object literal that is passed to app.execDialog. The Dialog object allows the current state of the Dialog to be queried and set.

data-id=dialog-methods

data-id=id398

Dialog methods

data-id=83122

data-id=enable

data-id=id399

enable

Enables or disables various dialog box elements using the object literal passed in.

Typically, enable is called in the initialize method (see Dialog box handlers) of the object literal passed to app.execDialog to preset whether various dialog box elements are enabled or not.

Parameters

Example: See the examples following app. execDialog.

data-id=99912

data-id=end

data-id=id400

end

Terminates a currently executing dialog box (as if the Cancel button had been pressed). This method takes an optional parameter of the ItemID, a string, of the dialog box element that will be reported as dismissing the dialog. This ItemID will be the return value of the app.execDialog call that created the dialog.

Parameters

Example: See the examples following app. execDialog.

data-id=32700

data-id=load

data-id=id401

load

Sets the values of dialog box elements using the object literal passed in. Dialog box items are identified by an ItemID which is a unique 4-character string.

Typically, load is called in the initialize method (see Dialog box handlers) of the object literal passed to app.execDialog to preset the value of various dialog box elements.

Parameters

Example: See the examples following app. execDialog.

data-id=63111

data-id=store

data-id=id402

store

Gets the values of dialog box elements as an object literal returned. Dialog box items are identified by an ItemID, which is a unique 4-character string. For each dialog box element, there will be an entry in the object literal with the ItemID as the label and the dialog box element setting as the contents. If the dialog box element takes multiple values (for example, a list_box or a popup), the value should be an object literal consisting of the displayed entry as the label and a numeric value as the contents. If the numeric value is greater than 0, the item was selected, otherwise it was not selected.

Typically, store is called in the commit method (see Dialog box handlers) of the object literal passed to app.execDialog to extract the value of various dialog box elements.

Returns

object literal

data-id=70131

data-id=dirconnection

data-id=id403

DirConnection

This object represents an open connection to a directory: a repository of user information, including public-key certificates. Directory connections are opened using the Directory object connect method. A directory with a particular name can have more than one connection open at a time. All DirConnection objects must support all properties and methods listed here, unless otherwise specified.

Note

This object can only be obtained from a Directory object and is thus governed by the security restrictions of the Directory object. The DirConnection object is therefore available only for batch, console and application initialization, including in Adobe Reader. See also priv.

data-id=dirconnection-properties

data-id=id404

DirConnection properties

data-id=61351

data-id=canlist

data-id=id405

canList

Indicates whether the directory connection is capable of listing all of its entries. Some directories may contain too many entries for this operation to be practical.

Example: The AAB directory allows listing of the local trusted identity list.

var sh = security.getHandler( "Adobe.AAB" );
var dc = sh.directories[0].connect();
console.println( "CanList = " + dc.canList );

data-id=54768

data-id=candocustomsearch

data-id=id406

canDoCustomSearch

Specifies whether the directory connection supports searching using directory-specific search parameter attributes. For example, directory-specific attributes for an LDAP directory include o (organization), c (country), cn (common name), givenname, sn (surname), uid, st, postalcode, mail, and telephonenumber.

data-id=19446

data-id=candocustomuisearch

data-id=id407

canDoCustomUISearch

Specifies whether the directory connection supports searching using its own custom user interface to collect the search parameters.

data-id=64521

data-id=candostandardsearch

data-id=id408

canDoStandardSearch

Specifies whether the directory connection supports search using standard search parameter attributes. The standard attributes are

firstName
lastName
fullName
email
certificates

Some directory database implementations may not support these attributes, but directory handlers are free to translate these attributes to names understood by the directory.

data-id=38818

data-id=groups

data-id=id409

groups

An array of language-dependent names for groups that are available through this connection.

data-id=68524

data-id=id410

data-id=id411

name

The language-independent name of the directory that this object is connected to. An example of this would be Adobe.PPKMS.ADSI.dir0. All DirConnection objects must support this property.

data-id=66947

data-id=uiname

data-id=id412

uiName

The language-dependent string of the directory this object is connected to. This string is suitable for user interfaces. All DirConnection objects must support this property.

data-id=dirconnection-methods

data-id=id413

DirConnection methods

data-id=65566

data-id=search

data-id=id414

search

Searches the directory and returns an array of UserEntity objects that match the search parameters. A UserEntity object is a generic object that contains properties for all attributes that were requested by the setOutputFields method. If the setOutputFields method is not called prior to a search, it would return a UserEntity object containing no entries.

Parameters

Returns

An array of UserEntity objects.

Example 1: Directory search.

var sh = security.getHandler( "Adobe.PPKMS" );
var dc= sh.directories[0].connect();
dc.setOutputFields( {oFields:["certificates","email"]} )
var retVal = dc.search({oParams:{lastName:"Smith"}});
if( retVal.length )
console.println( retVal[0].email );

Example 2: List all entries in a local Acrobat Address Book. The script searches the directory and returns an array of users, along with their certificate information.

var sh = security.getHandler( "Adobe.AAB" );
var dc = sh.directories[0].connect();
if( dc.canList ) {
    var x = dc.search();
    for( j=0; j<x.length; ++j ) {
        console.println("Entry[" + j + "] = " + x[j].fullName + ":");
        for(i in x[j]) console.println("  " + i + " = " + x[j][i]);
    }
}

data-id=45615

UserEntity object

A generic JavaScript object that describes a user in a directory and the user’s associated certificates. It contains standard properties that have a specific meaning for all directory handlers. Directory handlers translate these entries to the ones that are specific to them when required. An array of these objects is returned by the search method of the DirConnection object.

It has the following properties

data-id=89710

data-id=setoutputfields

data-id=id415

setOutputFields

Defines the list of attributes that should be returned when executing the search method.

Note

This method is not supported by the Adobe.AAB directory handler. Custom options are not supported by the Adobe.PPKMS.ADSI directory handler.

Parameters

Returns

An array of strings, containing the names of attributes from oFields that are not supported by this directory. An empty array is returned if the oFields array is empty.

Example: In this example, dc.setOutputFields returns the array of strings ["x", "y"].

var sh = security.getHandler("Adobe.PPKMS");
var dc = sh.directories[0].connect();
var w = dc.setOutputFields( [ "certificates", "email", "x", "y"] );
console.println( w );

See also the examples that follow the DirConnection.search method.

data-id=60701

data-id=directory

data-id=id416

Directory

Directories are a repository of user information, including public-key certificates. Directory objects provide directory access and are obtained using the directories property or the newDirectory method of the SecurityHandler object.

Acrobat 6.0 and later provides several directories. The Adobe.AAB Security Handler has a single directory named Adobe.AAB.AAB. This directory provides access to the local Acrobat Address Book, also called the trusted identity store. On Windows, the Adobe.PPKMS Security Handler provides access through the Microsoft Active Directory Script Interface (ADSI) to as many directories as have been created by the user. These directories are created sequentially with names Adobe.PPKMS.ADSI.dir0, Adobe.PPKMS.ADSI.dir1, and so on.

Note

This object can only be obtained from a SecurityHandler object and is thus governed by the security restrictions of the SecurityHandler object. The Directory object is therefore available only for batch, console and application initialization, including in Adobe Reader. See also priv.

data-id=directory-properties

data-id=id417

Directory properties

data-id=53347

data-id=info

data-id=id418

info

The value of this property is a DirectoryInformation object, a generic object used to set and get the properties for this Directory object.

Example:

// Create and activate a new directory
var oDirInfo = { dirStdEntryID: "dir0",
    dirStdEntryName: "Employee LDAP Directory",
    dirStdEntryPrefDirHandlerID: "Adobe.PPKMS.ADSI",
    dirStdEntryDirType: "LDAP",
    server: "ldap0.example.com",
    port: 389 };
var sh = security.getHandler( "Adobe.PPKMS" );
var newDir = sh.newDirectory();
newDir.info = oDirInfo;

data-id=56624

DirectoryInformation object

A directory information object is a generic object representing the properties for a directory and has the following standard properties.

Directory information objects can include additional properties that are specific to a particular directory handler. The Adobe.PPKMS.ADSI directory handler includes the following additional properties:

Example 1: Create and activate a new directory.

var oDirInfo = { dirStdEntryID: "dir0",
    dirStdEntryName: "Employee LDAP Directory",
    dirStdEntryPrefDirHandlerID: "Adobe.PPKMS.ADSI",
    dirStdEntryDirType: "LDAP",
    server: "ldap0.example.com",
    port: 389
};
var sh = security.getHandler( "Adobe.PPKMS" );
var newDir = sh.newDirectory();
newDir.info = oDirInfo;

Example 2: Get information for an existing directory.

var sh = security.getHandler("Adobe.PPKMS");
var dir0 = sh.directories[0];
// Get directory info object just once for efficiency
var dir0Info = dir0.info;
console.println( "Directory " + dir0Info.dirStdEntryName );
console.println( "address " + dir0Info.server + ":" + dir0Info.port );

data-id=directory-methods

data-id=id419

Directory methods

data-id=36168

data-id=connect

data-id=id420

connect

Returns a DirConnection object that is a connection to the directory with the specified name. There can be more than one active connection for a directory.

See also the DirConnection object and the SecurityHandler object’s directories property.

Parameters

Returns

A DirConnection object, or null if there is no directory with the specified name.

Example: Enumerate available directories and connect.

var sh = security.getHandler( "Adobe.PPKMS" );
var dirList = sh.directories;
for ( var i=0; i< dirList.length; i++)
    for ( var o in dirList[i].info )
        console.println( o + " = " + dirList[i].info[o]);
var dirConnection = dirList[0].connect();

data-id=92005

data-id=embedded-pdf

data-id=id421

Embedded PDF

This object describes an API exposed to the object model of a container application that allows sending and receiving messages from an embedded PDF document. For example, when a PDF document is embedded in an HTML document using the <OBJECT> tag, the PDF object is scripted in the browser scripting context.

The HostContainer object provides the corresponding interface in the PDF scripting model. Both the container and PDF document must explicitly allow this communication to occur for security reasons.

data-id=embedded-pdf-properties

data-id=id422

Embedded PDF properties

data-id=71300

data-id=messagehandler

data-id=id423

messageHandler

This property allows a script running in the web browser scripting context to register a notification object that will be called if a script in the PDF document calls the Doc hostContainer.postMessage method.

The value of this property is an object that may expose the following methods.

When the methods are invoked, the this object will be the messageHandler instance that the method is being called on. Properties on the messageHandler property that begin with on are reserved for future use as notification methods.

If the PDF document has had the postMessage method called on it prior to this method being registered, all of the queued messages will subsequently be passed to the messageHandler object once it is set.

Messages are guaranteed to be delivered in the order in which they are posted and errors are guaranteed to be delivered in the order in which they occurred. However, there is no correspondence between the delivery order of messages and errors.

Exceptions thrown from within the handler methods will be discarded. Messages and errors will not be delivered while inside an onMessage / onError handler.

Note

This property is not implemented on the Mac OS platform.

data-id=embedded-pdf-methods

data-id=id424

Embedded PDF methods

data-id=48590

data-id=postmessage

data-id=id425

postMessage

Sends a message asynchronously to the PDF document message handler if the PDF document has disclosed itself by returning true from the onDisclosed method of the HostContainer object messageHandler property.

The message is passed to the onMessage method of the messageHandler.

If the PDF document does not disclose itself to the host container, an error will be passed to the onError method of the messageHandler property at some later point after postMessage has returned. If the PDF document has not registered to receive events by setting the Doc hostContainer.messageHandler property, the events will be queued until the PDF document sets the property.

The messages will be submitted to a queue of messages until they are delivered. If the queue size exceeds a maximum, an error will be thrown until some of the messages in the queue have been delivered.

Parameters

Note

This method is not implemented on the Mac OS platform.

data-id=13935

data-id=error

data-id=id426

Error

Error objects are dynamically created whenever an exception is thrown from methods or properties implemented in JavaScript. Several subclasses of the Error object can be thrown by core JavaScript (EvalError, RangeError, SyntaxError, TypeError, ReferenceError, URLError). They all have the Error object as prototype. JavaScript can throw some of these exceptions, or implement subclasses of the Error object at its convenience. If your scripts are using the mechanism of try/catch error handling, the object thrown should be one of the types listed in the following table.

Error object types implemented by JavaScript inherit properties and methods from the core Error object. Some JavaScript objects may implement their own specific types of exception. A description of the Error subclass (with added methods and properties, if any) should be provided in the documentation for the particular object.

Example: Print all properties of the Error object to the console.

try {
    app.alert(); // one argument is required for alert
} catch(e) {
    for (var i in e)
    console.println( i + ": " + e[i])
}

data-id=error-properties

data-id=id427

Error properties

data-id=50406

data-id=filename

data-id=id428

fileName

The name of the script that caused the exception to be thrown.

data-id=67199

data-id=linenumber

data-id=id429

lineNumber

The offending line number from where an exception was thrown in the JavaScript code.

data-id=43381

data-id=extmessage

data-id=id430

extMessage

A message providing additional details about the exception.

data-id=71361

data-id=message

data-id=id431

message

The error message providing details about the exception.

data-id=24685

data-id=id432

data-id=id433

name

The name of the Error object subclass, indicating the type of the Error object instance.

data-id=error-methods

data-id=id434

Error methods

data-id=69913

data-id=tostring

data-id=id435

toString

Gets the error message that provides details about the exception.

Returns

The error message string. (See the message property.)

data-id=43659

data-id=fdf

data-id=id538

FDF

This object corresponds to a PDF-encoded data exchange file. Typically, FDF files contain forms data that is exported from a PDF file. However, FDF files can also be used as general purpose data files and it is for this latter purpose that the FDF object exists.

All security methods and properties are available only during batch, console, and application initialization events. See priv.

data-id=fdf-properties

data-id=id539

FDF properties

data-id=61881

data-id=deleteoption

data-id=id540

deleteOption

Indicates whether the FDF file should be automatically deleted after it is processed. This value may or may not be used, depending on the content of the FDF file and how it is processed. It is used for embedded files beginning in Acrobat 6.0. Allowed values are

• 0: (default) Acrobat will automatically delete the FDF file after processing
• 1: Acrobat will not delete the FDF file after processing (however, a web or email browser may still delete the file).
• 2: Acrobat will prompt the user to determine whether to delete the FDF file after processing (however, a web or email browser may still delete the file).

data-id=83309

data-id=issigned

data-id=id541

isSigned

Returns true if the FDF data file is signed.

Example: See if the fdf is signed.

var fdf = app.openFDF("/C/temp/myDoc.fdf");
console.println( "It is "+ fdf.isSigned + " that this FDF is signed");
fdf.close();

See a more complete example following signatureSign.

data-id=69469

data-id=numembeddedfiles

data-id=id542

numEmbeddedFiles

The number of files embedded in the FDF file. If the FDF object is a valid FDF file, no exceptions will be thrown.

A file may be embedded in an FDF file with the addEmbeddedFile method. Example: Create a new FDF object, embed a PDF doc, save the FDF, open the FDF again, and count the number of embedded files.

var fdf = app.newFDF();
fdf.addEmbeddedFile("/C/myPDFs/myDoc.pdf");
fdf.save("/c/temp/myDocWrapper.fdf");
fdf = app.openFDF("/c/temp/myDocWrapper.fdf");
console.println("The number of embedded files = "
    + fdf.numEmbeddedFiles);
fdf.close();

data-id=fdf-methods

data-id=id543

FDF methods

data-id=59252

data-id=addcontact

data-id=id544

addContact

Adds a contact to the FDF file.

Parameters

Returns

Throws an exception on failure.

Example:

var oEntity={firstName:"Fred", lastName:"Smith", fullName:"Fred Smith"};
var f = app.newFDF();
f.addContact( oEntity );
f.save( "/c/temp/FredCert.fdf" );

data-id=10402

data-id=addembeddedfile

data-id=id545

addEmbeddedFile

Add the specified file to the end of the array of embedded files in the FDF file. Anyone opening the FDF file will be instructed to save the embedded file or files according to nSaveOption. If the embedded file is a PDF file, it is opened and displayed. If the embedded file is an FDF file, the file is opened for processing.

FDF files containing embedded files have been supported beginning with Acrobat 4.05. An example use for embedding PDF files is when these files are hosted on an HTTP server and the user should click to download and save the PDF file, rather than viewing the file in the browser. There is no relationship between these embedded files and files that are associated with forms data that is stored in an FDF file.

Parameters

Returns

Throws an exception if this operation could not be completed, otherwise returns the number of embedded files that are now in the FDF file.

Example: Create a new FDF, embed a PDF doc, then save.

var fdf = app.newFDF();
fdf.addEmbeddedFile("/C/myPDFs/myDoc.pdf");
fdf.save("/c/temp/myDocs.fdf");

data-id=71568

data-id=addrequest

data-id=id546

addRequest

Adds a request to the FDF file. There can be only one request in an FDF file. If the FDF file already contains a request, it is replaced with this new request.

Parameters

Returns

Throws an exception if there is an error.

Example:

var f = app.newFDF();
f.addRequest( "CMS", "http://www.example.com/cgi.pl", "Acme Corp" );
f.save( "/c/tmp/request.fdf" );

data-id=49024

data-id=close

data-id=id547

close

Immediately closes the FDF file.

Returns

Throws an exception if there is an error.

See the FDF object save method, which also closes an FDF file.

Example: See example following the addEmbeddedFile method.

data-id=38284

data-id=mail

data-id=id548

mail

Saves the FDF object as a temporary FDF file and mails this file as an attachment to all recipients, with or without user interaction. The temporary file is deleted after it is no longer needed.

See also a pp. mailGetAddrs, app. mailMsg, the Doc methods mailDoc and mailForm, and the Report object method mail.

Note

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

Parameters

Returns

Throws an exception if there is an error.

Example:

var fdf = app.openFDF( "/c/temp/myDoc.fdf" );
/* This opens the compose new message window */
fdf.mail();

/* This will send out the mail with the attached FDF file to fun1@example.com

 and fun2@example.com */
fdf.mail( false, "fun1@example.com", "fun2@example.com", "",
    "This is the subject", "This is the body.");

data-id=72930

data-id=save

data-id=id549

save

Save the FDF object as a file. A save will always occur. The file is closed when it is saved and the FDF object no longer contains a valid object reference.

See the close method, which also closes a FDF file.

Parameters

Returns

Throws an exception if there is an error.

Example: Create a new FDF, embed a PDF doc, then save.

var fdf = app.newFDF()
fdf.addEmbeddedFile("/C/myPDFs/myDoc.pdf");
fdf.save("/c/temp/myDocs.fdf");

data-id=98207

data-id=signatureclear

data-id=id550

signatureClear

If the FDF object is signed, clears the signature and returns true if successful. Does nothing if the FDF object is not signed. Does not save the file.

Returns

true on success.

data-id=33751

data-id=signaturesign

data-id=id551

signatureSign

Sign the FDF object with the specified security object. FDF objects can be signed only once. The FDF object is signed in memory and is not automatically saved as a file to disk. Call save to save the FDF object after it is signed. Call signatureClear to clear FDF signatures.

Parameters

Returns

true if the signature was applied successfully, false otherwise.

Example: Open an existing FDF data file and sign.

var eng = security.getHandler( "Adobe.PPKLite" );
eng.login("myPassword","/c/test/Acme.pfx");
var myFDF = app.openFDF( "/c/temp/myData.fdf" );
if( !myFDF.isSigned ) {
    myFDF.signatureSign({
        oSig: eng,
        nUI: 1,
        cUISignTitle: "Sign Embedded File FDF",
        cUISelectMsg: "Please select a Digital ID to use to "
            + "sign your embedded file FDF."
    });
    myFDF.save( "/c/temp/myData.fdf" );
};

data-id=81915

data-id=signaturevalidate

data-id=id552

signatureValidate

Validate the signature of an FDF object and return a SignatureInfo object specifying the properties of the signature.

Parameters

Returns

A SignatureInfo object. The signature status is described in status property.

Example: Open an FDF file, if signed, validate it the signature and return information to the console.

fdf = app.openFDF("/c/temp/myDoc.fdf");
eng = security.getHandler( "Adobe.PPKLite" );
if (fdf.isSigned)
{
    var oSigInfo = fdf.signatureValidate({
        oSig: eng,
        bUI: true
    });
    console.println("Signature Status: " + oSigInfo.status);
    console.println("Description: " + oSigInfo.statusText);
} else {
    console.println("FDF not signed");
}

data-id=36795

data-id=field

data-id=id553

Field

This object represents an Acrobat form field (that is, a field created using the Acrobat form tool or the Doc addField method). In the same manner that a form author can modify an existing field’s properties, such as the border color or font, the JavaScript user can use the Field object to perform the same modifications.

Before a field can be accessed, it must be bound to a JavaScript variable through a method provided by the Doc. More than one variable may be bound to a field by modifying the field’s object properties or accessing its methods. This affects all variables bound to that field.

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

This example allows the script to manipulate the form field “Total” by means of the variable f.

Fields can be arranged hierarchically within a document. For example, form fields with names like “FirstName” and “LastName” are called flat names and there is no association between them. By changing the field names, a hierarchy of fields within the document can be created.

For example, “Name.First” and “Name.Last” forms a tree of fields. The period (‘.’) separator in Acrobat forms denotes a hierarchy shift. “Name” in these fields is the parent; “First” and “Last” are the children. Also, the field “Name” is an internal field because it has no visible appearance. “First” and “Last” are terminal fields that appear on the page.

Acrobat form fields that share the same name also share the same value. Terminal fields can have different presentations of that data. For example, they can appear on different pages, be rotated differently, or have a different font or background color, but they have the same value. Therefore, if the value of one presentation of a terminal field is modified, all others with the same name are updated automatically.

Each presentation of a terminal field is referred to as a widget. An individual widget does not have a name but is identified by index (0-based) within its terminal field. The index is determined by the order in which the individual widgets of this field were created (and is unaffected by tab-order).

You can determine the index for a specific widget by using the Fields navigation tab in Acrobat. The index is the number that follows the ‘#’ sign in the field name shown. (In Acrobat 6.0 or later, the widget index is displayed only if the field has more than one widget.) You can double-click an entry in the Fields panel to go to the corresponding widget in the document. Alternatively, if you select a field in the document, the corresponding entry in the Fields panel is highlighted.

Beginning with Acrobat 6.0, getField can be used to retrieve the Field object of one individual widget of a field. This notation consists of appending a “.” (period) followed by the widget index to the field name passed. When this approach is used, the Field object returned by getField encapsulates only one individual widget. You can use the Field objects returned this way anywhere you would use a Field object returned by passing the unaltered field name. However, the set of nodes that are affected may vary, as shown in the following table.

Beginning with Acrobat 8.0, the LiveCycle Reader Extensions Field right is checked for Field objects only if the JavaScript code is executed outside the PDF file (from the JavaScript console, through batch execution, or through JSObject).

The following example changes the rect property of the second radio button (the first would have index 0) of the field “my radio”.

var f = this.getField("my radio.1");
f.rect = [360, 677, 392, 646];

data-id=54526

data-id=field-versus-widget-attributes

data-id=id554

Field versus widget attributes

Some properties of the Field object, such as value, apply to all widgets that are children of that field. Other properties, such as rect, are specific to individual widgets.

The following field properties and methods affect field-level attributes:

calcOrderIndex, charLimit, comb, currentValueIndices,defaultValue,

 doNotScroll, doNotSpellCheck, delay, doc, editable, exportValues,

 fileSelect, multiline, multipleSelection, name, numItems,page, password,

 readonly, required,submitName, type, userName, value, valueAsString,

 clearItems, browseForFileToSubmit, deleteItemAt, getItemAt, insertItemAt,

 setAction, setItems,signatureInfo, signatureSign, and signatureValidate.

The following field properties and methods affect widget-level attributes:

alignment, borderStyle, buttonAlignX, buttonAlignY, buttonPosition,

 buttonScaleHow, buttonScaleWhen, display, fillColor, hidden, highlight,

 lineWidth, print, rect, strokeColor, style, textColor, textFont, textSize,

 buttonGetCaption, buttonGetIcon, buttonImportIcon, buttonSetCaption,

 buttonSetIcon, checkThisBox, defaultIsChecked, isBoxChecked,

 isDefaultChecked, setAction, and setFocus.

Note

The setAction method can apply at the field or widget level, depending on the event. The Keystroke, Validate, Calculate, and Format events apply to fields. The MouseUp, MouseDown, MouseEnter, MouseExit, OnFocus, and OnBlur events apply to widgets.

The checkThisBox, defaultIsChecked, isBoxChecked, and isDefaultChecked methods take a widget index, nWidget, as a parameter. If you invoke these methods on a Field object f that represents one specific widget, the nWidget parameter is optional (and is ignored if passed) and the method acts on the specific widget encapsulated by f.

data-id=field-properties

data-id=id555

Field properties

In general, field properties correspond to those stored in field and annotation dictionaries in the PDF document (see the PDF Reference).

Some property values are stored in the PDF document as names, while others are stored as strings (see the PDF Reference). For a property that is stored as a name, there is a 127-character limit on the length of the string.

Examples of properties that have a 127-character limit include value and defaultValue for check boxes and radio buttons. The PDF Reference documents all Annotation properties as well as how they are stored.

data-id=47052

data-id=id559

data-id=id560

alignment

Controls how the text is laid out within the text field. Values are

left
center
right

Fields

text

Example:

var f = this.getField("MyText");
f.alignment = "center";

data-id=18616

borderStyle

The border style for a field. Valid border styles are

solid
dashed
beveled
inset
underline

The border style determines how the border for the rectangle is drawn. The border object is a static convenience constant that defines all the border styles of a field, as shown in the following table:

Fields

All

Example: The following example shows how to set the border style of a field to solid :

var f = this.getField("MyField");
f.borderStyle = border.s; /* border.s evaluates to "solid" */

data-id=40106

data-id=buttonalignx

data-id=id561

buttonAlignX

Controls how space is distributed from the left of the button face with respect to the icon. It is expressed as a percentage between 0 and 100, inclusive. The default value is 50.

If the icon is scaled anamorphically (which results in no space differences), this property is not used.

Fields

button

data-id=41863

data-id=buttonaligny

data-id=id562

buttonAlignY

Controls how unused space is distributed from the bottom of the button face with respect to the icon. It is expressed as a percentage between 0 and 100, inclusive. The default value is 50.

If the icon is scaled anamorphically (which results in no space differences), this property is not used.

Fields

button

Example: This example is an elevator animation. The field “myElevator” is a button form field that has small width and large height. An icon is imported as the appearance face.

function MoveIt()
{
    if ( f.buttonAlignY == 0 ) {
        f.buttonAlignY++;
        run.dir = true;
        return;
    }
    if ( f.buttonAlignY == 100 ) {
        f.buttonAlignY--;
        run.dir = false;
        return;
    }
    if (run.dir) f.buttonAlignY++;
    else f.buttonAlignY--;
}
var f = this.getField("myElevator");
f.buttonAlignY=0;
run = app.setInterval("MoveIt()", 100);
run.dir=true;
toprun = app.setTimeOut(
    "app.clearInterval(run); app.clearTimeOut(toprun)", 2*20000+100);

data-id=13558

data-id=buttonfitbounds

data-id=id563

buttonFitBounds

If true, the extent to which the icon may be scaled is set to the bounds of the button field. The additional icon placement properties are still used to scale and position the icon within the button face.

In previous versions of Acrobat, the width of the field border was always taken into consideration when scaling an icon to fit a button face, even when no border color was specified. Setting this property to true when a border color has been specified for the button will cause an exception to be raised.

Fields

button

data-id=23056

data-id=buttonposition

data-id=id564

buttonPosition

Controls how the text and the icon of the button are positioned with respect to each other within the button face. The convenience position object defines all of the valid alternatives.

Fields

button

data-id=36156

data-id=buttonscalehow

data-id=id565

buttonScaleHow

Controls how the icon is scaled (if necessary) to fit inside the button face. The convenience scaleHow object defines all of the valid alternatives:

Fields

button

data-id=36367

data-id=buttonscalewhen

data-id=id566

buttonScaleWhen

Controls when an icon is scaled to fit inside the button face. The convenience scaleWhen object defines all of the valid alternatives:

Fields

button

data-id=20477

data-id=calcorderindex

data-id=id567

calcOrderIndex

Changes the calculation order of fields in the document. When a computable text or combo box field is added to a document, the field’s name is appended to the calculation order array. The calculation order array determines in what order the fields are calculated. The calcOrderIndex property works similarly to the Calculate tab used by the Acrobat Form tool.

Fields

combobox, text

Example:

var a = this.getField("newItem");
var b = this.getField("oldItem");
a.calcOrderIndex = b.calcOrderIndex + 1;

In this example, the “newItem” field was added after the “oldItem” field. The script changes the calcOrderIndex property of the “newItem” field so that it is calculated before the “oldItem” field.

data-id=42060

data-id=charlimit

data-id=id568

charLimit

Limits the number of characters that a user can type into a text field.

See event. fieldFull to detect when the maximum number of characters is reached.

Fields

text

Example: Set a limit on the number of characters that can be typed into a field.

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

data-id=64322

data-id=comb

data-id=id569

comb

If set to true, the field background is drawn as series of boxes (one for each character in the value of the field) and each character of the content is drawn within those boxes. The number of boxes drawn is determined from the charLimit property.

It applies only to text fields. The setter will also raise if any of the following field properties are also set multiline, password, and fileSelect. A side-effect of setting this property is that the doNotScroll property is also set.

Fields

text

Example: Create a comb field in the upper left corner of a newly created document.

var myDoc = app.newDoc();                 // Create a blank doc
var Bbox = myDoc.getPageBox("Crop");      // Get crop box
var inch = 72;

// Add a text field at the top of the document
var f = myDoc.addField("Name.Last", "text", 0,
    [ inch, Bbox[1]-inch, 3*inch, Bbox[1]- inch - 14 ] );
// Add some attributes to this text field
f.strokeColor = color.black;
f.textColor = color.blue;
f.fillColor = ["RGB",1,0.66,0.75];

f.comb = true;                            // Declare this is a comb field
f.charLimit = 10;                         // Max number of characters

data-id=74343

data-id=commitonselchange

data-id=id570

commitOnSelChange

Controls whether a field value is committed after a selection change:

• If true, the field value is committed immediately when the selection is made.
• If false, the user can change the selection multiple times without committing the field value. The value is committed only when the field loses focus, that is, when the user clicks outside the field.

Fields

combobox, listbox

data-id=52225

data-id=currentvalueindices

data-id=id571

currentValueIndices

Reads and writes single or multiple values of a list box or combo box.

Read

Returns the options-array indices of the strings that are the value of a list box or combo box field. These indices are 0-based. If the value of the field is a single string, it returns an integer. Otherwise, it returns an array of integers sorted in ascending order. If the current value of the field is not a member of the set of offered choices (as could happen in the case of an editable combo box) it returns -1.

Write

Sets the value of a list box or combo box. It accepts a single integer or array of integers as an argument. To set a single string as the value, pass an integer that is the 0-based index of that string in the options array. Note that in the case of an editable combo box, if the desired value is not a member of the set of offered choices, you must set the value instead. Except for this case, currentValueIndices is the preferred way to set the value of a list box or combo box.

To set a multiple selection for a list box that allows it, pass an array as argument to this property, containing the indices (sorted in ascending order) of those strings in the options array. If passed an array like this: Field.value=["item1", "item3"], it also selects the items. The ability for a list box to support multiple selections can be set through multipleSelection.

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

Fields

combobox, listbox

Example (Read)

A mouse-up action of a button. The script gets the current value of a list box.

var f = this.getField("myList");
var a = f.currentValueIndices;
if (typeof a == "number")     // A single selection
    console.println("Selection: " + f.getItemAt(a, false));
else {     // Multiple selections
    console.println("Selection:");
    for (var i = 0; i < a.length; i ++)
        console.println("   " + f.getItemAt(a[i], false));
}

Example (Write)

The following code, selects the second and fourth (0-based index values, 1 and 3, respectively) in a list box.

var f = this.getField("myList");
f.currentValueIndices = [1,3];

data-id=14483

data-id=defaultstyle

data-id=id572

defaultStyle

This property defines the default style attributes for the form field. If the user clicks an empty field and begins entering text without changing properties using the property toolbar, these are the properties that will be used. This property is a single Span object without a text property. Some of the properties in the default style span mirror the properties of the Field object. Changing these properties also modifies the defaultStyle property for the field and vice versa.

The following table details the properties of the Field object that are also in the default style and any differences between their values.

Note

When a field is empty, defaultStyle is the style used for newly entered text. If a field already contains text when defaultStyle is changed, the text will not pick up any changes to defaultStyle. Newly entered text uses the attributes of the text it is inserted into (or specified with the toolbar).

When pasting rich text into a field, unspecified attributes in the pasted rich text are filled with those from defaultStyle.

Superscript and Subscript are ignored in defaultStyle.

Fields

rich text

Example: Change the default style for a text field.

var style = this.getField("Text1").defaultStyle;
style.textColor = color.red;
style.textSize = 18;

// if Courier Std is not found, use a monospace font
style.fontFamily = ["Courier Std", "monospace" ];

this.getField("Text1").defaultStyle = style;

data-id=36634

data-id=defaultvalue

data-id=id573

defaultValue

The default value of a field—that is, the value that the field is set to when the form is reset. For combo boxes and list boxes, either an export or a user value can be used to set the default. A conflict can occur, for example, when the field has an export value and a user value with the same value but these apply to different items in the list. In such cases, the export value is matched against first.

Fields

all except button, signature

Example:

var f = this.getField("Name");
f.defaultValue = "Enter your name here.";

data-id=30113

data-id=donotscroll

data-id=id574

doNotScroll

If true, the text field does not scroll and the user, therefore, is limited by the rectangular region designed for the field. Setting this property to true or false corresponds to checking or unchecking the Scroll Long Text field in the Options tab of the field.

Fields

text

data-id=73181

data-id=donotspellcheck

data-id=id575

doNotSpellCheck

If true, spell checking is not performed on this editable text field. Setting this property to true or false corresponds to unchecking or checking the Check Spelling attribute in the Options tab of the Field Properties dialog box.

Fields

combobox (editable), text

data-id=29401

data-id=id576

data-id=id577

delay

Delays the redrawing of a field’s appearance. It is generally used to buffer a series of changes to the properties of the field before requesting that the field regenerate its appearance. Setting the property to true forces the field to wait until delay is set to false. The update of its appearance then takes place, redrawing the field with its latest settings.

There is a corresponding Doc delay flag if changes are being made to many fields at once.

Fields

all

Example: Change the appearance of a check box. Set delay to true, makes changes, and sets delay to false.

// Get the myCheckBox field
var f = this.getField("myCheckBox");
// Set the delay and change the fields properties
// to beveled edge and medium thickness line.
f.delay = true;
f.borderStyle = border.b;
.
..        // A number of other changes
f.strokeWidth = 2;
f.delay = false; // Force the changes now

data-id=10117

data-id=display

data-id=id578

display

Controls whether the field is hidden or visible on screen and in print. The values for the display property are listed in the table below.