Beyond its printed look, a PDF can hold things a viewer acts on: notes and links (PDF 1.0), actions that open other files and web addresses (1.1), forms, sounds and movies (1.2), JavaScript, digital signatures, embedded files and a set of markup annotations (1.3), and more of each in 1.4. Most of them are annotations, objects tied to a rectangle on a page.
Annotations
A page’s Annots array lists its annotations. Each is a dictionary
with these keys, and more for its type:
| Key | Since | Meaning |
|---|---|---|
Type | 1.0 | Annot, optional |
Subtype | 1.0 | Required: the type |
Rect | 1.0 | Required: where it is on the page, in default user space |
Contents | 1.0 | Its text, or a description for a non-text annotation |
P | 1.3 | The page it is on |
NM | 1.4 | A name unique on the page |
M | 1.1 | When it was last changed |
F | 1.1 | The flags; default 0 |
AP | 1.2 | The appearance streams |
AS | 1.2 | The current appearance state, such as /Off or /Yes |
Border | 1.0 | The border: corner radii and width, default [0 0 1], and an optional dash array |
C | 1.1 | Its colour: 0, 1, 3 or 4 numbers, for none, grey, RGB or CMYK |
T | 1.1 | The author, for markup annotations |
Popup | 1.3 | The pop-up annotation that shows its text |
CA | 1.4 | The opacity; default 1 |
StructParent | 1.3 | Its place in the logical structure |
Annotation types
| Subtype | Since | What it is |
|---|---|---|
Text | 1.0 | A note: an icon that opens to show text (Open, Name for the icon) |
Link | 1.0 | A hypertext link: Dest, or A (1.1), and H (1.2) for how to highlight it when clicked |
Sound | 1.2 | A sound to play |
Movie | 1.2 | A movie to play |
Widget | 1.2 | A form field’s visible part |
FreeText | 1.3 | Text written straight on the page, with DA for its font and colour |
Line | 1.3 | A straight line, L |
Square, Circle | 1.3 | A rectangle or an ellipse inside Rect |
Highlight, Underline, StrikeOut | 1.3 | Text markup over the areas in QuadPoints |
Squiggly | 1.4 | Text markup with a wavy underline |
Stamp | 1.3 | A rubber stamp such as Approved or Draft |
Ink | 1.3 | Freehand strokes, InkList |
Popup | 1.3 | The window that shows another annotation’s text |
FileAttachment | 1.3 | An icon holding an embedded file, FS |
TrapNet | 1.3 | Trapping for printing |
PrinterMark | 1.4 | Registration marks, colour bars and cut marks for printing |
Annotation flags
| Bit | Name | Since | Meaning |
|---|---|---|---|
| 1 | Invisible | 1.1 | An unknown type is not shown |
| 2 | Hidden | 1.2 | Not shown or printed |
| 3 | 1.2 | Printed when the page is printed | |
| 4 | NoZoom | 1.3 | Stays the same size when the page is zoomed |
| 5 | NoRotate | 1.3 | Does not turn with the page |
| 6 | NoView | 1.3 | Not shown on screen, but may be printed |
| 7 | ReadOnly | 1.3 | Cannot be changed or interacted with |
| 8 | Locked | 1.4 | Cannot be moved or deleted |
Appearance streams
From PDF 1.2 an annotation can say exactly how it looks with AP, a
dictionary of up to three appearances, each a form XObject drawn into
Rect:
| Key | Appearance |
|---|---|
N | Required: normal |
R | Rollover, when the pointer is over it |
D | Down, when it is pressed |
Each may be a stream, or a dictionary of streams by state, for check boxes and
radio buttons: /N << /Yes 12 0 R /Off 13 0 R >>, with
AS choosing the current one. Without appearance streams, the viewer
draws the annotation itself from its other keys, and different viewers draw it
differently.
Actions
From PDF 1.1 an action is a dictionary with /Type /Action (optional),
S for its type, and from PDF 1.2 Next, an action or array
of actions to run after it. Links, outline items, the catalog’s
OpenAction and the additional-actions dictionaries
(AA) of pages, annotations, fields and, from 1.4, the document all
use them.
| S | Since | What it does |
|---|---|---|
GoTo | 1.1 | Go to a destination, D, in this document |
GoToR | 1.1 | Go to a destination in another PDF, F, optionally in a new window |
Launch | 1.1 | Open or print another file, or run a program |
Thread | 1.1 | Start reading an article thread |
URI | 1.1 | Open a web address, URI, an ASCII string |
Sound | 1.2 | Play a sound |
Movie | 1.2 | Play a movie |
Hide | 1.2 | Show or hide annotations or fields |
Named | 1.2 | Run a viewer command: NextPage, PrevPage, FirstPage, LastPage, and others a viewer may add |
SubmitForm | 1.2 | Send form fields to a URL, as FDF, HTML form data or, from 1.4, XFDF or the whole PDF |
ResetForm | 1.2 | Set fields back to their defaults |
ImportData | 1.2 | Fill fields from an FDF file |
JavaScript | 1.3 | Run JavaScript |
Two more types, SetState and NOP, belong to Acrobat 2.1
and are obsolete. A reader meets them only in very old files and can ignore
them.
<< /Type /Annot /Subtype /Link /Rect [72 700 200 714] /Border [0 0 0]
/A << /S /URI /URI (https://example.org/) >> >>JavaScript
From PDF 1.3 an action can be /S /JavaScript with JS, a
text string or a stream of code. It runs in the viewer, with Acrobat’s object model
for the document, its fields and pages. Scripts are found in the
JavaScript name tree (run when the document opens), in field actions
(keystroke, format, validate and calculate, in the field’s AA), in page
and document actions, and in links. Viewers other than Acrobat run little or none of
it, and many security tools treat it as a warning sign.
Interactive forms
From PDF 1.2 the catalog’s AcroForm dictionary holds the document’s
form fields:
| Key | Since | Meaning |
|---|---|---|
Fields | 1.2 | Required: the top-level fields |
NeedAppearances | 1.2 | true asks the viewer to make the fields’ appearance streams itself; default false |
SigFlags | 1.3 | Bit 1 SignaturesExist, bit 2 AppendOnly: save changes only as incremental updates, so as not to break signatures |
CO | 1.3 | The fields to recalculate, in order |
DR | 1.2 | Default resources, such as fonts, for field appearances |
DA | 1.2 | The default appearance string for text: (/Helv 0 Tf 0 g) |
Q | 1.2 | The default alignment: 0 left, 1 centre, 2 right |
Fields
Fields form a tree. A field’s full name is its own T joined to its
parents’ with full stops, such as address.city. A terminal field has
one or more widget annotations, often merged into the same dictionary.
| Key | Since | Meaning |
|---|---|---|
FT | 1.2 | The type: Btn button, Tx text, Ch choice, Sig signature (1.3); inheritable |
Parent, Kids | 1.2 | The tree |
T | 1.2 | The partial name |
TU | 1.3 | A name to show to people, as a tool tip |
TM | 1.3 | The name to use when exporting |
Ff | 1.2 | Field flags, below |
V, DV | 1.2 | The value and the default value |
AA | 1.3 | Actions: keystroke, format, validate, calculate |
DA, Q | 1.2 | For text: the appearance string and alignment |
MaxLen | 1.2 | For text: the most characters allowed |
Opt | 1.2 | For choices: the options, strings or pairs of export value and text |
TI, I | 1.2, 1.4 | For lists: the top index shown, and the selected indices |
| Ff bit | For | Name | Since |
|---|---|---|---|
| 1 | all | ReadOnly | 1.2 |
| 2 | all | Required | 1.2 |
| 3 | all | NoExport | 1.2 |
| 13 | text | Multiline | 1.2 |
| 14 | text | Password | 1.2 |
| 15 | button | NoToggleToOff (radio buttons) | 1.2 |
| 16 | button | Radio | 1.2 |
| 17 | button | Pushbutton | 1.2 |
| 18 | choice | Combo: a drop-down, not a list | 1.2 |
| 19 | choice | Edit: the combo box takes typed text | 1.2 |
| 20 | choice | Sort | 1.2 |
| 21 | text | FileSelect: the value is a file name | 1.4 |
| 22 | choice | MultiSelect | 1.4 |
| 23 | text, choice | DoNotSpellCheck | 1.4 |
| 24 | text | DoNotScroll | 1.4 |
A button with neither Radio nor Pushbutton set is a check box. Its value is the name
of its on state, such as /Yes, or /Off.
Digital signatures
From PDF 1.3 a signature field (/FT /Sig) holds in V a
signature dictionary:
| Key | Meaning |
|---|---|
Type | Sig, optional |
Filter | Required: the preferred signature handler, such as Adobe.PPKLite |
SubFilter | The encoding of the signature: adbe.x509.rsa_sha1, adbe.pkcs7.detached or adbe.pkcs7.sha1 |
Contents | Required: the signature, a hexadecimal string, padded with zeros to the space reserved |
Cert | For adbe.x509.rsa_sha1: the signer’s certificate chain |
ByteRange | The bytes of the file that are signed: pairs of offset and length |
Name, M, Location, Reason | The signer, the time of signing, where and why |
ByteRange is usually [0 a b c]: the whole file except the
Contents string, which lies between byte a and byte
b. To check a signature, a reader hashes those two ranges and compares the
result with the one in Contents. A document signed again gets an
incremental update, so each signature still covers the bytes as they were.
Embedded files
A file specification names a file. In its simple form it is a string, a path relative to the PDF; from PDF 1.1 it may be a dictionary, and from PDF 1.3 that dictionary can hold the file itself:
| Key | Since | Meaning |
|---|---|---|
Type | 1.3 | Filespec |
FS | 1.1 | The file system, such as URL |
F | 1.1 | The file name, in a portable form with / between parts |
DOS, Mac, Unix | 1.1 | Platform-specific file names |
ID | 1.1 | The two strings of the other file’s ID |
V | 1.2 | true if the file changes often, so a viewer should not cache it |
EF | 1.3 | The embedded file streams, by key: /EF << /F 20 0 R >> |
RF | 1.3 | Related files, for a file in several parts |
An embedded file stream has /Type /EmbeddedFile, an optional
Subtype with the MIME type (such as /text#2Fplain), and
Params: Size, CreationDate,
ModDate, Mac (type and creator) and CheckSum
(an MD5 digest of the file). The stream data is the file, usually Flate-compressed.
Files are attached to a page with a FileAttachment annotation (1.3), or
to the document through the EmbeddedFiles name tree (1.4).