Actions

Introduction

A PDF action is an instruction that runs automatically when a specific event occurs, such as opening a document, clicking a link, or interacting with a form. Actions support page navigation, form submission, script execution, file operations, and more, improving PDF interactivity and automation.

Actions fall into two categories:

• Action: Introduced in PDF 1.1. Bound to the A entry on annotations (Link, Screen, Widget, and others), bookmarks (outline items), or the document catalog OpenAction. The viewer runs the action when the object is activated (click, selection, document open)—for example GoTo, Launch, sound, or changing annotation appearance.

• Additional action: Introduced in PDF 1.2. Bound to the AA entry on the catalog, pages, annotations, or form fields. Additional actions respond to trigger events such as enter, leave, mouse down/up, focus gain/loss, or field value change. Each event can specify its own action for finer-grained behavior.

NOTE

The Action class and related subclasses are deprecated. Use the dedicated APIs on objects such as Annot, Widget, PDFFormField, and PDFDoc instead.

Typical use cases

• Page navigation: Jump to a page or view via links or buttons (GoTo, GoToR, GoToE).
• Form interaction: SubmitForm, ResetForm, ImportData, Hide fields, and related behavior.
• Script automation: Run JavaScript on field change, page open, document save, and other events.
• Multimedia and external apps: Launch applications, open URIs, Rendition for multimedia.

Supported action types

Action type	Description	Editable (UI)	Triggerable	API
GoTo	Go to a location in the current document	Y	Y	Y
GoToR	Go to a location in another PDF (not embedded)	Y	N	Y
GoToE	Go to a target in a PDF embedded in another PDF	N	N	Y
Hide	Hide or show form fields	Y	Y	Y
ImportData	Import an FDF file to update form fields	Y	N	Y
JavaScript	Run a JavaScript script	Y	Y	Y
Launch	Launch an external application, often to open a file	Y	N	Y
ResetForm	Reset form fields to default values	Y	Y	Y
SubmitForm	Submit form data to a URL	Y	N	Y
URI	Open a URI	Y	N	Y
Rendition	Multimedia rendition action	N	Y	N

See ActionType and ActionSpecification for details.

Trigger events

Actions depend on trigger events; supported events vary by object. Common groups include:

• Document level (DocActionTriggerEvents): document close, save, print, and others.
• Page level (PageActionTriggerEvents): page open, close.
• Annotation / widget level (AnnotActionTriggerEvents): mouse enter, leave, down, up.
• Form field level (FieldActionTriggerEvents): keystroke, format, value change, recalculate.

Action data structures

• ActionSpecification: Action type and parameters (destination, script, and so on).
• ActionHierarchy: Hierarchical structure with nested child actions.
• ActionData: Concrete action payload.

Main APIs

Action APIs

• Annot.getAllActionData(): All action data for an annotation, including primary and additional actions.
• Annot.getActionData(): Primary action data.
• Annot.setAction(actionSpec): Set primary action.
• Annot.appendAction(actionSpec): Append primary action.
• Annot.updateAction(actionObjNumber, actionData): Update primary action.
• Annot.removeAction(actionObjNumber): Remove primary action.
• Annot.supportsAction(): Whether the annotation type supports actions (screen, link, sound, widget).

Additional action APIs

• getAdditionalAction: Get the additional-action instance.
  • Widget.getAdditionalAction(): On a widget.
  • PDFPage.getAdditionalAction(): On a page.
  • PDFFormField.getAdditionalAction(): On a form field.
  • PDFDoc.getAdditionalAction(): On the document.
• AdditionalAction.setAction(trigger, actionSpec): Set action for an event.
• AdditionalAction.addAction(trigger, actionSpec): Add additional action.
• AdditionalAction.updateActionData(trigger, actionObjNumber, actionData): Update additional action.
• AdditionalAction.removeAction(trigger, actionObjNumber): Remove additional action.
• AdditionalAction.getActions([triggers]): List additional actions for events.

Document-level actions

• PDFDoc.setOpenAction(actionType, actionData): Action when the document opens.
• PDFDoc.getOpenAction(): Get open action.
• PDFDoc.removeOpenAction(): Remove open action.

Notes on using actions

• Only some annotation types support actions: screen, link, sound, and widget.

• Only some annotation types support additional actions: screen and widget.

• Trigger event types must match the object type or they have no effect (AnnotActionTriggerEvents, DocActionTriggerEvents, FieldActionTriggerEvents, PageActionTriggerEvents). PageActionTriggerEvents applies to pages.

• Some action types (GotoR, GoToE, Rendition) have limited SDK support—trigger-only or set-via-API only.

Action vs additional action

Action

