File Coverage

blib/lib/Text/Layout.pm

Criterion	Covered	Total	%
statement	149	299	49.8
branch	89	170	52.3
condition	14	26	53.8
subroutine	25	74	33.7
pod	56	62	90.3
total	333	631	52.7

line	stmt	sub	time	code
1				#! perl
2
3	6	6	198633	use strict;
	6		11
	6		157
4	6	6	26	use warnings;
	6		10
	6		121
5	6	6	22	use utf8;
	6		9
	6		34
6
7				package Text::Layout;
8
9	6	6	181	use Carp;
	6		11
	6		671
10
11
12
13				our $VERSION = "0.030";
14
15				=head1 NAME
16
17				Text::Layout - Pango style markup formatting
18
19				This module will cooperate with PDF::API2, PDF::Builder, Cairo, and Pango.
20
21				=head1 SYNOPSIS
22
23				Text::Layout provides methods for Pango style text formatting. Where
24				possible the methods have identical names and (near) identical
25				behaviour as their Pango counterparts.
26
27				See L.
28
29				The package uses Text::Layout::FontConfig (included) to organize fonts
30				by description.
31
32				If module HarfBuzz::Shaper is installed, Text::Layout can use it for
33				text shaping.
34
35				Example, using PDF::API2 integration:
36
37				use PDF::API2; # or PDF::Builder
38				use Text::Layout;
39
40				# Create a PDF document.
41				my $pdf = PDF::API2->new; # or PDF::Builder->new
42				$pdf->mediabox( 595, 842 ); # A4, PDF units
43
44				# Set up page and get the text context.
45				my $page = $pdf->page;
46				my $ctx = $page->text;
47
48				# Create a markup instance.
49				my $layout = Text::Layout->new($pdf);
50
51				# This example uses PDF corefonts only.
52				Text::Layout::FontConfig->register_corefonts;
53
54				$layout->set_font_description(Text::Layout::FontConfig->from_string("times 40"));
55				$layout->set_markup( q{The quick brown fox} );
56
57				# Center text.
58				$layout->set_width(595); # width of A4 page
59				$layout->set_alignment("center");
60
61				# Render it.
62				$layout->show( 0, 600, $ctx );
63				$pdf->saveas("out.pdf");
64
65				All PDF::API2 graphic and text methods can still be used, they won't
66				interfere with the layout methods.
67
68				=head1 NOTES FOR PDF::API2/Builder USERS
69
70				=head2 Baselines
71
72				PDF::API2 and PDF::Builder render texts using the font baseline as origin.
73
74				This module typesets text in an area of possibly limited width and
75				height. The origin is the top left of this area. Currently this area
76				contains only a single line of text. This will change in the future
77				when line breaking and paragraph formatting is implemented.
78
79				PDF::API2 and PDF::Builder coordinates have origin bottom left. This
80				module produces information with respect to top left coordinates.
81
82				=head1 IMPORTANT NOTES FOR PANGO USERS
83
84				=head2 Coordinate system
85
86				Pango, layered upon Cairo, uses a coordinate system that starts off
87				top left. So for western text the direction is increasing I and
88				increasing I.
89
90				PDF::API2 uses the coordinate system as defined in the PDF
91				specification. It starts off bottom left. For western text the
92				direction is increasing I and Bcreasing I.
93
94				=head1 Pango Conformance Mode
95
96				Text::Layout can operate in one of two modes: I
97				(enabled by default), and I. The desired mode
98				can be selected by calling the method set_pango_scaling().
99
100				=head2 Pango coordinates
101
102				Pango uses two device coordinates units: Pango units and device units.
103				Pango units are 1024 (C) times the device units.
104
105				Several methods have two variants, e.g. get_size() and
106				get_pixel_size(). The pixel-variant uses device units while the other
107				variant uses Pango units.
108
109				In I, this module assumes no scaling. All units are
110				PDF device units (1/72 inch).
111
112				=head2 Pango device units
113
114				Device units are used for font rendering. Pango device units are 96dpi
115				while PDF uses 72dpi.
116
117				In I this is ignored. E.g. a C font
118				will be of equal size in the two systems,
119
120				In I you would need to specify a font size of
121				C<15360> to get a 20pt font.
122
123				=head1 SUPPORTED MARKUP
124
125				Text::Layout recognizes most of the Pango markup as provided by the
126				Pango library version 1.50 or newer. However, not everything is supported.
127
128				=head2 Span attributes
129
130				=over 8
131
132				=item font="I" font_desc="I"
133
134				Specifies a font to be used, e.g. C.
135
136				=item font_face="I" face="I"
137
138				Specifies a font family to be used.
139
140				=item font_family="I"
141
142				Same as font_face="I".
143
144				=item size=I size=Ipt size=I%
145
146				Font size in 1024ths of a point (conformance mode), or in points (e.g.
147				‘12.5pt’), or a percentage (e.g. ‘200%’), or one of the relative sizes
148				‘smaller’ or ‘larger’.
149
150				Note that in Pango conformance mode, the actual font size is 96/72
151				larger. So C<"45pt"> gives a 60pt font.
152
153				=item style="I