Field

Field object represents a form field in a PDF document. It provides access to form field properties and methods for manipulating field appearance and behavior. Field objects are typically accessed through Doc.getField or other field-related methods.

properties

alignment

The text alignment for text fields. Only applicable to text fields.

Valid values:

• "left"
• "center"
• "right"

example:

var field = this.getField("myTextField")
field.alignment = "center"

borderStyle

The border style of the field.

Valid values:

• "solid"
• "beveled"
• "dashed"
• "inset"
• "underline"

example:

var field = this.getField("myField")
field.borderStyle = "beveled"

buttonAlignX

The horizontal alignment of the icon on a button field. Value is a percentage from 0 to 100. Only applicable to pushbutton fields.

0 represents left alignment, 50 represents center, and 100 represents right alignment.

example:

var button = this.getField("myButton")
button.buttonAlignX = 50 // Center the icon horizontally

buttonAlignY

The vertical alignment of the icon on a button field. Value is a percentage from 0 to 100. Only applicable to pushbutton fields.

0 represents bottom alignment, 50 represents center, and 100 represents top alignment.

example:

var button = this.getField("myButton")
button.buttonAlignY = 50 // Center the icon vertically

buttonFitBounds

When true, the button icon ignores the border width when sizing. Only applicable to pushbutton fields. Cannot be set to true if the field has a visible border.

example:

var button = this.getField("myButton")
button.buttonFitBounds = true

buttonPosition

Controls the layout mode for the button caption and icon. Only applicable to pushbutton fields.

Valid values:

• 0 - Caption only
• 1 - Icon only
• 2 - Caption below icon
• 3 - Caption above icon
• 4 - Caption to the right of icon
• 5 - Caption to the left of icon
• 6 - Caption overlaid on icon

example:

var button = this.getField("myButton")
button.buttonPosition = 2 // Caption below icon

buttonScaleHow

Controls how the button icon is scaled. Only applicable to pushbutton fields.

Valid values:

• 0 - Always scale
• 1 - Scale when icon is bigger than bounds
• 2 - Scale when icon is smaller than bounds
• 3 - Never scale

example:

var button = this.getField("myButton")
button.buttonScaleHow = 0 // Always scale

buttonScaleWhen

Controls when the button icon scales. Only applicable to pushbutton fields.

Valid values:

• 0 - Always
• 1 - Never
• 2 - When icon is too big
• 3 - When icon is too small

example:

var button = this.getField("myButton")
button.buttonScaleWhen = 0 // Always

calcOrderIndex

The calculation order index for this field. Fields with lower indices are calculated first. When setting, if the index is greater than the number of fields with calculations it will be set to the last position.

example:

var field = this.getField("totalField")
field.calcOrderIndex = 0 // Calculate this field first

charLimit

The maximum number of characters allowed in a text field. A value of 0 means no limit. Only applicable to text fields.

example:

var field = this.getField("zipCode")
field.charLimit = 5

comb

When true, the text field is divided into equally spaced character positions. Only applicable to text fields. Cannot be true if multiline, password, or fileSelect is true.

example:

var field = this.getField("serialNumber")
field.comb = true
field.charLimit = 10 // Divide into 10 character boxes

commitOnSelChange

When true, the field value is committed immediately when the selection changes. Only applicable to list box and combo box fields.

example:

var combo = this.getField("myComboBox")
combo.commitOnSelChange = true

currentValueIndices

The index or indices of the currently selected items in a choice field. For single-selection fields, this is a number. For multiple-selection list boxes, this is an array of numbers. Returns -1 if nothing is selected.

example:

var list = this.getField("myListBox")
list.currentValueIndices = 2 // Select the third item

// For multiple selection
list.currentValueIndices = [0, 2, 4] // Select items 1, 3, and 5

defaultStyle

The default style for rich text fields. Only applicable to rich text fields. Returns a Span object containing style information.

example:

var field = this.getField("richTextField")
var style = field.defaultStyle
console.println(style.fontFamily)

defaultValue

The default value of the field. This is the value the field reverts to when reset.

example:

var field = this.getField("myField")
field.defaultValue = "Enter text here"

delay

Exists for compatibility reasons. Always returns false. Setting has no effect.

display

Controls the visibility and printing behavior of the field.

Valid values:

• 0 - Visible
• 1 - Hidden
• 2 - Visible but doesn't print
• 3 - Hidden but prints

example:

var field = this.getField("myField")
field.display = 2 // Visible on screen but won't print

doc

The Doc object that contains this field.

example:

var field = this.getField("myField")
var doc = field.doc
console.println(doc.numPages)

doNotScroll

When true, the text field does not scroll to accommodate more text than fits in the field bounds. Only applicable to text fields.