Action is the core PDF 1.1 mechanism, defined via the A entry:

• Direct binding: On annotation or bookmark dictionaries.
• Single trigger: Usually on activation (link click, bookmark selection).
• Chaining: Next entries build action chains.
• Document level: OpenAction on the catalog.

Additional action

Additional action is the PDF 1.2 extension via the AA entry:

• Event-driven: Specific trigger events, not only activation.
• Multiple events: Different actions per event on one object.
• Broad scope: Document, page, annotation, form field.
• Fine control: Mouse enter/leave, focus, and similar events.

Comparison

Feature	Action	Additional action
PDF version	PDF 1.1	PDF 1.2
Binding	A entry	AA entry
Trigger	Activation (e.g. click)	Event-driven
Event types	Single (activate)	Many (enter, leave, down, up, etc.)
Objects	Annotations, bookmarks, document	Document, page, annotations, form fields
Complexity	Simpler	More flexible
Typical use	Navigation, link click	Form validation, dynamic UI, state changes

Trigger event reference

Foxit PDF SDK for Web defines ActionTriggerEvents in four groups.

Document events (DocActionTriggerEvents)

• DOC_WILL_CLOSE: Before the document closes.
• DOC_WILL_SAVE: Before save.
• DOC_SAVED: After save.
• DOC_WILL_PRINT: Before print.
• DOC_PRINTED: After print.

Page events (PageActionTriggerEvents)

• PAGE_OPENED: When a page opens.
• PAGE_CLOSED: When a page closes.

Annotation / widget events (AnnotActionTriggerEvents)

• ANNOT_CURSOR_ENTER: Pointer enters the annotation area.
• ANNOT_CURSOR_EXIT: Pointer leaves the annotation area.
• ANNOT_MOUSE_BUTTON_PRESSED: Mouse button down in the area.
• ANNOT_MOUSE_BUTTON_RELEASED: Mouse button up in the area.
• ANNOT_RECEIVE_INPUT_FOCUS: Widget gains input focus.
• ANNOT_LOSE_INPUT_FOCUS: Widget loses input focus.
• ANNOT_PAGE_OPENED: Page containing the annotation opens (after PAGE_OPENED and open action).
• ANNOT_PAGE_CLOSED: Page closes (after PAGE_CLOSED).
• ANNOT_PAGE_VISIBLE: Page becomes visible in the viewer UI.
• ANNOT_PAGE_INVISIBLE: Page becomes invisible in the viewer UI.

Form field events (FieldActionTriggerEvents)

• FIELD_KEY_STROKE: Keystroke or list selection change in text or combo fields; validate or modify input.

• FIELD_WILL_FORMAT: Before the displayed value is formatted; modify the value.

• FIELD_VALUE_CHANGED: When the field value changes; validate the new value.

• FIELD_RECALCULATE_VALUE: When other fields change; recalculate this field. Order via PDFForm.getFieldsInCalculationOrder.

Examples

Action examples

// GoTo action on a link annotation
linkAnnot.setAction({
    type: "GoTo",
    dest: {page: 5, view: "FitH"},
});

// Document open action
pdfDoc.setOpenAction(PDF.actions.ActionType.javaScript, {
    script: 'app.alert("Welcome to this document!");',
});

Additional action examples

// Validate on field value change
const additionalAction = formField.getAdditionalAction();
additionalAction.setAction(PDF.actions.ActionTriggerEvents.FIELD_VALUE_CHANGED, {
    type: PDF.actions.ActionType.javaScript,
    data: {
        javascript: 'if (event.value < 0) { app.alert("Value cannot be negative"); event.rc = false; }'
    },
});

// Initialize when page opens
const pageAdditionalAction = pdfPage.getAdditionalAction();
pageAdditionalAction.setAction(PDF.actions.ActionTriggerEvents.PAGE_OPENED, {
    type: PDF.actions.ActionType.javaScript,
    data: {
        javascript: 'console.log("Page opened");',
    }
});


// Highlight when pointer enters annotation
const annotAdditionalAction = annotation.getAdditionalAction();
annotAdditionalAction.setAction(PDF.actions.ActionTriggerEvents.ANNOT_CURSOR_ENTER, {
    type: PDF.actions.ActionType.javaScript,
    data: {
        javascript: "this.highlight = true;",
    }
});

// Validate before save
const docAdditionalAction = pdfDoc.getAdditionalAction();
docAdditionalAction.setAction(PDF.actions.ActionTriggerEvents.DOC_WILL_SAVE, {
    type: PDF.actions.ActionType.javaScript,
    data: {
        javascript: 'if (!validateFormData()) { event.rc = false; app.alert("Please complete required fields"); }',
    }
});