1Text::Layout(3)       User Contributed Perl Documentation      Text::Layout(3)
2
3
4

NAME

6       Text::Layout - Pango style markup formatting
7
8       This module will cooperate with PDF::API2, PDF::Builder, Cairo, and
9       Pango.
10

SYNOPSIS

12       Text::Layout provides methods for Pango style text formatting. Where
13       possible the methods have identical names and (near) identical
14       behaviour as their Pango counterparts.
15
16       See
17       <https://developer.gnome.org/pango/stable/pango-Layout-Objects.html>.
18
19       The package uses Text::Layout::FontConfig (included) to organize fonts
20       by description.
21
22       If module HarfBuzz::Shaper is installed, Text::Layout can use it for
23       text shaping.
24
25       Example, using PDF::API2 integration:
26
27           use PDF::API2;              # or PDF::Builder
28           use Text::Layout;
29
30           # Create a PDF document.
31           my $pdf = PDF::API2->new;   # or PDF::Builder->new
32           $pdf->mediabox( 595, 842 ); # A4, PDF units
33
34           # Set up page and get the text context.
35           my $page = $pdf->page;
36           my $ctx  = $page->text;
37
38           # Create a markup instance.
39           my $layout = Text::Layout->new($pdf);
40
41           $layout->set_font_description(Text::Layout::FontConfig->from_string("times 40"));
42           $layout->set_markup( q{The <i><span foreground="red">quick</span> <span size="20"><b>brown</b></span></i> fox} );
43
44           # Center text.
45           $layout->set_width(595);    # width of A4 page
46           $layout->set_alignment("center");
47
48           # Render it.
49           $layout->show( 0, 600, $ctx );
50           $pdf->saveas("out.pdf");
51
52       All PDF::API2 graphic and text methods can still be used, they won't
53       interfere with the layout methods.
54

NOTES FOR PDF::API2/Builder USERS

56   Baselines
57       PDF::API2 and PDF::Builder render texts using the font baseline as
58       origin.
59
60       This module typesets text in an area of possibly limited width and
61       height. The origin is the top left of this area. Currently this area
62       contains only a single line of text. This will change in the future
63       when line breaking and paragraph formatting is implemented.
64
65       PDF::API2 and PDF::Builder coordinates have origin bottom left. This
66       module produces information with respect to top left coordinates.
67

IMPORTANT NOTES FOR PANGO USERS

69   Coordinate system
70       Pango, layered upon Cairo, uses a coordinate system that starts off top
71       left. So for western text the direction is increasing x and increasing
72       y.
73
74       PDF::API2 uses the coordinate system as defined in the PDF
75       specification. It starts off bottom left. For western text the
76       direction is increasing x and decreasing y.
77
78   Pango coordinates
79       Pango uses two device coordinates units: Pango units and device units.
80       Pango units are 1000 ("PANGO_SCALE") times the device units.
81
82       Several methods have two variants, e.g. get_size() and
83       get_pixel_size(). The pixel-variant uses device units while the other
84       variant uses Pango units.
85
86       This module assumes no scaling. If you insist on multiplying all values
87       by PANGO_SCALE use the set_pango_scale() method to say so and we'll
88       divide everything back again internally.
89
90   Pango device units
91       Pango device units are 96dpi while PDF uses 72dpi. This module ignores
92       this and uses PDF units everywhere, except for font sizes. Since we
93       want e.g. a "Times 20" font to be of equal size in the two systems, it
94       will set the PDF font size to 15.
95
96       DBD: Is this really a good idea?
97

METHODS

