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.

       $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
       $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!.

   Internal routines and common options
       $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.