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 bran cond sub pod time code
1             #! perl
2              
3 6     6   241649 use strict;
  6         14  
  6         172  
4 6     6   29 use warnings;
  6         11  
  6         149  
5 6     6   28 use utf8;
  6         12  
  6         26  
6              
7             package Text::Layout;
8              
9 6     6   178 use Carp;
  6         12  
  6         862  
10              
11              
12              
13             our $VERSION = "0.031";
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