99       new( $pdf )
100           Creates a new layout instance for PDF::API2. This is for
101           convenience.  It is equivalent to
102
103               use Text::Layout::PDFAPI2;
104               $layout = Text::Layout::PDFAPI2->new($pdf);
105
106           For other implementations only the above method can be used.
107
108           The argument is the context for text formatting. In the case of
109           PDF::API2 this will be a PDF::API2 object.
110
111       copy
112           Copies (clones) a layout instance.
113
114           The content is copied deeply, the context and fonts are copied by
115           reference.
116
117       get_context
118           Gets the context of this layout.
119
120       context_changed
121           Not supported.
122
123       get_serial
124           Not supported.
125
126       set_text( $text )
127           Puts a string in this layout instance. No markup is processed.
128
129           Note that if you have used set_markup() on this layout before, you
130           may want to call set_attributes() to clear the attributes set on
131           the layout from the markup as this function does not clear all
132           attributes.
133
134       get_text
135           Gets the content of this layout instance as a single string.
136           Markup is ignored.
137
138           Returns undef if no text has been set.
139
140       get_character_count
141           Returns the number of characters in the text of this layout.
142
143           Basically the same as length of get_text().
144
145           Returns undef if no text has been set.
146
147       set_markup( $string )
148           Puts a string in this layout instance.
149
150           The string can contain Pango-compatible markup. See
151           <https://developer.gnome.org/pygtk/stable/pango-markup-language.html>.
152
153           Implementation note: Although all markup is parsed, not all is
154           implemented.
155
156       set_markup_with_accel
157           Not supported.
158
159       set_attributes
160       get_attributes
161           Not yet implemented.
162
163       set_font_description( $description )
164           Sets the default font description for the layout. If no font
165           description is set on the layout, the font description from the
166           layout's context is used.
167
168           $description is a Text::Layout::FontConfig object.
169
170       get_font_description
171           Gets the font description for the layout.
172
173           Returns undef if no font has been set yet.
174
175       set_width( $width )
176           Sets the width to which the lines of the layout should align, wrap
177           or ellipsized. A value of zero or less means unlimited width.  The
178           width is in Pango units.
179
180           Implementation note: Only alignment is implemented.
181
182       get_width
183           Gets the width in Pango units for for this instance, or zero if
184           unlimited.
185
186       set_height( $height )
187           Sets the height in Pango units for this instance.
188
189           Implementation note: Height restrictions are not yet implemented.
190
191       get_height
192           Gets the height in Pango units for this instance, or zero if no
193           height restrictions apply.
194
195       set_wrap( $mode )
196           Sets the wrap mode; the wrap mode only has effect if a width is set
197           on the layout with set_width(). To turn off wrapping, set the width
198           to zero or less.
199
200           Not yet implemented.
201
202       get_wrap
203           Returns the current wrap mode.
204
205           Not yet implemented.
206
207       is_wrapped
208           Queries whether the layout had to wrap any paragraphs.
209
210       set_ellipsize( $mode )
211           Sets the type of ellipsization being performed for the layout.
212
213           Not yet implemented.
214
215       get_ellipsize
216           Gets the type of ellipsization being performed for the layout.
217
218       is_ellipsized
219           Queries whether the layout had to ellipsize any paragraphs.
220
221           Not yet implemented.
222
223       set_indent( $value )
224           Sets the width in Pango units to indent for each paragraph.
225
226           A negative value of indent will produce a hanging indentation. That
227           is, the first line will have the full width, and subsequent lines
228           will be indented by the absolute value of indent.
229
230           The indent setting is ignored if layout alignment is set to
231           "center".
232
233           Not yet implemented.
234
235       get_indent
236           Gets the current indent value in Pango units.
237
238       set_spacing( $value )
239           Sets the amount of spacing, in Pango units, between lines of the
240           layout.
241
242           When placing lines with spacing, things are arranged so that
243
244               line2.top = line1.bottom + spacing
245
246           Note: By default the line height (as determined by the font) for
247           placing lines is used. The spacing set with this function is only
248           taken into account when the line-height factor is set to zero with
249           set_line_spacing().
250
251           Not yet implemented.
252
253       get_spacing
254           Gets the current amount of spacing, in Pango units.
255
256       set_line_spacing( $factor )
257           Sets a factor for line spacing. Typical values are: 0, 1, 1.5, 2.
258           The default value is 0.
259
260           If factor is non-zero, lines are placed so that
261
262               baseline2 = baseline1 + factor * height2
263
264           where height2 is the line height of the second line (as determined
265           by the font(s)). In this case, the spacing set with set_spacing()
266           is ignored.
267
268           If factor is zero, spacing is applied as before.
269
270           Not yet implemented.
271
272       get_line_spacing
273           Gets the current line spacing factor.
274
275       set_justify( $state )
276           Sets whether each complete line should be stretched to fill the
277           entire width of the layout. This stretching is typically done by
278           adding whitespace.
279
280           Not yet implemented.
281
282       get_justify
283           Gets whether each complete line should be stretched to fill the
284           entire width of the layout.
285
286       set_auto_dir( $state )
287       get_auto_dir
288           Not supported.
289
290       set_alignment( $align )
291           Sets the alignment for the layout: how partial lines are positioned
292           within the horizontal space available.
293
294           $align must be one of "left", "center", or "right",
295
296       get_alignment
297           Gets the alignment for this instance.
298
299       set_tabs( $stops )
300       get_tabs
301           Not yet implemented.
302
303       set_single_paragraph_mode( $state )
304       get_single_paragraph_mode
305           Not yet implemented.
306
307       get_unknown_glyphs_count
308           Counts the number unknown glyphs in the layout.
309
310           Not yet implemented.
311
312       get_log_attrs
313       get_log_attrs_readonly
314           Not implemented.
315
316       index_to_pos( $index )
317           Converts from a character index within the layout to the onscreen
318           position corresponding to the grapheme at that index, which is
319           represented as rectangle.
320
321           Not yet implemented.
322
323       index_to_line_x ( $index )
324           Converts from a character index within the layout to line and X
325           position.
326
327           Not yet implemented.
328
329       xy_to_index ( $x, $y )
330           Converts from $x,$y position to a character index within the
331           layout.
332
333           Not yet implemented.
334
335       get_extents
336           Computes the logical and ink extents of the layout.
337
338           Logical extents are usually what you want for positioning things.
339
340           Return value is an array (in list context) or an array ref (in
341           scalar context) containing two hash refs with 4 values: "x", "y",
342           "width", and "height". The first reflects the ink extents, the
343           second the logical extents.
344
345           "x" will reflect the offset when text is centered or right aligned.
346           It will be zero for left aligned text. For right aligned text, it
347           will be the width of the layout.
348
349           "y" will reflect the offset when text is centered vertically or
350           bottom aligned. It will be zero for top aligned text.
351
352           Implementation note: Since the PDF::API support layer cannot
353           calculate ink, this function returns two identical extents.
354
355       get_pixel_extents
356           Same as get_extents, but using device units.
357
358       get_size
359           Returns the width and height of this layout.
360
361           In list context, width and height are returned as an two-element
362           list.  In scalar context a hashref with keys "width" and "height"
363           is returned.
364
365       get_pixel_size
366           Same as get_size().
367
368       get_iter
369           Returns the layout for the first line.
370
371           Implementation note: This is a dummy, it returns the layout.  It is
372           provided so you can write $layout->get_iter()->get_baseline() to be
373           compatible with the official Pango API.
374
375       get_baseline
376           Gets the Y position of the baseline of the first line in this
377           layout.
378
379           Implementation note: Position is relative to top left, so due to
380           the PDF coordinate system this is a negative number.
381
382           Note: The Python API only supports this method on iteration
383           objects.  See get_iter().
384

