Repository navigation
PDF Spec 12 Actions
Part of: PDF-Spec-12-Interactive-Features
Navigation: PDF-Spec-12-Annotations | PDF-Spec-Index | PDF-Spec-12-Forms
| TP | integer | (Optional; pushbutton fields only) A code indicating where to position the text of the widget annotation's caption relative to its icon: 0 No icon; caption only 1 No caption; icon only 2 Caption below the icon 3 Caption above the icon 4 Caption to the right of the icon 5 Caption to the left of the icon 6 Caption overlaid directly on the icon Default value: 0. |
A printer's mark annotation (PDF 1.4) represents a graphic symbol, such as a registration target, colour bar, or cut mark, that may be added to a page to assist production personnel in identifying components of a multipleplate job and maintaining consistent output during production. See 14.11.3, 'Printer's Marks,' for further discussion.
A trap network annotation (PDF 1.3) may be used to define the trapping characteristics for a page of a PDF document.
NOTE Trapping is the process of adding marks to a page along colour boundaries to avoid unwanted visual artifacts resulting from misregistration of colorants when the page is printed.
A page shall have no more than one trap network annotation, whose Subtype entry has the value TrapNet and which shall always be the last element in the page object's Annots array (see 7.7.3.3, 'Page Objects'). See 14.11.6, 'Trapping Support,' for further discussion.
A watermark annotation (PDF 1.6) shall be used to represent graphics that shall be printed at a fixed size and position on a page, regardless of the dimensions of the printed page. The FixedPrint entry of a watermark annotation dictionary (see Table 190) shall be a dictionary that contains values for specifying the size and position of the annotation (see Table 191).
Watermark annotations shall have no pop-up window or other interactive elements. When displaying a watermark annotation on-screen, conforming readers shall use the dimensions of the media box as the page size so that the scroll and zoom behaviour is the same as for other annotations.
NOTE Since many printing devices have non printable margins, such margins should be taken into consideration when positioning watermark annotations near the edge of a page.
Table 190 - Additional entries specific to a watermark annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Watermark for a watermark annotation. |
| FixedPrint | dictionary | (Optional) A fixed print dictionary (see Table 191) that specifies how this annotation shall be drawn relative to the dimensions of the target media. If this entry is not present, the annotation shall be drawn without any special consideration for the dimensions of the target media. If the dimensions of the target media are not known at the time of drawing, drawing shall be done relative to the dimensions specified by the page's MediaBox entry (see Table 30). |
Table 191 - Entries in a fixed print dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Required) Shall be FixedPrint . |
| Matrix | array | (Optional) The matrix used to transform the annotation's rectangle before rendering. Default value: the identity matrix [1 0 0 1 0 0]. When positioning content near the edge of a page, this entry should be used to provide a reasonable offset to allow for nonburnable margins. |
| H | number | (Optional) The amount to translate the associated content horizontally, as a percentage of the width of the target media (or if unknown, the width of the page's MediaBox ). 1.0 represents 100% and 0.0 represents 0%. Negative values should not be used, since they may cause content to be drawn off the page. Default value: 0. |
| V | number | (Optional) The amount to translate the associated content vertically, as a percentage of the height of the target media (or if unknown, the height of the page's MediaBox ). 1.0 represents 100% and 0.0 represents 0%. Negative values should not be used, since they may cause content to be drawn off the page. Default value: 0. |
When rendering a watermark annotation with a FixedPrint entry, the following behaviour shall occur:
- The annotation's rectangle (as specified by its Rect entry) shall be translated to the origin and transformed by the Matrix entry of its FixedPrint dictionary to produce a quadrilateral with arbitrary orientation.
- The transformed annotation rectangle shall be defined as the smallest upright rectangle that encompasses this quadrilateral; it shall be used in place of the annotation rectangle referred to in steps 2 and 3 of "Algorithm: Appearance streams".
In addition, given a matrix B that maps a scaled and rotated page into the default user space, a new matrix shall be computed that cancels out B and translates the origin of the printed page to the origin of the default user space. This transformation shall be applied to ensure the correct scaling and alignment.
EXAMPLE
The following example shows a watermark annotation that prints a text string one inch from the left and one inch from the top of the printed page.
8 0 obj % Watermark appearance << /Length ... /Subtype /Form /Resources ... /BBox ... >> stream ... BT /F1 1 Tf 36 0 0 36 0 -36 Tm (Do Not Build) Tx ET ... endstream endobj 9 0 obj % Watermark annotation << /Rect ... /Type /Annot /Subtype /Watermark /FixedPrint 10 0 R /AP <</N 8 0 R>> >> % in the page dictionary /Annots [9 0 R] 10 0 obj % Fixed print dictionary << /Type /FixedPrint /Matrix [1 0 0 1 72 -72] % Translate one inch right and one inch down /H 0 /V 1.0 % Translate the full height of the page vertically >> endobj
In situations other than the usual case where the PDF page size equals the printed page size, watermark annotations with a FixedPrint entry shall be printed in the following manner:
- When page tiling is selected in a conforming reader (that is, a single PDF page is printed on multiple pages), the annotations shall be printed at the specified size and position on each page to ensure that any enclosed content is present and legible on each printed page.
- When n -up printing is selected (that is, multiple PDF pages are printed on a single page), the annotations shall be printed at the specified size and shall be positioned as if the dimensions of the printed page were limited to a single portion of the page. This ensures that any enclosed content does not overlap content from other pages, thus rendering it illegible.
A redaction annotation ( PDF 1.7 ) identifies content that is intended to be removed from the document. The intent of redaction annotations is to enable the following process:
-
a) Content identification . A user applies redact annotations that specify the pieces or regions of content that should be removed. Up until the next step is performed, the user can see, move and redefine these annotations.
-
b) Content removal . The user instructs the viewer application to apply the redact annotations, after which the content in the area specified by the redact annotations is removed. In the removed content's place, some marking appears to indicate the area has been redacted. Also, the redact annotations are removed from the PDF document.
Redaction annotations provide a mechanism for the first step in the redaction process (content identification). This allows content to be marked for redaction in a non-destructive way, thus enabling a review process for evaluating potential redactions prior to removing the specified content.
Redaction annotations shall provide enough information to be used in the second phase of the redaction process (content removal). This phase is application-specific and requires the conforming reader to remove all content identified by the redaction annotation, as well as the annotation itself.
Conforming readers that support redaction annotations shall provide a mechanism for applying content removal, and they shall remove all traces of the specified content. If a portion of an image is contained in a redaction region, that portion of the image data shall be destroyed; clipping or image masks shall not be used to hide that data. Such conforming readers shall also be diligent in their consideration of all content that can exist in a PDF document, including XML Forms Architecture (XFA) content and Extensible Metadata Platform (XMP) content.
Table 192 - Additional entries specific to a redaction annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | ( Required ) The type of annotation that this dictionary describes; shall be Redact for a redaction annotation. |
| QuadPoints | array | ( Optional ) An array of 8 x n numbers specifying the coordinates of n quadrilaterals in default user space, as described in Table 175 for text markup annotations. If present, these quadrilaterals denote the content region that is intended to be removed. If this entry is not present, the Rect entry denotes the content region that is intended to be removed. |
| IC | array | ( Optional ) An array of three numbers in the range 0.0 to 1.0 specifying the components, in the DeviceRGB colour space, of the interior colour with which to fill the redacted region after the affected content has been removed. If this entry is absent, the interior of the redaction region is left transparent. This entry is ignored if the RO entry is present. |
| RO | stream | ( Optional ) A form XObject specifying the overlay appearance for this redaction annotation. After this redaction is applied and the affected content has been removed, the overlay appearance should be drawn such that its origin lines up with the lower-left corner of the annotation rectangle. This form XObject is not necessarily related to other annotation appearances, and may or may not be present in the AP dictionary. This entry takes precedence over the IC , OverlayText , DA , and Q entries. |
| OverlayText | text string | ( Optional ) A text string specifying the overlay text that should be drawn over the redacted region after the affected content has been removed. This entry is ignored if the RO entry is present. |
| Repeat | boolean | ( Optional ) If true , then the text specified by OverlayText should be repeated to fill the redacted region after the affected content has been removed. This entry is ignored if the RO entry is present. Default value: false . |
| DA | byte string | ( Required if OverlayText is present, ignored otherwise ) The appearance string to be used in formatting the overlay text when it is drawn after the affected content has been removed (see 12.7.3.3, 'Variable Text'). This entry is ignored if the RO entry is present. |
Table 192 - Additional entries specific to a redaction annotation (continued)
| Key | Type | Value |
|---|---|---|
| Q | integer | ( Optional ) A code specifying the form of quadding (justification) to be used in laying out the overlay text: 0 Left-justified 1 Centered 2 Right-justified This entry is ignored if the RO entry is present. Default value: 0 (left- justified). |
In addition to jumping to a destination in the document, an annotation or outline item may specify an action (PDF 1.1) to perform, such as launching an application, playing a sound, changing an annotation's appearance state. The optional A entry in the annotation or outline item dictionary (see Tables 168 and 153) specifies an action performed when the annotation or outline item is activated; in PDF 1.2, a variety of other circumstances may trigger an action as well (see 12.6.3, 'Trigger Events'). In addition, the optional OpenAction entry in a document's catalogue (7.7.2, 'Document Catalog') may specify an action that shall be performed when the document is opened. PDF includes a wide variety of standard action types, described in detail in 12.6.4, 'Action Types.'
An action dictionary defines the characteristics and behaviour of an action. Table 193 shows the required and optional entries that are common to all action dictionaries. The dictionary may contain additional entries specific to a particular action type; see the descriptions of individual action types in 12.6.4, 'Action Types,' for details.
Table 193 - Entries common to all action dictionaries
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be Action for an action dictionary. |
| S | name | (Required) The type of action that this dictionary describes; see Table 194 for specific values. |
| Next | dictionary or array | (Optional; PDF 1.2) The next action or sequence of actions that shall be performed after the action represented by this dictionary. The value is either a single action dictionary or an array of action dictionaries that shall be performed in order; see the Note for further discussion. |
- NOTE 1 The action dictionary's Next entry (PDF 1.2) allows sequences of actions to be chained together. For example, the effect of clicking a link annotation with the mouse might be to play a sound, jump to a new page, and start up a movie. Note that the Next entry is not restricted to a single action but may contain an array of actions, each of which in turn may have a Next entry of its own. The actions may thus form a tree instead of a simple linked list. Actions within each Next array are executed in order, each followed in turn by any actions specified in its Next entry, and so on recursively. Conforming readers should attempt to provide reasonable behavior in anomalous situations. For example, self-referential actions should not be executed more than once, and actions that close the document or otherwise render the next action impossible should terminate the execution sequence. Applications should also provide some mechanism for the user to interrupt and manually terminate a sequence of actions.
PDF 1.5 introduces transition actions, which allow the control of drawing during a sequence of actions; see 12.6.4.14, 'Transition Actions.'
- NOTE 2 No action should modify its own action dictionary or any other in the action tree in which it resides. The effect of such modification on subsequent execution of actions in the tree is undefined.
An annotation, page object, or (beginning with PDF 1.3) interactive form field may include an entry named AA that specifies an additional-actions dictionary (PDF 1.2) that extends the set of events that can trigger the execution of an action. In PDF 1.4, the document catalogue dictionary (see 7.7.2, 'Document Catalog') may also contain an AA entry for trigger events affecting the document as a whole. Tables 194 to 197 show the contents of this type of dictionary.
PDF 1.5 introduces four trigger events in annotation's additional-actions dictionary to support multimedia presentations:
- The PO and PC entries have a similar function to the O and C entries in the page object's additionalactions dictionary (see Table 194). However, associating these triggers with annotations allows annotation objects to be self-contained.
EXAMPLE Annotations containing such actions can be copied or moved between pages without requiring page open/close actions to be changed.
- The PV and PI entries allow a distinction between pages that are open and pages that are visible. At any one time, while more than one page may be visible, depending on the page layout.
- NOTE 1 For these trigger events, the values of the flags specified by the annotation's F entry (see 12.5.3, 'Annotation Flags') have no bearing on whether a given trigger event occurs.
Table 194 - Entries in an annotation's additional-actions dictionary
| Key | Type | Value |
|---|---|---|
| E | dictionary | (Optional; PDF 1.2) An action that shall be performed when the cursor enters the annotation's active area. |
| X | dictionary | (Optional; PDF 1.2) An action that shall be performed when the cursor exits the annotation's active area. |
| D | dictionary | (Optional; PDF 1.2) An action that shall be performed when the mouse button is pressed inside the annotation's active area. |
| U | dictionary | (Optional; PDF 1.2) An action that shall be performed when the mouse button is released inside the annotation's active area. For backward compatibility, the A entry in an annotation dictionary, if present, takes precedence over this entry (see Table 168). |
| Fo | dictionary | (Optional; PDF 1.2; widget annotations only) An action that shall be performed when the annotation receives the input focus. |
| Bl | dictionary | (Optional; PDF 1.2; widget annotations only) (Uppercase B, lowercase L) An action that shall be performed when the annotation loses the input focus. |
| PO | dictionary | (Optional; PDF 1.5) An action that shall be performed when the page containing the annotation is opened. EXAMPLE 1 When the user navigates to it from the next or previous page or by means of a link annotation or outline item. The action shall be executed after the O action in the page's additional-actions dictionary (see Table 195) and the OpenAction entry in the document Catalog (see Table 28), if such actions are present. |
Table 194 - Entries in an annotation's additional-actions dictionary (continued)
| Key | Type | Value |
|---|---|---|
| PC | dictionary | (Optional; PDF 1.5) An action that shall be performed when the page containing the annotation is closed. EXAMPLE 2 When the user navigates to the next or previous page, or follows a link annotation or outline item. The action shall be executed before the C action in the page's additional- actions dictionary (see Table 195), if present. |
| PV | dictionary | (Optional; PDF 1.5) An action that shall be performed when the page containing the annotation becomes visible. |
| PI | dictionary | (Optional; PDF 1.5) An action that shall be performed when the page containing the annotation is no longer visible in the conforming reader's user interface. |
Table 195 - Entries in a page object's additional-actions dictionary
| Key | Type | Value |
|---|---|---|
| O | dictionary | (Optional; PDF 1.2) An action that shall be performed when the page is opened (for example, when the user navigates to it from the next or previous page or by means of a link annotation or outline item). This action is independent of any that may be defined by the OpenAction entry in the document Catalog (see 7.7.2, 'Document Catalog') and shall be executed after such an action. |
| C | dictionary | (Optional; PDF 1.2) An action that shall be performed when the page is closed (for example, when the user navigates to the next or previous page or follows a link annotation or an outline item). This action applies to the page being closed and shall be executed before any other page is opened. |
Table 196 - Entries in a form field's additional-actions dictionary
| Key | Type | Value |
|---|---|---|
| K | dictionary | (Optional; PDF 1.3) A JavaScript action that shall be performed when the user modifies a character in a text field or combo box or modifies the selection in a scrollable list box. This action may check the added text for validity and reject or modify it. |
| F | dictionary | (Optional; PDF 1.3) A JavaScript action that shall be performed before the field is formatted to display its value. This action may modify the field's value before formatting. |
| V | dictionary | (Optional; PDF 1.3) A JavaScript action that shall be performed when the field's value is changed. This action may check the new value for validity. (The name V stands for 'validate.') |
| C | dictionary | (Optional; PDF 1.3) A JavaScript action that shall be performed to recalculate the value of this field when that of another field changes. (The name C stands for 'calculate.') The order in which the document's fields are recalculated shall be defined by the CO entry in the interactive form dictionary (see 12.7.2, 'Interactive Form Dictionary'). |
Table 197 - Entries in the document catalog's additional-actions dictionary
| Key | Type | Value |
|---|---|---|
| dictionary | (Optional; PDF 1.4) A JavaScript action that shall be performed before closing a document. (The name WC stands for 'will close.') | WC |
| dictionary | (Optional; PDF 1.4) A JavaScript action that shall be performed before saving a document. (The name WS stands for 'will save.') | WS |
| dictionary | (Optional; PDF 1.4) A JavaScript action that shall be performed after saving a document. (The name DS stands for 'did save.') | DS |
| WP dictionary | (Optional; PDF 1.4) A JavaScript action that shall be performed before a | printing document. (The name WP stands for 'will print.') |
| DP | dictionary | (Optional; PDF 1.4) A JavaScript action that shall be performed after printing a document. (The name DP stands for 'did print.') |
Conforming readers shall ensure the presence of such a device, or equivalent controls for simulating one, for the corresponding actions to be executed correctly. Mouse-related trigger events are subject to the following constraints:
- An E (enter) event may occur only when the mouse button is up.
- An X (exit) event may not occur without a preceding E event.
- A U (up) event may not occur without a preceding E and D event.
- In the case of overlapping or nested annotations, entering a second annotation's active area causes an X event to occur for the first annotation.
- NOTE 2 The field-related trigger events K (keystroke), F (format), V (validate), and C (calculate) are not defined for button fields (see 12.7.4.2, 'Button Fields'). The effects of an action triggered by one of these events are limited only by the action itself and can occur outside the described scope of the event. For example, even though the F event is used to trigger actions that format field values prior to display, it is possible for an action triggered by this event to perform a calculation or make any other modification to the document.
These field-related trigger events can occur either through user interaction or programmatically, such as in response to the NeedAppearances entry in the interactive form dictionary (see 12.7.2, 'Interactive Form Dictionary'), importation of FDF data (12.7.7, 'Forms Data Format'), or JavaScript actions (12.6.4.16, 'JavaScript Actions'). For example, the user's modifying a field value can trigger a cascade of calculations and further formatting and validation for other fields in the document.
PDF supports the standard action types listed in Table 198. The following sub-clauses describe each of these types in detail.
Table 198 - Action types
| Action type | Description | Discussed in sub-clause |
|---|---|---|
| GoTo | Go to a destination in the current document. 12.6.4.2, 'Go-To Actions' | |
| GoToR | ('Go-to remote') Go to a destination in another 12.6.4.3, 'Remote Go-To Actions' | |
| GoToE | ('Go-to embedded'; PDF 1.6 ) Go to a destination in 12.6.4.4, 'Embedded Go-To Actions' |
Table 198 - Action types (continued)
| Action type | Description | Discussed in sub-clause |
|---|---|---|
| Launch Launch an application, | a file. 12.6.4.5, 'Launch Actions' | usually to open |
| Begin reading an article thread. | 12.6.4.6, 'Thread Actions' | Thread |
| URI | Resolve a uniform resource identifier. 12.6.4.7, 'URI Actions' | |
| (PDF 1.2) Play a sound. | 12.6.4.8, 'Sound Actions' | Sound |
| (PDF 1.2) Play a movie. | 12.6.4.9, 'Movie Actions' | Movie |
| Hide (PDF 1.2) Set an | flag. 12.6.4.10, 'Hide Actions' | annotation's Hidden |
| Named (PDF 1.2) conforming | Execute an action predefined by the reader. 12.6.4.11, 'Named Actions' | |
| (PDF 1.2) Send data to a uniform resource locator. | 12.7.5.2, 'Submit-Form Action' | SubmitForm |
| (PDF 1.2) Set fields to their default values. | 12.7.5.3, 'Reset-Form Action' | ResetForm |
| (PDF 1.2) Import field values from a file. | 12.7.5.4, 'Import-Data Action' | ImportData |
| (PDF 1.3) Execute a JavaScript script. | 12.6.4.16, 'JavaScript Actions' | JavaScript |
| (PDF 1.5) Set the states of optional content groups. | 12.6.4.12, 'Set-OCG-State Actions' | SetOCGState |
| Rendition (PDF 1.5) Controls the | multimedia content. 12.6.4.13, 'Rendition Actions' | playing of |
| Trans (PDF 1.5) Updates the | document, using 12.6.4.14, 'Transition Actions' | display of a |
| GoTo3DView (PDF 1.6) Set the current | of a 3D annotation 12.6.4.15, 'Go-To-3D-View Actions,' | view |
NOTE The set-state action is considered obsolete and should not be used.
A go-to action changes the view to a specified destination (page, location, and magnification factor). Table 199 shows the action dictionary entries specific to this type of action.
Table 199 - Additional entries specific to a go-to action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be GoTo for a go-to action. |
| D | name, byte string, or array | (Required) The destination to jump to (see 12.3.2, 'Destinations'). |
NOTE Specifying a go-to action in the A entry of a link annotation or outline item (see Table 173 and Table 153) has the same effect as specifying the destination directly with the Dest entry. For example, the link annotation shown in the Example in 12.6.4.12, 'Set-OCG-State Actions,' which uses a go-to action, has the same effect as the one in the following Example, which specifies the destination directly. However, the go-to action is less compact and is not compatible with PDF 1.0; therefore, using a direct destination is preferable.
EXAMPLE 93 0 obj << /Type /Annot /Subtype /Link /Rect [ 71 717 190 734 ] /Border [ 16 16 1 ] /A << /Type /Action /S /GoTo /D [ 3 0 R /FitR -4 399 199 533 ] >> >> endobj
A remote go-to action is similar to an ordinary go-to action but jumps to a destination in another PDF file instead of the current file. Table 200 shows the action dictionary entries specific to this type of action.
NOTE Remote go-to actions cannot be used with embedded files; see 12.6.4.4, 'Embedded Go-To Actions.'
Table 200 - Additional entries specific to a remote go-to action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be GoToR for a remote go-to action. |
| F | file specification | (Required) The file in which the destination shall be located. |
| D | name, byte string, or array | (Required) The destination to jump to (see 12.3.2, 'Destinations'). If the value is an array defining an explicit destination (as described under 12.3.2.2, 'Explicit Destinations'), its first element shall be a page number within the remote document rather than an indirect reference to a page object in the current document. The first page shall be numbered 0. |
| NewWindow | boolean | (Optional; PDF 1.2) A flag specifying whether to open the destination document in a new window. If this flag is false , the destination document replaces the current document in the same window. If this entry is absent, the conforming reader should behave in accordance with its preference. |
An embedded go-to action (PDF 1.6) is similar to a remote go-to action but allows jumping to or from a PDF file that is embedded in another PDF file (see 7.11.4, 'Embedded File Streams'). Embedded files may be associated with file attachment annotations (see 12.5.6.15, 'File Attachment Annotations') or with entries in the EmbeddedFiles name tree (see 7.7.4, 'Name Dictionary'). Embedded files may in turn contain embedded files. Table 201 shows the action dictionary entries specific to embedded go-to actions.
Embedded go-to actions provide a complete facility for linking between a file in a hierarchy of nested embedded files and another file in the same or different hierarchy. The following terminology shall be used:
- The source is the document containing the embedded go-to action.
- The target is the document in which the destination lives.
- The T entry in the action dictionary is a target dictionary that locates the target in relation to the source, in much the same way that a relative path describes the physical relationship between two files in a file system. Target dictionaries may be nested recursively to specify one or more intermediate targets before reaching the final one. As the hierarchy is navigated, each intermediate target shall be referred to as the current document . Initially, the source is the current document.
NOTE It is an error for a target dictionary to have an infinite cycle (for example, one where a target dictionary refers to itself). Conforming readers should attempt to detect such cases and refuse to execute the action if found.
- A child document shall be one that is embedded within another PDF file.
- The document in which a file is embedded shall be its parent .
- A root document is one that is not embedded in another PDF file. The target and source may be contained in root documents or embedded documents.
Table 201 - Additional entries specific to an embedded go-to action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be GoToE for an embedded go-to action. |
| F | file specification | (Optional) The root document of the target relative to the root document of the source. If this entry is absent, the source and target share the same root document. |
| D | name, byte string, or array | (Required) The destination in the target to jump to (see 12.3.2, 'Destinations'). |
| NewWindow | boolean | (Optional) If true , the destination document should be opened in a new window; if false , the destination document should replace the current document in the same window. If this entry is absent, the conforming reader should act according to its preference. |
| T | dictionary | (Optional if F is present; otherwise required) A target dictionary (see Table 202) specifying path information to the target document. Each target dictionary specifies one element in the full path to the target and may have nested target dictionaries specifying additional elements. |
Table 202 - Entries specific to a target dictionary
| Key | Type | Value |
|---|---|---|
| R | name | (Required) Specifies the relationship between the current document and the target (which may be an intermediate target). Valid values are P (the target is the parent of the current document) and C (the target is a child of the current document). |
| N | byte string | (Required if the value of R is C and the target is located in the EmbeddedFiles name tree; otherwise, it shall be absent) The name of the file in the EmbeddedFiles name tree. |
| P | integer or byte string | (Required if the value of R is C and the target is associated with a file attachment annotation; otherwise, it shall be absent) If the value is an integer, it specifies the page number (zero-based) in the current document containing the file attachment annotation. If the value is a string, it specifies a named destination in the current document that provides the page number of the file attachment annotation. |
| A | integer or text string | (Required if the value of R is C and the target is associated with a file attachment annotation; otherwise, it shall be absent) If the value is an integer, it specifies the index (zero-based) of the annotation in the Annots array (see Table 30) of the page specified by P . If the value is a text string, it specifies the value of NM in the annotation dictionary (see Table 164). |
| T | dictionary | (Optional) A target dictionary specifying additional path information to the target document. If this entry is absent, the current document is the target file containing the destination. |
EXAMPLE
The following example illustrates several possible relationships between source and target. Each object shown is an action dictionary for an embedded go-to action.
1 0 obj % Link to a child << /Type /Action /S /GoToE /D (Chapter 1) /T << /R /C /N (Embedded document) >> >> endobj 2 0 obj % Link to the parent << /Type /Action /S /GoToE /D (Chapter 1) /T << /R /P >> >> endobj 3 0 obj % Link to a sibling << /Type /Action /S /GoToE /D (Chapter 1) /T << /R /P /T << /R /C /N (Another embedded document) >> >> >> endobj 4 0 obj % Link to an embedded file in an external document << /Type /Action /S /GoToE /D (Chapter 1) /F (someFile.pdf) /T << /R /C /N (Embedded document) >> >> endobj 5 0 obj % Link from an embedded file to a normal file << /Type /Action /S /GoToE /D (Chapter 1) /F (someFile.pdf) >> endobj 6 0 obj % Link to a grandchild << /Type /Action /S /GoToE /D (Chapter 1) /T << /R /C /N (Embedded document) /T << /R /C /P (A destination name) /A (annotName) >> >> >> endobj 7 0 obj % Link to a niece/nephew through the source's parent
<< /Type /Action /S /GoToE /D (destination) /T << /R /P /T << /R /C /N (Embedded document) /T << /R /C /P 3 /A (annotName) >> >> >> >> endobj
A launch action launches an application or opens or prints a document. Table 203 shows the action dictionary entries specific to this type of action.
The optional Win , Mac , and Unix entries allow the action dictionary to include platform-specific parameters for launching the designated application. If no such entry is present for the given platform, the F entry shall be used instead. Table 203 shows the platform-specific launch parameters for the Windows platform. Parameters for the Mac OS and UNIX platforms are not yet defined at the time of publication.
Table 203 - Additional entries specific to a launch action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Launch for a launch action. |
| F | file specification | (Required if none of the entries Win , Mac , or Unix is present) The application that shall be launched or the document that shall be opened or printed. If this entry is absent and the conforming reader does not understand any of the alternative entries, it shall do nothing. |
| Win | dictionary | (Optional) A dictionary containing Windows-specific launch parameters (see Table 204). |
| Mac | (undefined) | (Optional) Mac OS-specific launch parameters; not yet defined. |
| Unix | (undefined) | (Optional) UNIX-specific launch parameters; not yet defined. |
| NewWindow | boolean | (Optional; PDF 1.2) A flag specifying whether to open the destination document in a new window. If this flag is false , the destination document replaces the current document in the same window. If this entry is absent, the conforming reader should behave in accordance with its current preference. This entry shall be ignored if the file designated by the F entry is not a PDF document. |
Table 204 - Entries in a Windows launch parameter dictionary
| Key | Type | Value |
|---|---|---|
| F | byte string | (Required) The file name of the application that shall be launched or the document that shall be opened or printed, in standard Windows pathname format. If the name string includes a backslash character (), the backslash shall itself be preceded by a backslash. This value shall be a simple string; it is not a file specification. |
Table 204 - Entries in a Windows launch parameter dictionary (continued)
| Key | Type | Value |
|---|---|---|
| D | byte string | (Optional) A bye string specifying the default directory in standard DOS syntax. |
| O | ASCII string | (Optional) An ASCII string specifying the operation to perform: open Open a document. print Print a document. If the F entry designates an application instead of a document, this entry shall be ignored and the application shall be launched. Default value: open. |
| P | byte string | (Optional) A parameter string that shall be passed to the application designated by the F entry. This entry shall be omitted if F designates a document. |
A thread action jumps to a specified bead on an article thread (see 12.4.3, 'Articles'), in either the current document or a different one. Table 205 shows the action dictionary entries specific to this type of action.
Table 205 - Additional entries specific to a thread action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Thread for a thread action. |
| F | file specification | (Optional) The file containing the thread. If this entry is absent, the thread is in the current file. |
| D | dictionary, integer, or text string | (Required) The destination thread, specified in one of the following forms: An indirect reference to a thread dictionary (see 12.4.3, 'Articles'). In this case, the thread shall be in the current file. The index of the thread within the Threads array of its document's Catalog (see 7.7.2, 'Document Catalog'). The first thread in the array has index 0. The title of the thread as specified in its thread information dictionary (see Table 160). If two or more threads have the same title, the one appearing first in the document Catalog's Threads array shall be used. |
| B | dictionary or integer | (Optional) The bead in the destination thread, specified in one of the following forms: An indirect reference to a bead dictionary (see 12.4.3, 'Articles'). In this case, the thread shall be in the current file. The index of the bead within its thread. The first bead in a thread has index 0. |
A uniform resource identifier (URI) is a string that identifies ( resolves to) a resource on the Internet-typically a file that is the destination of a hypertext link, although it may also resolve to a query or other entity. (URIs are described in Internet RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax ; see the Bibliography.)
A URI action causes a URI to be resolved. Table 206 shows the action dictionary entries specific to this type of action.
Table 206 - Additional entries specific to a URI action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be URI for a URI action. |
| URI | ASCII string | (Required) The uniform resource identifier to resolve, encoded in 7-bit ASCII. |
| IsMap | boolean | (Optional) A flag specifying whether to track the mouse position when the URI is resolved (see the discussion following this Table). Default value: false . This entry applies only to actions triggered by the user's clicking an annotation; it shall be ignored for actions associated with outline items or with a document's OpenAction entry. |
If the IsMap flag is true and the user has triggered the URI action by clicking an annotation, the coordinates of the mouse position at the time the action has been triggered shall be transformed from device space to user space and then offset relative to the upper-left corner of the annotation rectangle (that is, the value of the Rect entry in the annotation with which the URI action is associated).
EXAMPLE 1
If the mouse coordinates in user space are ( x m , y m ) and the annotation rectangle extends from ( ll x , ll y ) at the lower-left to ( ur x , ur y ) at the upper-right, the final coordinates ( x f , y f ) are as follows:
If the resulting coordinates ( x f , y f ) are fractional, they shall be rounded to the nearest integer values. They shall then be appended to the URI to be resolved, separated by COMMAS (2Ch) and preceded by a QUESTION MARK (3Fh), as shown in this example:
EXAMPLE 2 http : / / www . adobe . com / intro ?100 , 200
NOTE 1 To support URI actions, a PDF document's Catalog (see 7.7.2, 'Document Catalog') may include a URI entry whose value is a URI dictionary . Only one entry shall be defined for such a dictionary (see Table 207).
| Key | Type | Value |
|---|---|---|
| Base | ASCII string | (Optional) The base URI that shall be used in resolving relative URI references. URI actions within the document may specify URIs in partial form, to be interpreted relative to this base address. If no base URI is specified, such partial URIs shall be interpreted relative to the location of the document itself. The use of this entry is parallel to that of the body element , as described in the HTML 4.01 Specification (see the Bibliography). |
NOTE 2 The Base entry allows the URI of the document to be recorded in situations in which the document may be accessed out of context. For example, if a document has been moved to a new location but contains relative links to other documents that have not been moved, the Base entry could be used to refer such links to the true location of the other documents, rather than that of the moved document.
A sound action (PDF 1.2) plays a sound through the computer's speakers. Table 208 shows the action dictionary entries specific to this type of action. Sounds are discussed in 13.3, 'Sounds.'
Table 208 - Additional entries specific to a sound action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Sound for a sound action. |
| Sound | stream | (Required) A sound object defining the sound that shall be played (see 13.3, 'Sounds'). |
| Volume | number | (Optional) The volume at which to play the sound, in the range - 1.0 to 1.0. Default value: 1.0. |
| Synchronous | boolean | (Optional) A flag specifying whether to play the sound synchronously or asynchronously. If this flag is true , the conforming reader retains control, allowing no further user interaction other than canceling the sound, until the sound has been completely played. Default value: false . |
| Repeat | boolean | (Optional) A flag specifying whether to repeat the sound indefinitely. If this entry is present, the Synchronous entry shall be ignored. Default value: false . |
| Mix | boolean | (Optional) A flag specifying whether to mix this sound with any other sound already playing. If this flag is false , any previously playing sound shall be stopped before starting this sound; this can be used to stop a repeating sound (see Repeat ). Default value: false . |
A movie action (PDF 1.2) can be used to play a movie in a floating window or within the annotation rectangle of a movie annotation (see 12.5.6.17, 'Movie Annotations' and 13.4, 'Movies'). The movie annotation shall be associated with the page that is the destination of the link annotation or outline item containing the movie action, or with the page object with which the action is associated.
NOTE A movie action by itself does not guarantee that the page the movie is on will be displayed before attempting to play the movie; such page change actions shall be done explicitly.
The contents of a movie action dictionary are identical to those of a movie activation dictionary (see Table 296), with the additional entries shown in Table 209. The contents of the activation dictionary associated with the movie annotation provide the default values. Any information specified in the movie action dictionary overrides these values.
Table 209 - Additional entries specific to a movie action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Movie for a movie action. |
| Annotation | dictionary | (Optional) An indirect reference to a movie annotation identifying the movie that shall be played. |
| T | text string | (Optional) The title of a movie annotation identifying the movie that shall be played. The dictionary shall include either an Annotation or a T entry but not both. |
Table 209 - Additional entries specific to a movie action (continued)
| Key | Type | Value |
|---|---|---|
| Operation | name | (Optional) The operation that shall be performed on the movie: PlayStart playing the movie, using the play mode specified by the dictionary's Mode entry (see Table 296). If the movie is currently paused, it shall be repositioned to the beginning before playing (or to the starting point specified by the dictionary's Start entry, if present). Stop Stop playing the movie. Pause Pause a playing movie. Resume Resume a paused movie. Default value: Play. |
A hide action (PDF 1.2) hides or shows one or more annotations on the screen by setting or clearing their Hidden flags (see 12.5.3, 'Annotation Flags'). This type of action can be used in combination with appearance streams and trigger events (Sections 12.5.5, 'Appearance Streams,' and 12.6.3, 'Trigger Events') to display pop-up help information on the screen.
NOTE
The E (enter) and X (exit) trigger events in an annotation's additional-actions dictionary can be used to show and hide the annotation when the user rolls the cursor in and out of its active area on the page. This can be used to pop up a help label, or tool tip, describing the effect of clicking at that location on the page.
Table 210 shows the action dictionary entries specific to this type of action.
Table 210 - Additional entries specific to a hide action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Hide for a hide action. |
| T | dictionary, text string, or array | (Required) The annotation or annotations to be hidden or shown, shall be specified in any of the following forms: An indirect reference to an annotation dictionary A text string giving the fully qualified field name of an interactive form field whose associated widget annotation or annotations are to be affected (see 12.7.3.2, 'Field Names') An array of such dictionaries or text strings |
| H | boolean | (Optional) A flag indicating whether to hide the annotation ( true ) or show it ( false ). Default value: true . |
Table 211 lists several named actions (PDF 1.2) that conforming readers shall support; further names may be added in the future.
Table 211 - Named actions
| Name | Action |
|---|---|
| NextPage | Go to the next page of the document. |
| PrevPage | Go to the previous page of the document. |
| FirstPage | Go to the first page of the document. |
| LastPage | Go to the last page of the document. |
NOTE Conforming readers may support additional, nonstandard named actions, but any document using them is not portable. If the viewer encounters a named action that is inappropriate for a viewing platform, or if the viewer does not recognize the name, it shall take no action.
Table 212 shows the action dictionary entries specific to named actions.
Table 212 - Additional entries specific to named actions
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Named for a named action. |
| N | name | (Required) The name of the action that shall be performed (see Table 211). |
A set-OCG-state action (PDF 1.5) sets the state of one or more optional content groups (see 8.11, 'Optional Content'). Table 213 shows the action dictionary entries specific to this type of action.
Table 213 - Additional entries specific to a set-OCG-state action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be SetOCGState for a set-OCG-state action. |
| State | array | (Required) An array consisting of any number of sequences beginning with a name object ( ON , OFF , or Toggle ) followed by one or more optional content group dictionaries. The array elements shall be processed from left to right; each name shall be applied to the subsequent groups until the next name is encountered: ON sets the state of subsequent groups to ON OFF sets the state of subsequent groups to OFF Toggle reverses the state of subsequent groups. |
| PreserveRB | boolean | (Optional) If true , indicates that radio-button state relationships between optional content groups (as specified by the RBGroups entry in the current configuration dictionary; see Table 101) should be preserved when the states in the State array are applied. That is, if a group is set to ON (either by ON or Toggle ) during processing of the State array, any other groups belonging to the same radio-button group shall be turned OFF . If a group is set to OFF , there is no effect on other groups. If PreserveRB is false , radio-button state relationships, if any, shall be ignored. Default value: true . |
When a set-OCG-state action is performed, the State array shall be processed from left to right. Each name shall be applied to subsequent groups in the array until the next name is encountered, as shown in the following example.
EXAMPLE 1 << /S /SetOCGState /State [/OFF 2 0 R 3 0 R /Toggle 16 0 R 19 0 R /ON 5 0 R] >>
A group may appear more than once in the State array; its state shall be set each time it is encountered, based on the most recent name. ON , OFF and Toggle sequences have no required order. More than one sequence in the array may contain the same name.
EXAMPLE 2 If the array contained [/OFF 1 0 R /Toggle 1 0 R], the group's state would be ON after the action was performed.
- NOTE While the specification allows a group to appear more than once in the State array, this is not intended to implement animation or any other sequential drawing operations. PDF processing applications are free to accumulate all state changes and apply only the net changes simultaneously to all affected groups before redrawing.
A rendition action (PDF 1.5) controls the playing of multimedia content (see 13.2, 'Multimedia'). This action may be used in the following ways:
- To begin the playing of a rendition object (see 13.2.3, 'Renditions'), associating it with a screen annotation (see 12.5.6.18, 'Screen Annotations'). The screen annotation specifies where the rendition shall be played unless otherwise specified.
- To stop, pause, or resume a playing rendition.
- To trigger the execution of a JavaScript script that may perform custom operations.
Table 214 lists the entries in a rendition action dictionary.
Table 214 - Additional entries specific to a rendition action
| Key | Type | Value |
|---|
Navigation: PDF-Spec-12-Annotations | PDF-Spec-Index | PDF-Spec-12-Forms