NAME

       Text::Layout::PDFAPI2::ImageElement - <img> element for PDF images

DESCRIPTION

       This class implements support for an "<img>" element. It can be used to include inline
       images in marked-up texts.

       The class provides the three mandatory methods according to the requirements of
       Text::Layout::ElementRole.

       parse
           To parse the "<img>" tag in marked-up text.

       bbox
           To provide the augmented bounding box for the image.

       render
           To render the image using one of the PDF::API2 compatible libraries.

       An additional, overridable method getimage() is provided to actually produce the desired
       image object. See "IMAGE PRODUCER"

THE "<img>" ELEMENT

           <img attributes />

       Note that the "<img>" element must be self-closed, i.e., end with "/>".

       The image is placed at the current location in the text and aligned on the baseline of the
       text. The image dimensions contribute to the resultant bounding box of the formatted text.
       See "dx" and "dy" below.

       All attributes are key=value pairs. The value should (but need not) be enclosed in quotes.

       Dimensional values may be a (fractional) number optionally postfixed by "em" or "ex", or a
       percentage.  A number indicates points.  "em" values are multiplied by the current font
       size and "ex" values are multiplied by half the font size.

       "src="IMAGE
           Provides the source of the image. This can be the filename of a jpg, png or gif image.

       "width="NNN
           The desired width for the image.  Dimensional.  The image is scaled if necessary.

       "height="NNN
           The desired height for the image.  Dimensional.  The image is scaled if necessary.

       "dx="NNN
           A horizontal offset for the image, wrt. the current location in the text.
           Dimensional.

       "dy="NNN
           Same, but vertical. Positive amounts move up.

           Note the direction is opposite to the Pango "rise".

       "scale="NNN
           A scaling factor, to be applied after width/height scaling.  The value may be
           expressed as a percentage.

       "align="XXX
           Align the image in the width given by "w="NNN.

           Possible alignments are "left", "center", and "right".

       "bbox="N
           If true, the actual bounding box of an object is used for placement.

           By default the bounding box is only used to obtain the width and height.

           This attribute has no effect on image objects.

       "w="NNN
           The advance width of the image.  Dimensional.  Default advance is the image width plus
           horizontal offset.  This overrides the advance and may be zero.

       "h="NNN
           The advance height of the image.  Dimensional.  Default advance is the image height
           plus vertical offset.  This overrides the advance and may be zero.

CONSTRUCTOR

       This class is usually instantiated in a Text::Layout register_element call:

           $layout->register_element
             ( Text::Layout::PDFAPI2::ImageElement->new( pdf => $pdf ) );

IMAGE PRODUCER

       The image object is produced with a call to method getimage(), that can be overridden in a
       subclass.  The method gets a hash ref as argument.  This hash contains all the attributes
       and may be used for cacheing purposes.

       For example,

           method getimage ($fragment) {
               $fragment->{_img} //= $self->pdf->image($fragment->{src});
           }

       An overridden getimage() may produce a PDF XObject instead of an image object. An XObject
       is treated similar to an image object, but is aligned according to its bounding box if
       attribute "bbox" is set to a true value, i.e., not zero.

SEE ALSO

       Text::Layout, PDF::API2, PDF::Builder.

AUTHOR

       Johan Vromans, "<JV at CPAN dot org>"

SUPPORT

       This class is part of <Text::Layout>.

       Development takes place on GitHub: <https://github.com/sciurius/perl-Text-Layout>.

       Please report any bugs or feature requests using the issue tracker for Text::Layout on
       GitHub.

LICENSE

       See Text::Layout.