METHODS NOT IMPLEMENTED

386       get_line_count
387       get_line( $index )
388       get_line_readonly( $index )
389       get_lines
390       get_lines_readonly
391       line_get_extents
392       line_get_pixel_entents
393       line_index_to_x
394       line_x_to_index
395       line_get_x_ranges
396       line_get_height
397       get_cursor_pos
398       move_cursor_visually
399
400   ADDITIONAL METHODS
401       The following methods are not part of the Pango API.
402
403       set_font_size( $size )
404           Sets the size for the current font.
405
406       get_font_size
407           Returns the size of the current font.
408
409           NOTE: This is not a Pango API method.
410
411       get_bbox
412           Returns the bounding box of the text, w.r.t. the origin.
413
414                +-----------+   ascend
415                |           |
416                |           |
417                |           |
418                |           |
419                |           |
420                | <-width-> |
421                |           |
422                |           |
423                o-----------+   o = origin baseline
424                |           |
425                |           |
426                +-----------+   descend
427
428           bb = ( left, descend, right, ascend )
429
430           bb[0] = left is nonzero for centered and right aligned text
431
432           bb[1] = descend is a negative value
433
434           bb[2] - bb[0] = advancewidth
435
436           bb[2] = layout width for right aligned text
437
438           bb[3] = ascend is a positive value
439
440           NOTE: Some fonts do not include accents on capital letters in the
441           ascend.
442
443       show( $x, $y, $text )
444           Transfers the content of this layout instance to the designated
445           graphics environment.
446
447           Use this instead of Pango::Cairo::show_layout().
448
449           For PDF::API2, $text must be an object created by the $page->text
450           method.
451
452       set_pango_scale( $scale )
453           Sets the pango scaling to $scale, which should be 1000.
454
455           Set to 1 to cancel scaling, causing all methods to use pixel units
456           instead of Pango units. Set to 0 to get the default behaviour.
457

SEE ALSO

459       Description of the Pango Markup Language:
460       <https://developer.gnome.org/pygtk/stable/pango-markup-language.html>.
461
462       Documentation of the Pango Layout class:
463       <https://developer.gnome.org/pango/stable/pango-Layout-Objects.html>.
464
465       PDF::API2, PDF::Builder, HarfBuzz::Shaper, Font::TTF.
466

AUTHOR

468       Johan Vromans, "<JV at CPAN dot org>"
469

SUPPORT

471       Development of this module takes place on GitHub:
472       <https://github.com/sciurius/perl-Text-Layout>.
473
474       You can find documentation for this module with the perldoc command.
475
476         perldoc Text::Layout
477
478       Please report any bugs or feature requests using the issue tracker on
479       GitHub.
480

LICENSE

482       Copyright (C) 2019, Johan Vromans
483
484       This module is free software. You can redistribute it and/or modify it
485       under the terms of the Artistic License 2.0.
486
487       This program is distributed in the hope that it will be useful, but
488       without any warranty; without even the implied warranty of
489       merchantability or fitness for a particular purpose.
490
491
492
493perl v5.32.1                      2021-01-27                   Text::Layout(3)
Impressum