| PDF::Builder::Annotation(3pm) | User Contributed Perl Documentation | PDF::Builder::Annotation(3pm) |
NAME¶
PDF::Builder::Annotation - Add annotations to a PDF
Inherits from PDF::Builder::Basic::PDF::Dict
SYNOPSIS¶
An "annotation" is an extra feature on a page that may change the appearance (e.g., highlighting), or perform some action when clicked on. Some actions may require a single click and others a double click; this depends on the PDF Reader used. Some may warn you and/or ask permission to perform a certain action, while others may refuse to do something (which may be configurable).
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. In particular, Named Destinations seem to be handled in widely varying ways!
new¶
$annotation = PDF::Builder::Annotation->new()
It is normally not necessary to explicitly call this method (see examples).
Common parameters¶
For the annotation calls given below, all require a clickable rectangular area (button) on the page to activate the call. These all share common parameters to define this "button". Note that your code is responsible for creating the visible content of the button (if any), while the 'rect' parameter tells the annotation what (invisible) area on the page activates it, and the 'border' and 'color' parameters describe the border drawn around the button.
Note that this is in contrast to "NamedDestination", which ignores any of these entries, as it does not define a "button" to press.
'rect' => [ LLx,LLy, URx,URy ]
This defines the rectangle of the "button". Your code is responsible for any fill or text visible to the user, via normal text and graphics calls. As an alternative (mandatory if 'rect' is not given), you may specify the rectangle with the "$ann->rect(LLx,LLy, URx,URy);" call. Note: the other diagonals (UL to LR, LR to UL, UR to LL) are usually allowed.
Instead of this hash element being used, the
$ann->rect( LLx,LLy, URx,URy )
method may be used (before the annotation method itself is invoked).
'border' => [ Rx,Ry, w, [dash-pattern] ]
This defines the border around the button. If not given, the default is [ 0, 0, 1 ]. Rx and Ry are corner radii (0 for sharp corners), w is the stroke width (0 for no visible border), and an optional dash-pattern may be given to draw something other than a solid line (e.g., [5, 5] for a 5pt long dash and 5pt space pattern). Note that the square brackets [ ] are actually used, as the dash-pattern is an anonymous array.
Instead of this hash element being used, the
$ann->border(Rx,Ry, w, [dash-pattern])
method may be used (before the annotation method itself is invoked).
'color' => [ Red, Green, Blue ]
This defines the stroke color of the button border, using the RGB triplet way of describing a color (RGB anonymous array, each value 0 to 1). If 0 width does not work on all Readers to suppress the border, selecting a color that matches any fill or background color in the button may work instead.
Instead of this hash element being used, the
$ann->Color(Red, Green, Blue)
method may be used (before the annotation method itself is invoked). Note that Color is capitalized, unlike the hash option method.
It's a matter of stylistic choice whether to give these settings as options to the annotation object in the call, or call their methods directly before the annotation action method itself is called.
Some calls have additional optional parameters, which will be described in their section.
Annotation types¶
goto, link
$annotation->goto($page, $location, @args, %opts) # preferred
$annotation->goto($page, %opts) # location info as a hash element
Note that $page is not a simple page number, but is either a page object such as "$pdf->openpage(page_number)", or a Named Destination defined elsewhere (a prefix of '#' or '/' is optional, except when the Named Destination is entirely numeric, and then it is required). 'foo', '#foo', and '/3659' are examples of Named Destinations. If a Named Destination is given, the page fit (location) is ignored, as the Named Destination handles that.
Note that the options %opts is a hash, permitting 'rect', 'border', and 'color' to be described in a more natural manner than flattening the hash into an array. The location and its arguments (fit data) may be either a list (in the PDF::API2 style) or another hash element.
Alternate name: "link"
Originally this method was named "link", but PDF::API2 changed it to "goto", to correspond to the GoTo PDF command used. For compatibility, it has been changed to "goto", with "link" still available as an alias.
pdf, pdfile, pdf_file
$annotation->pdf($pdffile, $page_number, $location, @args, %opts) # preferred
$annotation->pdf($pdffile, $page_number, %opts) # including location & data
$page_number is the physical page number, starting at 1: 1, 2,..., or a Named Destination defined in that document (a prefix of '#' or '/' is optional, except when the Named Destination is entirely numeric, and then it is required). 'foo', '/foo', and '#3659' are examples of Named Destinations. If a Named Destination is used, the page fit (location) is ignored, as the Named Destination handles that.
Note that the options %opts is a hash, while the location and fit @args may be described as a list (PDF::API2 style), or as another hash element. This permits 'rect', 'border', and 'color' to be described in a more natural manner than flattening the hash into an array.
Alternate names: "pdfile" and "pdf_file"
Originally this method was named "pdfile", and then "pdf_file" but PDF::API2 changed it to "pdf". For compatibility, it has been changed to "pdf", with "pdfile" and "pdf_file" still available as aliases.
uri, url
$annotation->uri($url, %opts)
Alternate name: "url"
Originally this method was named "url", but PDF::API2 changed it to "uri" to correspond to the URI PDF command used. For compatibility, it has been changed to "uri", with "url" still available as an alias.
launch, file
$annotation->launch($file, %opts)
Alternate name: "file"
Originally this method was named "file", but PDF::API2 changed it to "launch" to correspond to the Launch PDF command used. For compatibility, it has been changed to "launch", with "file" still available as an alias.
text
$annotation->text($text, %opts)
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)
"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 some PDF
specifications! 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:
- 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)
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)
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¶
The common options may be called separately (applied against $annotation before calling the action routine), or passed as options to the call.
rect
$annotation->rect($llx,$lly, $urx,$ury)
The default clickable area is the icon itself.
Defining option. Note that this "option" is actually required.
This call may be replaced by a hash element 'rect'=> in many calls (see Common parameters).
- rect => [LLx, LLy, URx, URy]
- Set annotation rectangle as an option 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)
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.
This call may be replaced by a hash element 'border'=> in many calls (see Common parameters).
Color
$annotation->Color(@color)
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.
This call may be replaced by a hash element 'color'=> in many calls (see Common parameters).
content
$annotation->content(@lines)
open
$annotation->open($bool)
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".
text string
'text' => string
| 2026-01-07 | perl v5.40.1 |