|
|
| |
PDF::Builder::Annotation(3) |
User Contributed Perl Documentation |
PDF::Builder::Annotation(3) |
PDF::Builder::Annotation - Add annotations to a PDF
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.
- $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->link($page, %options)
- $annotation->link($page)
- Defines the annotation as a launch-page with page
$page (within this document) and options
%options (-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)".
- $annotation->pdf_file($pdffile, $page_number, %options)
- Defines the annotation as a PDF-file with filepath
$pdffile, on page
$page_number, and options
%options (-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,...
- $annotation->file($file, %options)
- Defines the annotation as a launch-file with filepath
$file (a local file) and options
%options (-rect, -border, -color: see descriptions
below). How the file is displayed depends on the operating system,
type of file, and local configuration or mapping.
- $annotation->url($url, %options)
- Defines the annotation as a launch-url with url
$url and options %options
(-rect, -border, -color: see descriptions below). This page is usually
brought up in a browser, and may be remote.
- $annotation->text($text, %options)
- Defines the annotation as a text note with content string
$text and options %options
(-rect, -color, -text, -open: 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.
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.
- $annotation->markup($text, $PointList, $highlight, %options)
- Defines the annotation as a text note with content string
$text and options %options
(-rect, -color, -text, -open: 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.
- $annotation->movie($file, $contentType, %options)
- Defines the annotation as a movie from $file with
content (MIME) type $contentType and options
%options (-rect, -border, -color: 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.
- $annotation->file_attachment($file, %options)
- Defines the annotation as a file attachment with file
$file and options %options
(-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!.
- $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.
- $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.
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 used when an icon is being used to mark the
clickable area.
The default is [0 0 1] (solid line of width 1, with sharp
corners).
Defining option:
- -border => [CRh, CRv, W]
- -border => [CRh, CRv, W [, on, off...]]
- 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]).
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
radii may work on some other Readers.
- $annotation->content(@lines)
- Sets the text-content of the "text()"
annotation. This is a text string or array of strings.
- $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".
- $annotation->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 fit
settings 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 ([undef, undef,
undef]).
- $annotation->dest($name)
- Connect the Annotation to a "Named Destination" defined
elsewhere, including the optional desired fit (default: -xyz
undef*3).
- $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 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
- 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.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |