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.

alignment

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

   left

   center

   right

Type

String

Access

R/W

Fields

text 

Example

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

   f.alignment = "center";

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:

Type

String

Access

R/W

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" */

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.

Type

Integer

Access

R/W

Fields

button 

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.

Type

Integer

Access

R/W

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);

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.

Type

Boolean

Access

R/W

Fields

button 

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.

Type

Integer

Access

R/W

Fields

button 

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:

Type

Integer

Access

R/W

Fields

button 

buttonScaleWhen

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

Type

Integer

Access

R/W

Fields

button 

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.

Type

Integer

Access

R/W

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.

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.

Type

Integer

Access

R/W

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;

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.

Type

Boolean

Access

R/W

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

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.

Type

Boolean

Access

R/W

Fields

combobox, listbox 

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.

Type

Integer | Array

Access

R/W

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];

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.

Type

Span object

Access

R/W

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;

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.

Type

String

Access

R/W

Fields

all except button, signature 

Example

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

   f.defaultValue = "Enter your name here.";

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.

Type

Boolean

Access

R/W

Fields

text 

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.

Type

Boolean

Access

R/W

Fields

combobox (editable), text 

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.

Type

Boolean

Access

R/W

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

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.

This property supersedes the older hidden and print properties.

Type

Integer

Access

R/W

Fields

all

Example

   // Set the display property

   var f = getField("myField");

   f.display = display.noPrint;

   

   // Test whether field is hidden on screen and in print

   if (f.display == display.hidden) console.println("hidden");

doc

Returns the Doc of the document to which the field belongs.

Type

object

Access

R

Fields

all

editable

Controls whether a combo box is editable. If true, the user can type in a selection. If false, the user must choose one of the provided selections.

Type

Boolean

Access

R/W

Fields

combobox 

Example

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

   f.editable = true;

exportValues

An array of strings representing the export values for the field. The array has as many elements as there are annotations in the field. The elements are mapped to the annotations in the order of creation (unaffected by tab-order).

For radio button fields, this property is required to make the field work properly as a group. The button that is checked at any time gives its value to the field as a whole.

For check box fields, unless an export value is specified, “Yes” (or the corresponding localized string) is the default when the field is checked. “Off” is the default when the field is unchecked (the same as for a radio button field when none of its buttons are checked).

Type

Array

Access

R/W

Fields

checkbox, radiobutton 

Example

Create a radio button field and sets its export values.

   var d = 40;

   var f = this.addField("myRadio","radiobutton",0,  [200, 510, 210, 500]);

   this.addField("myRadio","radiobutton",0,  [200+d, 510-d, 210+d, 500-d]);

   this.addField("myRadio","radiobutton",0,  [200, 510-2*d, 210, 500-2*d]);

   this.addField("myRadio","radiobutton",0,  [200-d, 510-d, 210-d, 500-d]);

   f.strokeColor = color.black;

   // Now give each radio field an export value

   f.exportValues = ["North", "East", "South", "West"];

fileSelect

If true, sets the file-select flag in the Options tab of the text field (Field is Used for File Selection). This indicates that the value of the field represents a path of a file whose contents may be submitted with the form.

The path may be entered directly into the field by the user, or the user can browse for the file. (See the browseForFileToSubmit method.)

Note:The file select flag is mutually exclusive with the multiline, charLimit, password, and defaultValue properties. Also, on the Mac OS platform, when setting the file select flag, the field gets treated as read-only. Therefore, the user must browse for the file to enter into the field. (See browseForFileToSubmit.)

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

Type

Boolean

Access

R/W

Fields

text 

fillColor

Specifies the background color for a field. The background color is used to fill the rectangle of the field. Values are defined by using transparent, gray, RGB or CMYK color. See Color arrays for information on defining color arrays and how values are used with this property.

In older versions of this specification, this property was named bgColor. The use of bgColor is now discouraged, although it is still valid for backward compatibility.

Type

Array

Access

R/W

Fields

all

Example

Change the background color of a text field. If the current color is red, it changes to blue, otherwise it changes to yellow.

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

   if (color.equal(f.fillColor, color.red))

      f.fillColor = color.blue;

   else

      f.fillColor = color.yellow;

hidden

Note:This property has been superseded by the display property and its use is discouraged.

If the value is false, the field is visible to the user; if true, the field is invisible. The default value is false.

Type

Boolean

Access

R/W

Fields

all

highlight

Defines how a button reacts when a user clicks it. The four highlight modes supported are:

none — No visual indication that the button has been clicked.

