Form interaction event handling

Foxit PDF SDK for Web provides a complete event handling mechanism for form interaction in fill mode, so developers can control and customize form behavior precisely. The mechanism supports mouse events (press, move, release, and others) and keyboard events (key down, key up, and others). You can implement control in three ways:

• Event listeners: Listen with FormFillerService.onMouseDownWidget, FormFillerService.onMouseMoveWidget, and related methods.
• Interceptors: Implement the FormInteractionEventInterceptor interface to intercept and handle form interaction events.
• Method override: Register mixin methods with ViewerAnnotManager.registerMatchRule, extend WidgetAnnot, and override methods such as handleOnGotFocus and handleOnClick.

The following sections describe each approach.

Form interaction event listeners

Event listeners let you handle logic that is independent of the widget implementation during interaction, without changing default widget behavior. Typical use cases include:

• User behavior analytics:
  • Collect interaction data (clicks, movement, keyboard input) on form widgets.
• Real-time help and tips:
  • Show help or tooltips when the user focuses on or clicks specific fields.
• Other scenarios:
  • Extend behavior for your business requirements.

Foxit PDF SDK for Web provides these listener methods:

• FormFillerService.onMouseDownWidget: Mouse button down.
• FormFillerService.onMouseMoveWidget: Mouse move.
• FormFillerService.onMouseUpWidget: Mouse button up.
• FormFillerService.onClickWidget: Left-click.
• FormFillerService.onRightClickWidget: Right-click.
• FormFillerService.onMouseOverWidget: Mouse enter.
• FormFillerService.onMouseLeaveWidget: Mouse leave.
• FormFillerService.onKeyDown: Key down.
• FormFillerService.onKeyUp: Key up.
• FormFillerService.onFocusChange: Focus change.

See FormFillerService in the API Reference for more.

Example:

const formFillerService = pdfViewer.getFormFillerService();
// Call the returned function to remove the listener when needed
const removeEvent = formFillerService.onMouseOverWidget((widgetId, event) => {
    console.log('Mouse over widget:', widgetId, event);
});

const removeEvent = formFillerService.onMouseDownWidget((widgetId, event) => {
    if (widgetId) {
        console.log('Mouse down on widget:', widgetId, event);
    } else {
        console.log('Mouse down on page');
    }
});

Form interaction event interceptors

Interceptors let you intervene before or after an event and allow or block propagation. Typical use cases include:

• Access control:
  • Control whether fields are interactive based on user role or permissions.
• UI protection:
  • Intercept events (for example mouseup) and prompt for confirmation before high-risk actions.
• Behavior modification:
  • Change interaction behavior for specific scenarios.

The interceptor interface is:

interface FormInteractionEvent {
    type: string; // mousedown|mousemove|mouseup|keydown|keyup
    timestamp: number; // Event timestamp in milliseconds
}

interface FormInteractionEventInterceptorOptions {
    type: FormInteractionEvent;
    widgetId: AnnotId;
}

type FormInteractionEventInterceptor = (options: FormInteractionEventInterceptorOptions, next: () => Promise<unknown>) => Promise<void>;

The options parameter includes the target widget ID (an object with pageIndex and objNumber) and the event type. next invokes the next interceptor. See FormInteractionEventInterceptor for details.

Example:

// removeInterceptor removes the interceptor when appropriate
const removeInterceptor = formFillerService.appendInteractionEventInterceptor(async (options, next) => {
    if (options.type === 'mouseup') {
        // Intercept mouse up
        console.log("Before mouse up");
        // Call the next interceptor or the real handler
        await next();
        // Run after mouse up completes
        console.log("After mouse up");
    }
})

NOTE

1. If you do not call next, the interceptor blocks the event and internal SDK handling does not run.
2. click and right-click are composite events derived from mousedown/mouseup under certain conditions; you cannot handle them directly—intercept mousedown or mouseup instead.

A full example is in examples/UIExtension/form/interaction-event-interceptor/index.js.

Method override

Method override uses ViewerAnnotManager.registerMatchRule to register a mixin, extend WidgetAnnot, and override handleOnGotFocus, handleOnClick, and related methods. Besides listening to events, you can control whether the SDK runs its default presentation-layer logic. Typical use cases include:

• All scenarios supported by event listeners.
• Scenarios where you need to replace Foxit PDF SDK for Web presentation-layer behavior.

Overridable event-related methods include:

• handleOnClick: Left-click.
• handleOnMouseOver: Mouse enter.
• handleOnMouseLeave: Mouse leave.
• handleOnGotFocus: Focus gained.
• handleOnLostFocus: Focus lost.

NOTE

To override right-click or customize the context menu, override showContextMenu.

Example:

pdfViewer.getAnnotManager().registerMatchRule(function (annot, AnnotComponentClass) {
    if (annot.getType() !== 'widget') {
        return;
    }
    return class CustomWidgetAnnot extends AnnotComponentClass {
        handleOnClick() {
            super.handleOnClick();
            console.log('CustomWidgetAnnot handleOnClick');
        }

        handleOnMouseOver() {
            super.handleOnMouseOver();
            console.log('Handle on mouse over');
        }

        handleOnMouseLeave() {
            super.handleOnMouseLeave();
            console.log('Handle on mouse leave');
        }

        handleOnGotFocus() {
            super.handleOnGotFocus();
            console.log('Handle on got focus');
        }

        handleOnLostFocus() {
            super.handleOnLostFocus();
            console.log('Handle on lost focus');
        }
    }
})

Comparison

Approach	Supported events	Control level	Flexibility
Event listeners	mousedown/mouseover/mouseup/click/right-click/mouseover/mouseleave/keydown/keyup/focus-change	After event	Moderate
Interceptors	mousedown/mousemove/mouseup/keydown/keyup	Before and after event	Highest
Method override	click/mouseover/mouseleave/get-focus/lost-focus	After event	Moderate