NAME

PDF::Cairo::Layout - wrapper for Pango layouts

SYNOPSIS

Simplified interface for rendering Pango layouts with markup in Cairo. All of the method arguments are in standard Cairo units; you only use 'Pango units' (1/1024pt) inside markup tags (specifically, size, rise, and letter_spacing). Methods that do not return an explicit value return $self so they can be chained.

use PDF::Cairo qw(cm);
use PDF::Cairo::Layout;
$pdf = PDF::Cairo->new(
    file => "output.pdf",
    paper => "a4",
    landscape => 1,
);
$layout = PDF::Cairo::Layout->new($pdf);
$markup = qq(<big><b>big bold text</b></big>\n);
$markup .= qq(<span font='Ms Mincho 32' lang='ja'>日本語</span>);
$layout->markup($markup);
$layout->width(cm(8))->indent(16);
$pdf->move(cm(3), cm(5));
$layout->show;

MARKUP

The Pango markup format supports the following HTML-like tags: <b>, <big>, <i>, <s>, <span>, <sub>, <sup>, <small>, <tt>, and <u>. Span tags are the primary way to markup text, with the others used as shortcuts for common styles.

To set the font, you can either use the font attribute with a space-separated list of family, point size, style, variant, weight, and stretch (all of which are optional), or set them individually with the face, size, style, weight, variant, and stretch attributes. Both of these methods are quirky and unpredictable, and your best bet is to select a quoted string from the output of pango-list, add a size in points to the end, and use that as the argument to font.

Size is either integers in 1/1024pt, or one of: xx-small, x-small, small, medium, large, x-large, xx-large, smaller, larger. Style is either normal or italic. Weight is either a numeric weight or one of: ultralight, light, normal, bold, ultrabold, heavy. Variant is either normal or smallcaps. Stretch is one of: ultracondensed, extracondensed, condensed, semicondensed, normal, semiexpanded, expanded, extraexpanded, ultraexpanded.

Additional attributes include color (name or hex string), bgcolor, alpha (1-65536 or percentage string), bgalpha, underline (none, single, double, low, error), underline_color, rise (1/1024pt), strikethrough (true, false), strikethrough_color, lang, and letter_spacing (1/1024pt).

Newlines are used to indicate line breaks.

Full documentation on the markup language can be found at:

https://developer.gnome.org/pango/unstable/PangoMarkupFormat.html

DESCRIPTION

Methods

new $pdf_cairo_ref, %options

alignment => 'left|center|right'

ellipsize => 'none|start|middle|end'

height => $height

indent => $indent

justify => 1|0

size => [$width, $height]

spacing => $spacing

tabs => [tab1,...]

width => $width

wrap => 'word|char|word-char'

Create a new layout. The first argument must be a PDF::Cairo object, in order for Pango to locate the Cairo context. Options behave the same as the methods below, except that an array reference must be passed for size and tabs.

alignment ['left|center|right']

Sets/gets the paragraph alignment for the current layout.

baseline

Returns the Y offset from the top of the current layout to the baseline of the first line of text. Negative.

ellipsize ['none|start|middle|end']

Get/set the ellipsis settings for the current layout.

height [$height]

Sets/gets the height of the current layout. If negative, instead sets the number of lines per paragraph to display, ellipsizing the others. If zero, render exactly one line.

indent [$indent]

Sets/gets the indentation for the current layout. If negative, produces a hanging indent.

ink

Returns the ink extents of the current layout as a hash reference containing the scalars x, y, width, height, and the array reference bbox containing all four in that order with the height negated to reflect that (x,y) is the offset from the upper-left corner of the layout:

{
  x => $x,
  y => $y,
  width => $width,
  height => $height,
  bbox => [$x, $y, $width, -$height],
}

Note that a trailing newline in the markup will count as extra "ink".

justify [1|0]

Get/set the justification for the current layout.

markup $text

Set the contents of the current layout to $text, which will be parsed for Pango markup tags.

path

Add the outlines of the glyphs in the current layout to the current path.

show

Render layout with the upper-left corner starting at the current position.

size [$width, $height]

Sets/gets the width and height of the current layout.

spacing $spacing

Get/set the inter-line spacing for the current layout.

tabs [tab1,...]

Sets/gets the tabs for the current layout. Defaults to the width of eight space characters in the current font.

width [$width]

Sets/gets the wrap width of the current layout. If set to -1, no width is set (default).

wrap ['word|char|word-char']

Sets/gets the word-wrap settings for the current layout.

AUTHOR

J Greely, <jgreely at cpan.org>

SEE ALSO

Pango, Pango::Layout, Pango Markup Format