invert — The region encompassing the button’s rectangle inverts momentarily.

push — The down face for the button (if any) is displayed momentarily.

outline — The border of the rectangleinverts momentarily.

The convenience highlight object defines each state, as follows:

Type

String

Access

R/W

Fields

button 

Example

Set the highlight property of a button to “invert”.

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

   f.highlight = highlight.i;

lineWidth

Specifies the thickness of the border when stroking the perimeter of a field’s rectangle. If the stroke color is transparent, this parameter has no effect except in the case of a beveled border. Values are:

0 — none

1 — thin

2 — medium

3 — thick

In older versions of this specification, this property was borderWidth. The use of borderWidth is now discouraged, although it is still valid for backward compatibility.

The default value for lineWidth is 1 (thin). Any integer value can be used; however, values beyond 5 may distort the field’s appearance.

Type

Integer

Access

R/W

Fields

all

Example

Change the border width of the Text Box to medium thickness

   f.lineWidth = 2

multiline

Controls how text is wrapped within the field. If false (the default), the text field can be a single line only. If true, multiple lines are allowed and they wrap to field boundaries.

Type

Boolean

Access

R/W

Fields

text 

Example

See Example 1 following the Doc getField method.

multipleSelection

If true, indicates that a list box allows a multiple selection of items.

See also type, value, and currentValueIndices.

Type

Boolean

Access

R/W

Fields

listbox 

name

This property returns the fully qualified field name of the field as a string object.

Beginning with Acrobat 6.0, if the Field object represents one individual widget, the returned name includes an appended '.' followed by the widget index.

Type

String

Access

R

Fields

all

Example

Get a Field object and write the name of the field to the console.

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

   

   // Displays "myField" in the console window

   console.println(f.name);

numItems

The number of items in a combo box or list box.

Type

Integer

Access

R

Fields

combobox, listbox 

Example

Get the number of items in a list box.

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

   console.println("There are " + f.numItems + " in this list box");

Face names and values of a combo box or list box can be accessed through the getItemAt method. See that method for an additional example of numItems.

page

The page number or an array of page numbers of a field. If the field has only one appearance in the document, the page property returns an integer representing the 0-based page number of the page on which the field appears. If the field has multiple appearances, it returns an array of integers, each member of which is a 0-based page number of an appearance of the field. The order in which the page numbers appear in the array is determined by the order in which the individual widgets of this field were created (and is unaffected by tab-order). If an appearance of the field is on a hidden template page, page returns a value of -1 for that appearance.

Type

Integer | Array

Access

R

Fields

all

Example 1