example:

var field = this.getField("myTextField")
field.doNotScroll = true

doNotSpellCheck

When true, spell checking is disabled for the text field. Only applicable to text fields.

example:

var field = this.getField("myTextField")
field.doNotSpellCheck = true

editable

When true, the combo box allows custom text entry. Only applicable to combo box fields.

example:

var combo = this.getField("myComboBox")
combo.editable = true

exportValues

Array of export values for the widgets of a checkbox or radio button field. Only applicable to checkbox and radio button fields.

example:

var check = this.getField("myCheckBox")
check.exportValues = ["Yes", "No"]

fileSelect

When true, the text field is used for file selection. Only applicable to text fields. Requires elevated privileges to set.

example:

var field = this.getField("filePathField")
field.fileSelect = true

fillColor

The background color of the field. Value is a color array in the same format as the color object.

example:

var field = this.getField("myField")
field.fillColor = color.yellow

hidden

When true, the field is hidden. Equivalent to setting display to 1.

example:

var field = this.getField("myField")
field.hidden = true

highlight

The highlighting mode for pushbutton fields. Only applicable to pushbutton fields.

Valid values:

• "none"
• "invert"
• "push"
• "outline"

example:

var button = this.getField("myButton")
button.highlight = "push"

lineWidth

The border width of the field in points.

example:

var field = this.getField("myField")
field.lineWidth = 2

multiline

When true, the text field can contain multiple lines of text. Only applicable to text fields.

example:

var field = this.getField("commentsField")
field.multiline = true

multipleSelection

When true, multiple items can be selected in a list box. Only applicable to list box fields.

example:

var list = this.getField("myListBox")
list.multipleSelection = true

name

The fully qualified name of the field.

example:

var field = this.getField("parent.child")
console.println(field.name) // "parent.child"

numItems

The number of items in a choice field (list box or combo box). Only applicable to choice fields.

example:

var list = this.getField("myListBox")
console.println("List has " + list.numItems + " items")

page

The 0-based page number(s) where the field appears. Returns a single number if the field appears on one page, or an array of numbers if it appears on multiple pages.

example:

var field = this.getField("myField")
console.println("Field is on page " + field.page)

password

When true, the text field displays asterisks or bullets instead of the actual characters. Only applicable to text fields.

example:

var field = this.getField("passwordField")
field.password = true

print

When true, the field will print when the document is printed.

example:

var field = this.getField("myField")
field.print = false // Don't print this field

radiosInUnison

When true, radio buttons with the same export value in a radio button group will toggle in unison. Only applicable to radio button fields.

example:

var radio = this.getField("myRadioGroup")
radio.radiosInUnison = true

readonly

When true, the field cannot be changed by the user.

example:

var field = this.getField("calculatedField")
field.readonly = true

rect

The rectangle that defines the field's position and size on the page. Array is in the form [left, top, right, bottom] in points.

example:

var field = this.getField("myField")
field.rect = [100, 100, 200, 120] // Position at (100, 100) with width 100 and height 20

required

When true, the field must have a value when the form is submitted.

example:

var field = this.getField("emailField")
field.required = true

richText

When true, the text field supports rich text formatting. Only applicable to text fields.

example:

var field = this.getField("myTextField")
field.richText = true

richValue

The rich text value of the field as an array of Span objects. Only applicable to rich text fields.

example:

var field = this.getField("richTextField")
var spans = field.richValue
// spans is an array of Span objects with formatting

rotation

The rotation of the field in degrees. Valid values are 0, 90, 180, or 270.

example:

var field = this.getField("myField")
field.rotation = 90 // Rotate 90 degrees clockwise

strokeColor

The border color of the field. Value is a color array in the same format as the color object.

example:

var field = this.getField("myField")
field.strokeColor = color.red

style

The style of checkmark for checkbox and radio button fields. Only applicable to checkbox and radio button fields.

Valid values:

• "check"
• "cross"
• "diamond"
• "circle"
• "star"
• "square"

example:

var check = this.getField("myCheckBox")
check.style = "diamond"

submitName

The name used when submitting the field data. If not set, the field name is used.

example:

var field = this.getField("myField")
field.submitName = "custom_field_name"

textColor

The text color of the field. Value is a color array in the same format as the color object.

example:

var field = this.getField("myField")
field.textColor = color.blue

textFont

The font used for text in the field. Valid values are the standard 14 PDF fonts.

Valid values:

• "Times-Roman"
• "Times-Bold"
• "Times-Italic"
• "Times-BoldItalic"
• "Helvetica"
• "Helvetica-Bold"
• "Helvetica-Oblique"
• "Helvetica-BoldOblique"
• "Courier"
• "Courier-Bold"
• "Courier-Oblique"
• "Courier-BoldOblique"
• "Symbol"
• "ZapfDingbats"

