PDF annotation actions on Android
PDF actions define behavior such as navigation, form submission, and script execution. Nutrient supports common actions from Adobe’s PDF Reference, starting on page 417.
GoTo and URI are the most common action types. Documents also use named actions for page changes.
Nutrient can parse each Action subclass from a PDF:
| Action | Nutrient class | Use case |
|---|---|---|
| GoTo | GoToAction | Go to a page in the current document. |
| URI | UriAction | Open a URI, such as a web link. |
| Hide | HideAction | Set an annotation’s hidden flag. |
| Named | NamedAction | Execute an action that the PDF reader defines. |
| SubmitForm | SubmitFormAction | Submit form data. |
| ResetForm | ResetFormAction | Reset fields to their default values. |
| JavaScript | JavaScriptAction | Execute a JavaScript script. |
For script support, refer to the JavaScript guide.
Chain actions through getSubActions. LinkAnnotation and WidgetAnnotation can contain actions.
An OutlineElement also contains an action and supports the same action types. For example, a PDF outline entry can open a web link.
Trigger events
A WidgetAnnotation can contain additional actions, each associated with an AnnotationTriggerEvent.
Nutrient parses all trigger events but executes actions only for the following events. It ignores unsupported events:
| Event | Use case |
|---|---|
MOUSE_DOWN | Executes an action when a user touches an annotation. |
MOUSE_UP | Executes an action when a user lifts their finger after tapping an annotation. |
RECEIVE_FOCUS | Executes an action when a user selects an annotation. |
LOOSE_FOCUS | Executes an action when a user deselects an annotation. |
FORM_CHANGED | Executes JavaScript when a user types in a text or combo box field or changes a list box selection. The action can reject or modify the keystroke. |
FIELD_FORMAT | Executes JavaScript before formatting a form field. |
FORM_VALIDATE | Executes JavaScript to validate a changed field value. |
FORM_CALCULATE | Executes JavaScript to recalculate a field’s value when another field changes. |
For compatibility with older PDF specifications, Nutrient prioritizes annotation actions from getAction() over additional MOUSE_UP actions.
Form field events (FORM_CHANGED, FIELD_FORMAT, FORM_VALIDATE, and FORM_CALCULATE) support only JavaScriptAction.
Executing actions
Use PdfFragment#executeAction to execute PDF actions:
annotation.action?.let { action -> fragment.executeAction(action)}if (annotation.getAction() != null) { fragment.executeAction(annotation.getAction());}Provide an ActionSender to specify the execution context:
formElement.annotation.action?.let { action -> fragment.executeAction(action, ActionSender(formElement))}WidgetAnnotation annotation = formElement.getAnnotation();if (annotation.getAction() != null) { fragment.executeAction(annotation.getAction(), new ActionSender(formElement));}Always provide ActionSender when executing JavaScriptAction for a form field. Without it, Nutrient executes the script at document level. The script can’t format or validate the field, and event.target refers to the document instead.