oracular (3) PDF::Builder::Annotation.3pm.gz
NAME
PDF::Builder::Annotation - Add annotations to a PDF
SYNOPSIS
my $pdf = PDF::Builder->new();
my $font = $pdf->font('Helvetica');
my $page1 = $pdf->page();
my $page2 = $pdf->page();
my $content = $page1->text();
my $message = 'Go to Page 2';
my $size = 18;
$content->distance(1 * 72, 9 * 72);
$content->font($font, $size);
$content->text($message);
my $annotation = $page1->annotation();
my $width = $content->text_width($message);
$annotation->rect(1 * 72, 9 * 72, 1 * 72 + $width, 9 * 72 + $size);
$annotation->link($page2);
$pdf->save('sample.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.
new
$annotation = PDF::Builder::Annotation->new()
Returns an annotation object (called from $page->annotation()).
It is normally not necessary to explicitly call this method (see examples).
Annotation types
link
$annotation->link($page, %opts)
Defines the annotation as a launch-page with page $page (within this document) and opts %opts (rect,
border, color, fit: see descriptions below).
Note that $page is not a simple page number, but is a page structure such as
"$pdf->openpage(page_number)", or a Named Destination defined elsewhere.
pdf, pdfile, pdf_file
$annotation->pdf($pdffile, $page_number, %opts)
Defines the annotation as a PDF-file with filepath $pdffile, on page $page_number, and opts %opts
(rect, border, color, fit: see descriptions below). This differs from the "link" call in that the
target is found in a different PDF file, not the current document.
$page_number is the physical page number, starting at 1: 1, 2,...
Alternate names: "pdfile" and "pdf_file"
Originally this method was named "pdfile", and then "pdf_file" but a recent PDF::API2 change made it
"pdf". For compatibility, it has been changed to "pdf", with "pdfile" and "pdf_file" still available
as aliases.
launch, file
$annotation->launch($file, %opts)
Defines the annotation as a launch-file with filepath $file (a local file) and options %opts (rect,
border, color: see descriptions below). How the file is displayed depends on the operating system,
type of file, and local configuration or mapping.
Alternate name: "file"
Originally this method was named "file", but a recent PDF::API2 change made it "launch". For
compatibility, it has been changed to "launch", with "file" still available as an alias.
uri, url
$annotation->uri($url, %opts)
Defines the annotation as a launch-url with url $url and options %opts (rect, border, color: see
descriptions below). This page is usually brought up in a browser, and may be remote.
Alternate name: "url"
Originally this method was named "url", but a recent PDF::API2 change made it "uri". For
compatibility, it has been changed to "uri", with "url" still available as an alias.
text
$annotation->text($text, %opts)
Defines the annotation as a text note with content string $text and options %opts (rect, color, text,
open: see descriptions below). The $text may include newlines \n for multiple lines. The option
border is ignored, since an icon is used.
The option "text" is the popup's label string, not to be confused with the main $text.
The icon appears in the upper left corner of the "rect" selection rectangle, and its active clickable
area is fixed by the icon (it is not equal to the rectangle). The icon size is fixed, and its fill
color set by "color".
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.
opacity => value
Define the opacity (non-transparency, opaqueness) of the icon. This value ranges from 0.0
(transparent) to 1.0 (fully opaque), and applies to both the outline and the fill color. The default
is 1.0.
markup
$annotation->markup($text, $PointList, $highlight, %opts)
Defines the annotation as a text note with content string $text and options %opts (color, text, open,
opacity: see descriptions below). The $text may include newlines \n for multiple lines.
"text" is the popup's label string, not to be confused with the main $text.
There is no icon. Instead, the annotated text marked by $PointList is highlighted in one of four ways
specified by $highlight.
$PointList => [ 8n numbers ]
One or more sets of numeric coordinates are given, defining the quadrilateral (usually a rectangle)
around the text to be highlighted and selectable (clickable, to bring up the annotation text). These
are four sets of "x,y" coordinates, given (for Left-to-Right text) as the upper bound Upper Left to
Upper Right and then the lower bound Lower Left to Lower Right. Note that this is different from what
is (erroneously) documented in the PDF specification! It is important that the coordinates be given
in this order.
Multiple sets of quadrilateral corners may be given, such as for highlighted text that wraps around
to new line(s). The minimum is one set (8 numbers). Any AP dictionary entry will override the
$PointList setting. Finally, the "Rect" selection rectangle is created just outside the convex
bounding box defined by $PointList.
$highlight => 'string'
The following highlighting effects are permitted. The "string" must be spelled and capitalized
exactly as given:
Highlight
The effect of a translucent "highlighter" marker.
Squiggly
The effect is an underline written in a "squiggly" manner.
StrikeOut
The text is struck-through with a straight line.
Underline
The text is marked by a straight underline.
color => array of values
If "color" is not given (an array of numbers in the range 0.0-1.0), a medium gray should be used by
default. Named colors are not supported at this time.
opacity => value
Define the opacity (non-transparency, opaqueness) of the icon. This value ranges from 0.0
(transparent) to 1.0 (fully opaque), and applies to both the outline and the fill color. The default
is 1.0.
movie
$annotation->movie($file, $contentType, %opts)
Defines the annotation as a movie from $file with content (MIME) type $contentType and options %opts
(rect, border, color, text: see descriptions below).
The "rect" rectangle also serves as the area where the movie is played, so it should be of usable
size and aspect ratio. It does not use a separate popup player. It is known to play .avi and .wav
files -- others have not been tested. Using Adobe Reader, it will not play .mpg files (unsupported
type). More work is probably needed on this annotation method.
file_attachment
$annotation->file_attachment($file, %opts)
Defines the annotation as a file attachment with file $file and options %opts (rect, color: see
descriptions below). Note that "color" applies to the icon fill color, not to a selectable area
outline. The icon is resized (including aspect ratio changes) based on the selectable rectangle given
by "rect", so watch your rectangle dimensions!
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/squashed to fill the defined target rectangle, so take care when
defining "rect" dimensions. Any AP dictionary entry will override the icon setting.
A reference to an icon may be passed instead of a name.
opacity => value
Define the opacity (non-transparency, opaqueness) of the icon. This value ranges from 0.0
(transparent) to 1.0 (fully opaque), and applies to both the outline and the fill color. The default
is 1.0.
notrimpath => 1
If given, show the entire path and file name on mouse rollover, rather than just the file name.
text => string
A text label for the popup (on mouseover) that contains the file name.
Note that while PDF permits different specifications (paths) to DOS/Windows, Mac, and Unix (including
Linux) versions of a file, and different format copies to be embedded, at this time PDF::Builder only
permits a single file (format of your choice) to be embedded. If there is user demand for multiple file
formats to be referenced and/or embedded, we could look into providing this, although separate OS version
paths may be considered obsolescent!.
Internal routines and common options
rect
$annotation->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.
border
$annotation->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. An optional
fourth entry (described below) may be used for a dashed or dotted line.
A border is used in annotations where text or some other material is put down, and a clickable
rectangle is defined over it (rect). A border is not shown when an icon is being used to mark the
clickable area.
A PDF Reader normally defaults to [0 0 1] (solid line of width 1, with sharp corners) if no border
("/Border") is specified. Keeping compatibility with PDF::API2's longstanding practice, PDF::Builder
defaults to no visible border "[0 0 0]" (solid line of width 0, and thus invisible).
Defining option:
border => [CRh, CRv, W]
border => [CRh, CRv, W, [on, off...]]
Note that the square brackets [ and ] are literally there, indicating a vector or array of values.
They do not indicate optional values!
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 PDF::Builder default is no border (while
a PDF Reader typically defaults to no border ([0 0 0]), if no /Border entry is given). Optionally, a
dash pattern array may be given ("on" length, "off" length, as one or more pairs). The default is a
solid line.
The border vector seems to ignore the first two settings (corner radii), but the line thickness
works, on basic Readers. The corner radii may work on some other Readers.
content
$annotation->content(@lines)
Sets the text-content of the "text()" annotation. This is a text string or array of strings.
open
$annotation->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".
dest
$annotation->dest($page, I<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 fit settings are
listed in "Page Fit Options" in PDF::Builder::Docs.
"xyz" is the default fit setting, with position (left and top) and zoom the same as the calling
page's ([undef, undef, undef]).
$annotation->dest($name)
Connect the Annotation to a "Named Destination" defined elsewhere, including the optional desired fit
(default: xyz undef*3).
Color
$annotation->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. Currently, named colors
(strings) are not handled.
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:
Named colors (e.g., 'black') are not supported at this time.
color => [ ] or not 1, 3, or 4 numbers 0.0-1.0
A medium gray (0.5 value) will be used if an invalid color is given.
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
text => string
Specify an optional text label for annotation. This text or comment only shows up as a title in the
pop-up containing the file or text.