event

The event object provides access to information about the current JavaScript event being processed. Unlike other JavaScript objects in Revu, the event object is not directly accessible through this or other means. Instead, it is automatically available in the scope of event handler scripts when they are executed.

Events in Revu are triggered by various user interactions and document actions. When an event occurs, the associated JavaScript code is executed with an event object that contains contextual information about what triggered the event. The properties available on the event object vary depending on the type of event being processed.

The event object is read-only for most properties, but certain properties like change, rc, selEnd, selStart, and value can be modified to affect the outcome of the event. For example, setting event.rc = false in a validation script will prevent the action from completing.

Event Types

Revu supports various event types that can trigger JavaScript execution:

• App Events: Application initialization
• Doc Events: Document open, close, print, and save operations
• Field Events: Form field interactions including focus, blur, calculate, format, keystroke, validate, and mouse events
• Page Events: Page open and close
• Bookmark Events: Bookmark mouse interactions
• Console Events: Console command execution

example:

// In a field validation script
if (event.value < 0) {
    app.alert("Value must be positive");
    event.rc = false; // Prevent the negative value from being accepted
}

properties

change

The text being entered or pasted into a field during a keystroke event. This property is only present for Field_Keystroke events when text is being modified.

When processing keystroke events, you can modify this property to change what text will be inserted. Setting event.change = "" will prevent the character from being entered.

example:

// In a field keystroke script - convert to uppercase
event.change = event.change.toUpperCase();

// Prevent non-numeric characters
if (!/^\d*$/.test(event.change)) {
    event.change = "";
}

changeEx

Contains the export value of the item that was selected in a combobox or listbox during a keystroke event. This is particularly useful when the display value and export value of list items differ.

For regular text input, this property contains the same value as change.

example:

// In a combobox keystroke script
console.println("Display value: " + event.change);
console.println("Export value: " + event.changeEx);

commitKey

Indicates how the user committed the field value during a keystroke event when willCommit is true. This helps determine what action caused the field to lose focus.

Valid values:

• 0: Value was not committed (willCommit is false)
• 1: User pressed Enter key
• 2: User pressed Tab key to move to next field
• 3: User clicked outside the field or otherwise caused it to lose focus

example:

// In a field keystroke script
if (event.willCommit) {
    switch(event.commitKey) {
        case 1:
            console.println("User pressed Enter");
            break;
        case 2:
            console.println("User pressed Tab");
            break;
        case 3:
            console.println("Field lost focus");
            break;
    }
}

fieldFull

Indicates whether the field is full during a keystroke event. This is true when the user attempts to enter more characters than the field's character limit allows.

This property is useful for providing feedback when users reach the maximum character limit of a field.

example:

// In a field keystroke script
if (event.fieldFull) {
    app.beep(0);
    console.println("Field has reached maximum character limit");
}

keyDown

For mouse events, indicates whether a keyboard key was being held down when the mouse event occurred. This is always false for non-mouse events.

modifier

Indicates whether the CTRL key was held down during a mouse event. This property is only present for mouse events.

example:

// In a field mouse up script
if (event.modifier) {
    console.println("CTRL was held during click");
}

name

The name of the current event. This indicates what specific action triggered the event within its type category.

Possible values include:

• "Init" - App initialization
• "Exec" - Execution events (Batch, Console, External, Menu, Doc)
• "Open" - Opening events (Doc, Page, Screen)
• "Close" - Closing events (Page, Screen)
• "Mouse Up" - Mouse up events (Bookmark, Field, Screen, Link)
• "Mouse Down" - Mouse down events (Field, Screen)
• "Mouse Enter" - Mouse enter events (Field, Screen)
• "Mouse Exit" - Mouse exit events (Field, Screen)
• "Calculate" - Field calculation
• "Validate" - Field validation
• "Format" - Field formatting
• "Keystroke" - Field keystroke
• "Focus" - Focus events (Field, Screen)
• "Blur" - Blur events (Field, Screen)
• "WillClose" - Document will close
• "WillPrint" - Document will print
• "WillSave" - Document will save
• "DidPrint" - Document did print
• "DidSave" - Document did save

example:

console.println("Event name: " + event.name);
console.println("Event type: " + event.type);

rc

Return code that determines whether the event should proceed. Setting this to false cancels the event and prevents the associated action from completing.

This is one of the most important properties for controlling event behavior. It defaults to true, meaning the event will proceed normally. Setting it to false in validation, keystroke, or other "Will" events prevents the action.

example:

