Events

Text field entry

1. Focus: User clicks into field

2. Keystroke: Each character typed (willCommit = false)

3. Keystroke: Final value (willCommit = true)

4. Validate: Checks if value is acceptable

5. Format: Formats for display

6. Blur: User leaves field

7. Calculate: Other fields recalculate

Dropdown and list selection

For dropdowns and listboxes, the Keystroke event serves as the selection change event:

// Dropdown/List Keystroke event - fires when selection changes
if (event.willCommit) {
    console.println("Selected: " + event.value)
    console.println("Export value: " + event.changeEx)
    
    // React to selection
    if (event.value == "Other") {
        this.getField("OtherText").display = display.visible
    }
}

This is different from text fields—there's no character-by-character keystroke, just the selection change.

Button click

1. Mouse Enter: Cursor enters

2. Mouse Down: Mouse pressed

3. Mouse Up: Mouse released (primary action event)

4. Mouse Exit: Cursor leaves

Control properties

event.rc = false     // Cancel the event
event.rc = true      // Allow the event (default)

Value properties

event.value          // The field value
event.change         // Character being typed (text) or selection (dropdown)
event.changeEx       // Export value for dropdown/list selections
event.willCommit     // Whether action is final

Context properties

event.target         // Object receiving event
event.source         // Object triggering event
event.targetName     // Name of target field

Validation

// Validate event - check range
if (event.value < 0 || event.value > 100) {
    app.alert("Value must be 0-100")
    event.rc = false
}

Formatting

// Format event - currency
if (event.value != "") {
    event.value = "$" + parseFloat(event.value).toFixed(2)
}

Calculation

// Calculate event - sum fields
var total = 0
for (var i = 1; i <= 3; i++) {
    total += this.getField("Item" + i).value || 0
}
event.value = total

Keystroke control

// Keystroke event - different behavior for text vs dropdown
if (event.willCommit) {
    // Final value being committed
    console.println("Final: " + event.value)
} else {
    // Text field only - character input
    event.change = event.change.toUpperCase()
}

Required fields

// WillSave event
if (!this.getField("Required").value) {
    app.alert("Complete required fields")
    event.rc = false
}

Conditional visibility

// Dropdown keystroke event
if (event.willCommit && event.value == "Other") {
    this.getField("Details").display = display.visible
} else {
    this.getField("Details").display = display.hidden
}

Input masking

// Phone number keystroke
if (!event.willCommit) {
    // Only allow digits while typing
    if (!/^\d*$/.test(event.change)) {
        event.rc = false
    }
}

Stamps have a unique event structure. The stamp's JavaScript accesses the document through a double-source pattern:

// In stamp JavaScript
var stamp = event.source              // The stamp
var doc = event.source.source         // The document

// Interact with the document
doc.getField("StampDate").value = new Date()
var pageCount = doc.numPages

This event.source.source pattern is essential for stamps that modify the underlying document. See Interactive stamps for complete stamp examples.

Calculation order

Fields calculate in the order set in Forms > Edit Form Fields > Set Field Calculation Order. This matters when fields depend on each other:

copy

// Field A calculates first
event.value = this.getField("Quantity").value * 10

// Field B calculates second, can use Field A's result
event.value = this.getField("FieldA").value * 1.08