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.