File Coverage

blib/lib/Text/Layout.pm

Criterion	Covered	Total	%
statement	180	377	47.7
branch	95	212	44.8
condition	24	53	45.2
subroutine	30	82	36.5
pod	60	68	88.2
total	389	792	49.1

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