Determine whether a particular field appears on one page, or more than one page.

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

   if (typeof f.page == "number")

      console.println("This field only occurs once on page " + f.page);

   else

      console.println("This field occurs " + f.page.length + " times);

Example 2 (Acrobat 6.0)

The page property can be used to get the number of widgets associated with a field name. This example gets the number of radio buttons in a radio button field.

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

   if ( typeof f.page == "object" )

      console.println("There are " + f.page.length

         + " radios in this field.");

password

Specifies whether the field should display asterisks when data is entered in the field. (Upon submission, the actual data entered is sent.) If this property is true, data in the field is not saved when the document is saved to disk.

Type

Boolean

Access

R/W

Fields

text 

print

Note:This property has been superseded by the display property and its use is discouraged.

If true, the field appears when the user prints the document. If false, the field does not appear when printing. This property can be used to hide control buttons and other fields that are not useful on the printed page.

Type

Boolean

Access

R/W

Fields

all

radiosInUnison

If false, even if a group of radio buttons have the same name and export value, they behave in a mutually exclusive fashion, like HTML radio buttons. The default for new radio buttons is false.

If true, if a group of radio buttons have the same name and export value, they turn on and off in unison, as in Acrobat 4.0.

Type

Boolean

Access

R/W

Fields

radiobutton 

readonly

The read-only characteristic of a field. If a field is read-only, the user can see the field but cannot change it.

Type

Boolean

Access

R/W

Fields

all

Example

Get a field and make it read-only.

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

   f.value = "You can’t change this message!";

   f.readonly = true;

rect

An array of four numbers in rotated user space that specify the size and placement of the form field. These four numbers are the coordinates of the bounding rectangle and are listed in the following order: upper-left x, upper-left y, lower-right x and lower-right y.

Note:The Annotation object also has a rect property. However, the coordinates are not in rotated user space and they are in a different order than in the Field object rect property.

Type

Array

Access

R/W

Fields

all

Example 1

Lay out a 2-inch-wide text field just to the right of the field “myText”.

   var f = this.getField("myText");  // Get the Field object

   var myRect = f.rect;              // and get its rectangle

   myRect[0] = f.rect[2];            // The ulx for new = lrx for old

   myRect[2] += 2 * 72;               // Move two inches for lry

   f = this.addField("myNextText", "text", this.pageNum, myRect);

   f.strokeColor = color.black;

Example 2

Move an existing button field 10 points to the right.

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

   var aRect = b.rect;   // Make a copy of b.rect

   aRect[0] += 10;       // Increment first x coordinate by 10

   aRect[2] += 10;       // Increment second x coordinate by 10

   b.rect = aRect;       // Update the value of b.rect

required

Specifies whether a field requires a value. If true, the field’s value must be non-null when the user clicks a submit button that causes the value of the field to be posted. If the field value is null, the user receives a warning message and the submit does not occur.

Type

Boolean

Access

R/W

Fields

all except button 

Example

Make “myField” into a required field.

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

   f.required = true;

richText

If true, the field allows rich text formatting. The default is false.

Type

Boolean

Access

R/W

Fields

text 

Related objects and properties are richValue, defaultStyle, event.richValue, event.richChange, event.richChangeEx, the Annotation object richContents property, and the Span object.

Example 1

Get a Field object and set it for rich text formatting.

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

   f.richText = true;

See Example 2 following richValue for a more complete example.

Example 2

Count the number of rich text fields in the document.

   var count = 0;

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

   {

      var fname = this.getNthFieldName(i);

      var f = this.getField(fname);

      if ( f.type == "text" && f.richText ) count++

   }

   console.println("There are a total of "+ count + " rich text fields.");

richValue

This property specifies the text contents and formatting of a rich text field. For field types other than rich text, this property is undefined. The rich text contents are represented as an array of Span objects containing the text contents and formatting of the field.

Type

Array of Span objects

Access

R/W

Fields

rich text

Related objects and properties are richText, defaultStyle, event.richValue, event.richChange, event.richChangeEx, the Annotation object richContents property, and the Span object.

Example 1

Turn all bold text into red underlined text.

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

   var spans = f.richValue;

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

   {

      if( spans[i].fontWeight >= 700 )

      {

         spans[i].textColor = color.red;

         spans[i].underline = true;

      }

   }

   f.richValue = spans;

Example 2

Create a text field, marks it for rich text formatting, and inserts rich text.

   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("Text1", "text", 0,

      [72, Bbox[1]-inch, Bbox[2]-inch, Bbox[1]-2*inch ] );

   // Add some attributes to this text field

   f.strokeColor = color.black;

   f.richText = true;                         // Rich text

   f.multiline = true;                        // Multiline

   

   // Now build up an array of Span objects

   var spans = new Array();

   spans[0] = new Object();

   spans[0].text = "Attention:\r";

   spans[0].textColor = color.blue;

   spans[0].textSize = 18;

   

   spans[1] = new Object();

   spans[1].text = "Adobe Acrobat 6.0\r";

   spans[1].textColor = color.red;

   spans[1].textSize = 20;

   spans[1].alignment = "center";

   

   spans[2] = new Object();

   spans[2].text = "will soon be here!";

   spans[2].textColor = color.green;

   spans[2].fontStyle = "italic";

   spans[2].underline = true;

   spans[2].alignment = "right";

   

   // Now give the rich field a rich value

   f.richValue = spans;

rotation

The rotation of a widget in counterclockwise increments. Valid values are 0, 90, 180, and 270.

Type

Integer

Access

R/W

Fields

all

Example

Create a rotated text field on each page and fill it with text.

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

      var f = this.addField("myRotatedText"+i,"text",i,[6, 6+72, 18, 6]);

      f.rotation = 90; f.value = "Confidential";

      f.textColor = color.red; f.readonly = true;

   }

strokeColor

Specifies the stroke color for a field that is used to stroke the rectangle of the field with a line as large as the line width. Values are defined by using transparent, gray, RGB or CMYK color. See Color arrays for information on defining color arrays and how values are used with this property.

In older versions of this specification, this property was borderColor. The use of borderColor is now discouraged, although it is still valid for backward compatibility.

Type

Array

Access

R/W

Fields

all

Example

Change the stroke color of each text field in the document to red.

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

      var fname = this.getNthFieldName(i);

      var f = this.getField(fname);

      if ( f.type == "text" ) f.strokeColor = color.red;

}

style

