Text::...Element(3pm)

✨ NAME ✨

Text::Layout::PDFAPI2::ImageElement — the <img> element for PDF images, bestie 💖

---

🦋 DESCRIPTION 🦋

Okay so this class is literally the glow-up that lets you drop <img> elements into your marked-up text — inline images, in your PDF, no cap. Slay.

It comes through with the three mandatory methods that Text::Layout::ElementRole demands, because it's a well-behaved icon:

• parse — parses the <img> tag in your marked-up text 🎀
• bbox — hands over the augmented bounding box for the image
• render — actually renders the image, using one of the PDF::API2 compatible libraries

Plus there's a bonus, overridable method — getimage() — that does the actual work of producing the image object you want. Peep IMAGE PRODUCER below for the tea 👑

---

💅 THE <img> ELEMENT 💅

<img attributes />

⚠️ Not me reminding you: the <img> element must be self-closed, i.e. it has to end with />. No exceptions, periodt.

The image gets placed at the current location in the text and aligned on the baseline of the text. Its dimensions count toward the resulting bounding box of the formatted text — see dx and dy down there ⬇️

Every attribute is a key=value pair. The value should be wrapped in quotes (but doesn't have to be — we're chill like that).

Dimensional values can be a (fractional) number, optionally postfixed with em or ex, or a percentage. A plain number means points ✨ An em value gets multiplied by the current font size, and an ex value gets multiplied by half the font size.

• src= IMAGE — gives you the source of the image. Can be the filename of a jpg, png or gif image. 🖼️
• width= NNN — the desired width for the image. Dimensional. The image gets scaled if it needs to be.
• height= NNN — the desired height for the image. Dimensional. Same deal, it gets scaled if necessary.
• dx= NNN — a horizontal offset for the image, wrt. the current location in the text. Dimensional.
• dy= NNN — same energy, but vertical. Positive amounts move up.

🫠 Heads up: the direction is opposite to the Pango rise.

• scale= NNN — a scaling factor, applied after the width/height scaling. The value may be expressed as a percentage.

Want independent horizontal and vertical scaling? That's giving two comma-separated scale values, and it's iconic.

• align= XXX — aligns the image within 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.

💀 Real talk: this attribute has no effect on image objects.

• w= NNN — the advance width of the image. Dimensional. The default advance is the image width plus horizontal offset. This overrides the advance, and it may be zero.
• h= NNN — the advance height of the image. Dimensional. The default advance is the image height plus vertical offset. This overrides the advance, and it may be zero.

---

🌸 CONSTRUCTOR 🌸

This class usually gets instantiated inside a Text::Layout register_element call, like so:

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

Yes bestie, that's the whole vibe check ✅

---

🧚 IMAGE PRODUCER 🧚

The image object comes from a call to the method getimage(), which you can override in a subclass. The method receives a hash ref as its argument. That hash holds all the attributes, and you can absolutely use it 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 it's aligned according to its bounding box if the 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. We're listening, fr fr 🙈

---

📜 LICENSE 📜

See Text::Layout.

---

and that's the whole page, bestie — no notes 💅

this page is brought to you by perl v5.40.1, dated 2025-08-15 📅 — stay hydrated, close your tags, and go render something gorgeous ✨🦋💖