// In a field validation script
if (event.value < 0 || event.value > 100) {
    app.alert("Value must be between 0 and 100");
    event.rc = false; // Prevent invalid value
}

// In a Doc WillSave script
if (!this.getField("RequiredField").value) {
    app.alert("Required field is empty");
    event.rc = false; // Prevent save
}

richChange

Array of Span objects representing rich text formatting changes during a keystroke event in a rich text field. Each Span object contains formatting information for a portion of text.

This property is only present when editing rich text fields and allows you to modify the formatting of the text being entered.

richChangeEx

Array of Span objects representing the rich text formatting of text that was deleted or replaced during a keystroke event in a rich text field.

richValue

Array of Span objects representing the complete rich text value of a field. This property is available during format and keystroke events for rich text fields.

selEnd

The ending character position of the current text selection in a field during keystroke events. This is the character position where the selection ends or where the cursor is positioned if there's no selection.

You can modify this value to change the selection programmatically.

example:

// In a field keystroke script
console.println("Selection: " + event.selStart + " to " + event.selEnd);

// Select all text after validation
if (event.willCommit && !isValid(event.value)) {
    event.selStart = 0;
    event.selEnd = event.value.length;
}

selStart

The starting character position of the current text selection in a field during keystroke events. If there's no selection (just a cursor position), this equals selEnd.

example:

// Check if text is selected
if (event.selStart != event.selEnd) {
    var selectedText = event.value.substring(event.selStart, event.selEnd);
    console.println("Selected text: " + selectedText);
}

shift

Indicates whether the Shift key was held down during a mouse event. This property is only present for mouse events.

example:

// In a field mouse up script
if (event.shift) {
    console.println("Shift was held during click");
    // Perform special action for Shift+Click
}

source

The object that triggered the event. For field events, this is typically the Field object. For document events, this is the Doc object. For bookmark events, this is the Bookmark object.

The source represents where the event originated from, while target represents what object the event is acting upon.

example:

// In a field calculate script
console.println("Source field: " + event.source.name);
console.println("Source value: " + event.source.value);

target

The target object of the event. For field events, this is the Field object being acted upon. For document events, this is the Doc object.

In many cases, source and target are the same object, but they can differ in calculation scripts where one field's change (source) triggers another field's calculation (target).

example:

// In a field calculate script
if (event.source != event.target) {
    console.println("Calculation triggered by: " + event.source.name);
    console.println("Calculating for: " + event.target.name);
}

targetName

The name of the target object. For field events, this is the field name. This provides a convenient way to get the target's name without accessing the target object directly.

example:

// In a field script
console.println("Event occurring on field: " + event.targetName);

// Perform different actions based on field name
switch(event.targetName) {
    case "Total":
        // Special handling for Total field
        break;
    case "Subtotal":
        // Special handling for Subtotal field
        break;
}

type

The type category of the event, indicating what kind of object or action triggered it.

Possible values:

• "App" - Application events
• "Bookmark" - Bookmark events
• "Console" - Console events
• "Doc" - Document events
• "External" - External events
• "Field" - Form field events
• "Link" - Link events
• "Menu" - Menu events
• "Page" - Page events

example:

// Determine what kind of event is occurring
console.println("Event type: " + event.type);
console.println("Event name: " + event.name);

if (event.type == "Field") {
    console.println("This is a field event");
}

value

The value associated with the event. The meaning depends on the event type:

• For field validation and calculation events: The proposed new value of the field
• For field format events: The value to be formatted for display
• For field keystroke events when willCommit is true: The value about to be committed

You can modify this property in format events to change how the value is displayed, or in validation events to modify the value before it's committed.

example:

// In a field validation script
if (event.value != "") {
    // Ensure value is within range
    if (event.value < 0) {
        event.value = 0;
    } else if (event.value > 100) {
        event.value = 100;
    }
}

// In a field format script
if (event.value != "") {
    // Format as currency
    event.value = "$" + parseFloat(event.value).toFixed(2);
}

willCommit

For keystroke events, indicates whether the field value is about to be committed (true) or whether the user is still typing (false).

When true, the keystroke event represents the final value being committed to the field. When false, the event represents individual character input as the user types.

This property is essential for distinguishing between character-by-character validation and final value validation.

example:

// In a field keystroke script
if (event.willCommit) {
    // Validate complete value
    if (event.value == "") {
        app.alert("Field cannot be empty");
        event.rc = false;
    }
} else {
    // Validate individual keystrokes
    // Allow only numeric input
    if (!/^\d*$/.test(event.change)) {
        event.rc = false;
    }
}