Allows the user to set the glyph style of a check box or radio button. The glyph style is the graphic used to indicate that the item has been selected.

The style values are associated with keywords as follows.

Type

String

Access

R/W

Fields

checkbox, radiobutton 

Example

This example sets the glyph style to circle.

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

   f.style = style.ci;

submitName

If nonempty, used during form submission instead of name. Only applicable if submitting in HTML format (that is, URL-encoded).

Type

String

Access

R/W

Fields

all

textColor

The foreground color of a field. It represents the text color for text, button, or list box fields and the check color for check box or radio button fields. Values are defined the same as the fillColor. See Color arrays for information on defining color arrays and how values are set and used with this property.

In older versions of this specification, this property was fgColor. The use of fgColor is now discouraged, although it is still valid for backward compatibility.

Note:An exception is thrown if a transparent color space is used to set textColor.

Type

Array

Access

R/W

Fields

all

Example

This example sets the foreground color to red.

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

   f.textColor = color.red;

textFont

The font that is used when laying out text in a text field, combo box, list box or button. Valid fonts are defined as properties of the font object. Beginning with Acrobat 5.0, arbitrary fonts can also be used. See “Use of arbitrary fonts”.

Type

String

Access

R/W

Fields

button, combobox, listbox, text 

font Object

Use of arbitrary fonts

Beginning with Acrobat 5.0, an arbitrary font can be used when laying out a text field, combo box, list box or button by setting the value of textFont to the PDSysFont font name, as returned by PDSysFontGetName. (See the Acrobat and PDF Library API Reference.)

To find the PDSysFont font name of a font:

1.Create a text field in a PDF document. Using the UI, set the text font for this field to the desired font.

2.Open the JavaScript Debugger Console and execute the script

      this.getField("Text1").textFont

The above code assumes the name of the field is Text1.

3.The string returned to the console is the font name needed to programmatically set the text font.

Example

Set the font to Helvetica.

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

   f.textFont = font.Helv;

Example (Acrobat 5.0)

Set the font of myField to Viva-Regular.

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

   f.textFont = "Viva-Regular";

textSize

Specifies the text size (in points) to be used in all controls. In check box and radio button fields, the text size determines the size of the check. Valid text sizes range from 0 to 32767, inclusive. A value of zero means the largest point size that allows all text data to fit in the field’s rectangle.

Type

Number

Access

R/W

Fields

all

Example

Set the text size of “myField” to 28 points.

   this.getField("myField").textSize = 28;

type

Returns the type of the field as a string. Valid types are:

   button

   checkbox

   combobox

   listbox

   radiobutton

   signature

   text

Type

String

Access

R

Fields

all

Example

Count the number of text fields in the document.

   var count = 0;

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

      var fname = this.getNthFieldName(i);

      if ( this.getField(fname).type == "text" ) count++; }

   console.println("There are " + count + " text fields.");

userName

The user name (short description string) of the field. It is intended to be used as tooltip text whenever the cursor enters a field. It can also be used as a user-friendly name, instead of the field name, when generating error messages.

Type

String

Access

R/W

Fields

all

Example

Add a tooltip to a button field.

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

   f.userName = "Press this button to submit your data.";

value

The value of the field data that the user has entered. Depending on the type of the field, may be a String, Date, or Number. Typically, the value is used to create calculated fields.

Beginning with Acrobat 6.0, if a field contains rich text formatting, modifying this property will discard the formatting and regenerate the field value and appearance using the defaultStyle and plain text value. To modify the field value and maintain formatting use the richValue property.

Note:For signature fields, if the field has been signed, a non-null string is returned as the value.

For Acrobat 5.0 or later, if the field is a list box that accepts multiple selections (see multipleSelection), you can pass an array to set the value of the field, and value returns an array for a list box with multiple values currently selected.

The currentValueIndices of a list box that has multiple selections is the preferred and most efficient way to get and set the value of this type of field.

See also valueAsString and event.type.

Type

various

Access

R/W

Fields

all except button 

Example

In this example, the value of the field being calculated is set to the sum of the “Oil” and “Filter” fields and multiplied by the state sales tax.

   var oil = this.getField("Oil");

   var filter = this.getField("Filter");

   event.value = (oil.value + filter.value) * 1.0825;

valueAsString

Returns the value of a field as a JavaScript string.

It differs from value, which attempts to convert the contents of a field contents to an accepted format. For example, for a field with a value of “020”, value returns the integer 20, while valueAsString returns the string “020”.

Type

String

Access

R

Fields

all except button