Adobe PDF Library

Working with Annotations

Both Adobe Reader and Adobe Acrobat allow users to add text to a PDF file.  Within the free Adobe Reader you can add notes and highlight text.  With Adobe Acrobat you can make a variety of changes, including the following:

  • add notes and highlights
  • add, cross out, or delete text
  • attach a file
  • add a callout box to add text
  • add images or stamps

When you save the PDF file these changes, called annotations, are added to the file.


View Sample Code

This sample demonstrates how to copy and paste annotations from one PDF file to another.

The program provides two optional input PDF documents. The first is the source of the annotations, and the second is the PDF document that receives these copied annotations. The program also provides a default name and path for the output PDF document. The second input document, Layers.pdf, is saved as the output document Paste-out.pdf.

You can provide your own file names for these values in the code, or you can enter your own file names as command line parameters.


View Sample Code

The purpose of this sample program is to show how to write code that will find and describe an annotation in a PDF file.

When you run Annotations, the program provides an optional input PDF document. You can enter your own file name in the code, or you can enter the file name as a command line parameter.

If the PDF file that you provide has any annotations, the program will identify the first annotation on the first page of the PDF file and display a brief description on the command screen, with the name of the author of the file:

Input file: Samples/Data/sample_annotations.PDF


View Sample Code

When you create a PDF file you can add hyperlinks that will move the reader to another part of the same document, or open a different document or a web page.  Normally this link text appears in blue, like this:


You can use the ChangeLinkColors program code to change the color of a hyperlink in a PDF file.  The program takes the hyperlinks found in the file Sample_links.PDF, updates the color, and saves the results to Change_link_colors_out.PDF.

The program works by identifying text in a PDF file that is associated with hyperlinks.  Each link appears as a rectangle layer in the PDF file; ChangeLinkColors identifies these rectangles, and then finds the text that lines up within these rectangles and changes the color of each character that is a part of the hyperlink.  In the sample PDF files, the hyperlink changes from this:


To this:


The sample program assumes that the PDF file used will have horizontal text, reading from left to right.

When you run the program from a command line, it will respond every time it finds a “text object” or a letter, and identify each LinkAnnotation.  A LinkAnnotation is a hyperlink embedded in the document.

The program starts by creating a list of all of the link annotations, or hyperlinks found on each page. Then it looks for text objects associated with these link annotations, working recursively to make sure any text objects are found that are in nested content.

Then, the program identifies the individual characters that are associated with the text attached to each hyperlink. It checks each character in the text one character at a time, looking for the first character that interacts with the link annotation, and continuing to check each character in sequence until the last character in the link is found. Each character is checked to determine if it intersects the rectangle defined by the link annotation.

The text characters associated with the link annotation are identified as being a part of a TextRun, a sequence of characters that share a single property. The program splits the TextRun at each character that is not the first character in the sequence, and then notes the new index entry of the character in the TextRun. This includes every character in the sequence except for the first character. Then, the program changes the GraphicState for all of the characters associated with TextRuns associated with the LinkAnnotation rectangles in the document.

The Graphics State is an internal data structure in a PDF file that holds the parameters that describe graphics within that file. These parameters define how individual graphics are presented on the page. Adobe Systems introduced the Extended Graphic State to expand the original Graphics State data structure, providing space to define and store more data objects within a PDF.


View Sample Code

The sample program shows how to add an annotation to a PDF file that features a flash video embedded under an image.  In this example the output file is a PDF page that features a photograph of a cabin.  But a hyperlink is embedded in the photograph; if you click on the photograph, a brief flash video starts.  The program identifies the PDF file to import and the source of the flash video, and then creates a new PDF document with space for the flash annotation.

Within the sample program the size of the annotation space is set up to be the right size to display the flash video, and to fit within the borders or the photograph.  The program will create the appearance for the flash annotation and the action.  The appearance is what is shown before the reader clicks on the image to start the flash video.  The flash action describes the video itself; the action describes what to do to play the flash video file.


View Sample Code

If you are working with a PDF file and Adobe Acrobat on a Tablet PC, or on a Windows workstation with a stylus or pen input device installed, you can add ink annotations to a PDF file.  With ink annotations you can work with a document displayed on a screen just as you would on paper, such as making notes in the margins, circling or underlining sections, or crossing things out.

Use this sample program to add ink annotations to a PDF file page.  To be more specific, you can use the InkAnnotations sample code to add a Bezier curve to a PDF file.  A Bezier curve is a freeform polygon, used to model smooth curves that can be scaled without limit.  Bezier curves have a variety of uses when creating graphic designs.  In this sample the program generates the Bezier curve based on mathematical coordinates.

When the program runs it generates a PDF file with an irregular shape applied to the top of a blank page.


Note that the InkAnnotations sample program is not taking an annotation that already appears on an existing PDF file and copying it to another PDF file.  Rather, it is creating a new annotation and adding it to a new PDF file.


View Sample Code

This program creates a PDF file with an embedded hyperlink.  In this case, the hyperlink takes you to the second page of the document, and is found in the lower left corner of the first page, over the number “1” in “1 of 2.”

The coordinates in the program define the rectangle holding the hyperlink as quite small:

The new destination rectangle: [ LLx=0, LLy=-1.#INF, URx=-1.#INF, URy=200 ]

So you need to zoom in to about 600% to see the hyperlink rectangle:


You can of course edit the coordinates to make the hyperlink as large as you need it to be, and place it anywhere on the page. The command prompt displays the settings for the annotation when you run the program:

LinkAnnotations Sample:
Initialized the library.
Opened a documentsamples/Data/sample.PDF
Current Link Annotation version = 1.2
New Link Annotation version = 1
The new destination rectangle: [ LLx=0, LLy=-1.#INF, URx=-1.#INF, URy=200 ]
The new fit type: FitV
The new zoom level: -Infinity
The new page number: 1


View Sample Code

This program generates a PDF output file with a polygon shape—a triangle—as an annotation to the file.  The program defines the vertices for the outlines of the annotation, and the line and fill colors.


View Sample Code

This program generates a PDF output file with a line shape—an angle—as an annotation to the file. The program defines the vertices for the outlines of the annotation, and the line and fill colors.


View Sample Code

This program shows how to add annotations to an existing PDF file that will highlight and underline words.  When you run it, the program generates a PDF output file. The output sample here will annotate a PDF file showing a National Weather Service web page, highlighting the word “Cloudy” wherever it appears and underlining the word “Rain.”