Field

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

fileColor

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"

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