Events

Understanding Events

Events are the heartbeat of interactive PDFs. Every time a user clicks a button, types in a field, or interacts with your document, an event fires. JavaScript code attached to these events brings your PDFs to life.

The event object appears automatically when an event fires - you don't create it or access it through this. It's simply there in your event handler code, containing information about what triggered the event.

Event Flow

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

Key Event Properties

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

Common Event Handlers

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()
}

Special Patterns

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 and Events

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. Chapter 6 explores 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:

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

Quick Reference

Event Types:

• Fields: Focus, Blur, Keystroke (typing or selection), Validate, Format, Calculate
• Document: Open, WillSave, DidSave, WillPrint, DidPrint
• Mouse: Up, Down, Enter, Exit
• Page: Open, Close

Key Patterns:

• Cancel event: event.rc = false
• Dropdown change: Keystroke with willCommit = true
• Character input: Keystroke with willCommit = false
• Stamp document access: event.source.source

Moving Forward

Events transform static PDFs into dynamic documents. By understanding event flow and choosing the right event for each task, you can create sophisticated forms that respond intelligently to user actions. The detailed property reference in event.md provides complete documentation for all event properties.