example:

var field = this.getField("myField")
field.textFont = "Helvetica-Bold"

textSize

The text size in points. A value of 0 means auto-size.

example:

var field = this.getField("myField")
field.textSize = 12

type

The type of the field.

Possible values:

• "button"
• "checkbox"
• "radiobutton"
• "combobox"
• "listbox"
• "text"
• "signature"

example:

var field = this.getField("myField")
if (field.type == "text") {
    field.multiline = true
}

userName

The user-friendly name of the field, used for tooltips and error messages.

example:

var field = this.getField("email")
field.userName = "Email Address"

value

The value of the field. The type depends on the field type:

• Text fields: string or number
• Checkboxes/Radio buttons: string export value
• List boxes (single selection): string
• List boxes (multiple selection): array of strings
• Combo boxes: string

example:

var textField = this.getField("myTextField")
textField.value = "Hello World"

var checkBox = this.getField("myCheckBox")
checkBox.value = "Yes"

var listBox = this.getField("myListBox")
listBox.value = ["Option1", "Option2"] // For multiple selection

valueAsString

The value of the field as a string, regardless of the actual value type.

example:

var field = this.getField("numberField")
field.value = 123.45
console.println(field.valueAsString) // "123.45"

methods

browseForFileToSubmit

Opens a file browser dialog for selecting a file path. Only works with text fields that have fileSelect set to true.

browseForFileToSubmit()

example:

var field = this.getField("fileField")
field.fileSelect = true
field.browseForFileToSubmit() // Opens file browser

buttonGetCaption

Returns the caption text for a button field.

buttonGetCaption(nFace)

nFace: [optional] The button face to get the caption from:

• 0 - Normal (default)
• 1 - Down
• 2 - Rollover

Returns the caption string.

example:

var button = this.getField("myButton")
var caption = button.buttonGetCaption(0)
console.println("Button caption: " + caption)

buttonGetIcon

Returns the icon for a button field.

buttonGetIcon(nFace)

nFace: [optional] The button face to get the icon from:

• 0 - Normal (default)
• 1 - Down
• 2 - Rollover

Returns an Icon object or null if no icon is set.

example:

var button = this.getField("myButton")
var icon = button.buttonGetIcon(0)
if (icon != null) {
    // Use the icon elsewhere
    var otherButton = this.getField("otherButton")
    otherButton.buttonSetIcon(icon)
}

buttonImportIcon

Imports an image file as the button icon. Requires elevated privileges if a path is specified.

buttonImportIcon(cPath, nPage)

cPath: [optional] The device-independent path to the image file. If not specified, a file dialog is shown.

nPage: [optional] If importing from a PDF, the 0-based page number. Default is 0.

Returns:

• 0 - Success
• 1 - User cancelled
• -1 - Could not open file
• -2 - Invalid page number

example:

var button = this.getField("myButton")
var result = button.buttonImportIcon() // Show file dialog
if (result == 0) {
    console.println("Icon imported successfully")
}

// With privileges
var result = button.buttonImportIcon("/c/images/icon.png")

buttonSetCaption

Sets the caption text for a button field.

buttonSetCaption(cCaption, nFace)

cCaption: The caption text to set

nFace: [optional] The button face to set the caption for:

• 0 - Normal (default)
• 1 - Down
• 2 - Rollover

example:

var button = this.getField("myButton")
button.buttonSetCaption("Click Me!")
button.buttonSetCaption("Pressed", 1) // Down state

buttonSetIcon

Sets the icon for a button field.

buttonSetIcon(oIcon, nFace)

oIcon: An Icon object to set as the button icon

nFace: [optional] The button face to set the icon for:

• 0 - Normal (default)
• 1 - Down
• 2 - Rollover

example:

var button1 = this.getField("button1")
var icon = button1.buttonGetIcon()

var button2 = this.getField("button2")
button2.buttonSetIcon(icon) // Copy icon to another button

checkThisBox

Checks or unchecks a specific widget in a checkbox or radio button field. Only applicable to checkbox and radio button fields.

checkThisBox(nWidget, bCheckIt)

nWidget: The 0-based index of the widget to check

bCheckIt: [optional] When true, checks the box. When false, unchecks it. Default is true. For radio buttons, cannot be false.

example:

var check = this.getField("myCheckBox")
check.checkThisBox(0, true) // Check the first widget

var radio = this.getField("myRadioGroup")
radio.checkThisBox(2, true) // Select the third radio button

clearItems

Removes all items from a choice field (combo box or list box).

clearItems()

example:

var list = this.getField("myListBox")
list.clearItems() // Remove all items

