/ 
PDF-Builder-3.012
River stage one • 2 direct dependents • 2 total dependents
/ PDF::Builder::Annotation

NAME

PDF::Builder::Annotation - Add annotations to a PDF

METHODS

Note that the handling of annotations can vary from Reader to Reader. The available icon set may be larger or smaller than given here, and some Readers activate an annotation on a single mouse click, while others require a double click. Not all features provided here may be available on all PDF Readers.

$ant = PDF::Builder::Annotation->new()

Returns an annotation object (called from $page->annotation()).

Annotation types

$ant->link($page, %opts)
$ant->link($page)

Defines the annotation as a launch-page with page $page (within this document) and options %opts (-rect, -border, fit, -color (border's)).

$ant->url($url, %opts)
$ant->url($url)

Defines the annotation as a launch-url with url $url and options %opts (-rect, -border, and -color (border's)).

$ant->file($file, %opts)
$ant->file($file)

Defines the annotation as a launch-file with filepath $file and options %opts (-rect, -border, and -color (border's)).

$ant->pdf_file($pdffile, $pagenum, %opts)
$ant->pdf_file($pdffile, $pagenum)

Defines the annotation as a PDF-file with filepath $pdffile, on page $pagenum, and options %opts (-rect, -border, fit, and -color (border's)).

The old name, pdfile, is still available but is deprecated and will be removed at some time in the future.

$ant->text($text, %opts)
$ant->text($text)

Defines the annotation as a text note with content string $text and options %opts (-rect, -border, -color (border's), and -open).

Additional options:

-icon => name_string
-icon => reference

Specify the icon to be used. The default is Reader-specific (usually Note), and others may be defined by the Reader. Comment, Key, Help, NewParagraph, Paragraph, and Insert are also supposed to be available on all PDF Readers. Note that the name case must exactly match. The icon is of fixed size. Any AP dictionary entry will override the -icon setting.

A reference to an icon may be passed instead of a name.

$ant->movie($file, $contentType, %opts)
$ant->movie($file, $contentType)

Defines the annotation as a movie from $file with $contentType and options %opts (-rect, -border, -color (border's)).

$ant->file_attachment($file, %opts)

Defines the annotation as a file attachment with file $file and options %opts.

The file, along with its name, is embedded in the PDF document and may be extracted for viewing with the appropriate viewer.

This differs from the file method in that file looks for and launches a file already on the Reader's machine, while file_attachment embeds the file in the PDF, and makes it available on the Reader's machine for actions of the user's choosing.

Note 1: some Readers may only permit an "open" action, and may also restrict file types (extensions) that will be handled. This may be configurable with your Reader's security settings.

Note 2: the displayed file name (pop-up during mouse rollover of the target rectangle) is given with the path trimmed off (file name only). If you want the displayed name to exactly match the path that was passed to the call, including the path, give the -notrimpath option.

Options:

-icon => name_string
-icon => reference

Specify the icon to be used. The default is Reader-specific (usually PushPin), and others may be defined by the Reader. Paperclip, Graph, and Tag are also supposed to be available on all PDF Readers. Note that the name case must exactly match. None is a custom invisible icon defined by PDF::Builder. The icon is stretched to fill the defined target rectangle. Any AP dictionary entry will override the -icon setting.

A reference to an icon may be passed instead of a name.

-notrimpath => 1

If given, show the entire path and file name on mouse rollover, rather than just the file name.

Internal routines and common options

$ant->rect($llx,$lly, $urx,$ury)

Sets the rectangle (active click area) of the annotation, given by -rect option. This is any pair of diagonally opposite corners of the rectangle.

The default clickable area is the icon itself.

Defining option. Note that this "option" is actually required.

-rect => [LLx LLy URx URy]

Set annotation rectangle at [LLx,LLy] to [URx,URy] (lower left and upper right coordinates). LL to UR is customary, but any diagonal is allowed.

$ant->border(@b)

Sets the border-style of the annotation, if applicable, as given by the -border option. There are three entries in the array: horizontal and vertical corner radii, and border width.

The default is [0 0 1] (solid line of width 1, sharp corners).

Defining option:

-border => [CRh CRv W]

Set annotation border style of horizontal and vertical corner radii CRh and CRv (value 0 for squared corners) and width W (value 0 for no border). The default is squared corners and a solid line of width 1 ([0 0 1]).

The border vector seems to ignore the first two settings (corner radii), but the line thickness works, on basic Readers. The radii may work on some other Readers.

$ant->content($text)

Sets the text-content of the text() annotation. This is a text string.

$ant->open($bool)

Display the text() annotation either open or closed, if applicable.

Both are editable; the "open" form brings up the page with the entry area already open for editing, while "closed" has to be clicked on to edit it.

Defining option:

-open => boolean

If true (1), the annotation will be marked as initially "open". If false (0), or the option is not given, the annotation is initially "closed".

$ant->dest($page, fit_setting)

For certain annotation types (link or pdf_file), the fit_setting specifies how the content of the page $page is to be fit to the window, while preserving its aspect ratio. These options are:

-fit => 1

Display the page with its contents magnified just enough to fit the entire page within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the page within the window in the other dimension.

-fith => $top

Display the page with the vertical coordinate $top positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of the page within the window.

-fitv => $left

Display the page with the horizontal coordinate $left positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of the page within the window.

-fitr => [$left, $bottom, $right, $top]

Display the page with its contents magnified just enough to fit the rectangle specified by the coordinates $left, $bottom, $right, and $top entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the rectangle within the window in the other dimension.

-fitb => 1

Display the page with its contents magnified just enough to fit its bounding box entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the bounding box within the window in the other dimension.

-fitbh => $top

Display the page with the vertical coordinate $top positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of its bounding box within the window.

-fitbv => $left

Display the page with the horizontal coordinate $left positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of its bounding box within the window.

-xyz => [$left, $top, $zoom]

Display the page with the coordinates [$left, $top] positioned at the top-left corner of the window and the contents of the page magnified by the factor $zoom. A zero (0) value for any of the parameters $left, $top, or $zoom specifies that the current value of that parameter is to be retained unchanged.

This is the default fit setting, with position (left and top) and zoom the same as the calling page's.

$ant->dest($name)

Connect the Annotation to a "Named Destination" defined elsewhere.

$ant->Color(@color)

Set the icon's fill color. The color is an array of 1, 3, or 4 numbers, each in the range 0.0 to 1.0. If 1 number is given, it is the grayscale value (0 = black to 1 = white). If 3 numbers are given, it is an RGB color value. If 4 numbers are given, it is a CMYK color value.

For link and url annotations, this is the color of the rectangle border (-border given with a width of at least 1).

If an invalid array length or numeric value is given, a medium gray ( [0.5] ) value is used, without any message. If no color is given, the usual fill color is black.

Defining option:

-color => [ g ]

If g is between 0.0 (black) and 1.0 (white), the fill color will be gray.

-color => [ r, g, b ]

If r (red), g (green), and b (blue) are all between 0.0 and 1.0, the fill color will be the defined RGB hue. [ 0, 0, 0 ] is black, [ 1, 1, 0 ] is yellow, and [ 1, 1, 1 ] is white.

-color => [ c, m, y, k ]

If c (red), m (magenta), y (yellow), and k (black) are all between 0.0 and 1.0, the fill color will be the defined CMYK hue. [ 0, 0, 0, 0 ] is white, [ 1, 0, 1, 0 ] is green, and [ 1, 1, 1, 1 ] is black.

-text => string

Specify an optional text label for annotation. This text or comment only shows up in the pop-up containing the file or text, when the mouse is rolled over the target rectangle. It does not normally show for link, url, etc. annotations.