defaultIsChecked

Sets whether a checkbox or radio button widget is checked by default. Only applicable to checkbox and radio button fields.

defaultIsChecked(nWidget, bIsDefaultChecked)

nWidget: The 0-based index of the widget

bIsDefaultChecked: [optional] When true, the widget is checked by default. Default is true.

example:

var check = this.getField("myCheckBox")
check.defaultIsChecked(0, true) // First widget checked by default

deleteItemAt

Deletes an item from a choice field at the specified index.

deleteItemAt(nIdx)

nIdx: [optional] The 0-based index of the item to delete. If -1 or not specified, deletes the currently selected item.

example:

var list = this.getField("myListBox")
list.deleteItemAt(2) // Delete the third item
list.deleteItemAt() // Delete the currently selected item

getArray

Returns an array of Field objects for all terminal children of this field. Terminal children are the leaf nodes in the field hierarchy.

getArray()

Returns an array of Field objects.

example:

var parentField = this.getField("parent")
var children = parentField.getArray()
for (var i = 0; i < children.length; i++) {
    console.println(children[i].name)
}

getItemAt

Returns the item at the specified index in a choice field.

getItemAt(nIdx, bExportValue)

nIdx: The 0-based index of the item

bExportValue: [optional] When true, returns the export value. When false, returns the display value. Default is true.

Returns the item string.

example:

var list = this.getField("myListBox")
var exportVal = list.getItemAt(0, true) // Get export value
var displayVal = list.getItemAt(0, false) // Get display value

getLock

Returns the lock settings for a signature field. Only applicable to signature fields.

getLock()

Returns a Lock object with properties:

• action - The lock action ("All", "Include", or "Exclude")
• fields - Array of field names to lock

Returns null if no lock is set.

example:

var sig = this.getField("signatureField")
var lock = sig.getLock()
if (lock != null) {
    console.println("Lock action: " + lock.action)
}

insertItemAt

Inserts an item into a choice field at the specified position.

insertItemAt(cName, cExport, nIdx)

cName: The display name for the item

cExport: [optional] The export value for the item. If not specified, uses cName.

nIdx: [optional] The 0-based index where to insert. Default is 0. If negative, appends to the end.

example:

var list = this.getField("myListBox")
list.insertItemAt("New Item", "new_value", 0) // Insert at beginning
list.insertItemAt("Another Item") // Insert at beginning with same export value

isBoxChecked

Returns whether a specific widget in a checkbox or radio button field is checked.

isBoxChecked(nWidget)

nWidget: The 0-based index of the widget to check

Returns true if checked, false otherwise.

example:

var check = this.getField("myCheckBox")
if (check.isBoxChecked(0)) {
    console.println("First checkbox is checked")
}

isDefaultChecked

Returns whether a specific widget in a checkbox or radio button field is checked by default.

isDefaultChecked(nWidget)

nWidget: The 0-based index of the widget to check

Returns true if checked by default, false otherwise.

example:

var check = this.getField("myCheckBox")
if (check.isDefaultChecked(0)) {
    console.println("First checkbox is checked by default")
}

setAction

Sets a JavaScript action for a field trigger.

setAction(cTrigger, cScript)

cTrigger: The trigger name. Valid values:

• "MouseUp"
• "MouseDown"
• "MouseEnter"
• "MouseExit"
• "OnFocus"
• "OnBlur"
• "Keystroke"
• "Validate"
• "Calculate"
• "Format"

cScript: The JavaScript code to execute

example:

var field = this.getField("myField")
field.setAction("MouseUp", "app.alert('Field clicked!')")
field.setAction("Validate", "event.rc = event.value.length > 0")

setFocus

Sets the keyboard focus to this field.

setFocus()

example:

var field = this.getField("myField")
field.setFocus() // Move cursor to this field

setItems

Sets all items in a choice field, replacing any existing items.

setItems(oArray)

oArray: An array where each element is either:

• A string (both display and export value will be the same)
• A two-element array [display, export]

example:

var list = this.getField("myListBox")
// Simple items
list.setItems(["Option 1", "Option 2", "Option 3"])

// Items with different export values
list.setItems([
    ["Display 1", "value1"],
    ["Display 2", "value2"],
    ["Display 3", "value3"]
])

setLock

Sets the lock settings for a signature field. Only applicable to signature fields. Requires elevated privileges.

setLock(oLock)

oLock: A Lock object with properties:

• action - "All", "Include", or "Exclude"
• fields - Array of field names to lock (required for Include/Exclude)

Returns true if successful.

example:

var sig = this.getField("signatureField")
var lock = {
    action: "Include",
    fields: ["field1", "field2", "field3"]
}
sig.setLock(lock)