1Text::Layout(3) User Contributed Perl Documentation Text::Layout(3)
2
6 Text::Layout - Pango style markup formatting
7 This module will cooperate with PDF::API2, PDF::Builder, Cairo, and
9 Pango.
10
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 See
17 <https://developer.gnome.org/pango/stable/pango-Layout-Objects.html>.
18 The package uses Text::Layout::FontConfig (included) to organize fonts
20 by description.
21 If module HarfBuzz::Shaper is installed, Text::Layout can use it for
23 text shaping.
24 Example, using PDF::API2 integration:
26 use PDF::API2; # or PDF::Builder
28 use Text::Layout;
29 # Create a PDF document.
31 my $pdf = PDF::API2->new; # or PDF::Builder->new
32 $pdf->mediabox( 595, 842 ); # A4, PDF units
33 # Set up page and get the text context.
35 my $page = $pdf->page;
36 my $ctx = $page->text;
37 # Create a markup instance.
39 my $layout = Text::Layout->new($pdf);
40 # This example uses PDF corefonts only.
42 Text::Layout::FontConfig->register_corefonts;
43 $layout->set_font_description(Text::Layout::FontConfig->from_string("times 40"));
45 $layout->set_markup( q{The <i><span foreground="red">quick</span> <span size="20"><b>brown</b></span></i> fox} );
46 # Center text.
48 $layout->set_width(595); # width of A4 page
49 $layout->set_alignment("center");
50 # Render it.
52 $layout->show( 0, 600, $ctx );
53 $pdf->saveas("out.pdf");
54 All PDF::API2 graphic and text methods can still be used, they won't
56 interfere with the layout methods.
57
59 Baselines
60 PDF::API2 and PDF::Builder render texts using the font baseline as
61 origin.
62 This module typesets text in an area of possibly limited width and
64 height. The origin is the top left of this area. Currently this area
65 contains only a single line of text. This will change in the future
66 when line breaking and paragraph formatting is implemented.
67 PDF::API2 and PDF::Builder coordinates have origin bottom left. This
69 module produces information with respect to top left coordinates.
70
72 Coordinate system
73 Pango, layered upon Cairo, uses a coordinate system that starts off top
74 left. So for western text the direction is increasing x and increasing
75 y.
76 PDF::API2 uses the coordinate system as defined in the PDF
78 specification. It starts off bottom left. For western text the
79 direction is increasing x and decreasing y.
80
82 Text::Layout can operate in one of two modes: convenience mode (enabled
83 by default), and Pango conformance mode. The desired mode can be
84 selected by calling the method set_pango_scaling().
85 Pango coordinates
87 Pango uses two device coordinates units: Pango units and device units.
88 Pango units are 1024 ("PANGO_SCALE") times the device units.
89 Several methods have two variants, e.g. get_size() and
91 get_pixel_size(). The pixel-variant uses device units while the other
92 variant uses Pango units.
93 In convenience mode, this module assumes no scaling. All units are PDF
95 device units (1/72 inch).
96 Pango device units
98 Device units are used for font rendering. Pango device units are 96dpi
99 while PDF uses 72dpi.
100 In convenience mode this is ignored. E.g. a "Times 20" font will be of
102 equal size in the two systems,
103 In Pango conformance mode you would need to specify a font size of
105 15360 to get a 20pt font.
106
108 Text::Layout recognizes most of the Pango markup as provided by the
109 Pango library version 1.50 or newer. However, not everything is
110 supported.
111 Span attributes
113 font="DESC" font_desc="DESC"
114 Specifies a font to be used, e.g. "Serif 20".
115 font_face="FAM" face="FAM"
117 Specifies a font family to be used.
118 font_family="FAM"
120 Same as font_face="FAM".
121 size=FNUM size=FNUMpt size=FNUM%
123 Font size in 1024ths of a point (conformance mode), or in
124 points (e.g. ‘12.5pt’), or a percentage (e.g. ‘200%’), or one
125 of the relative sizes ‘smaller’ or ‘larger’.
126 Note that in Pango conformance mode, the actual font size is
128 96/72 larger. So "45pt" gives a 60pt font.
129 style="STYLE" font_style="STYLE"
131 Specifes the font style, e.g. "italic".
132 weight="WEIGHT" font_weight="WEIGHT"
134 Specifies the font weight, e.g. "bold".
135 foreground="COLOR" fgcolor="COLOR" color="COLOR"
137 Specifies the foreground colour, e.g. "black".
138 background="COLOR" bgcolor="COLOR"
140 Specifies the background colour, e.g. "white".
141 underline="TYPE"
143 Enables underlining. TYPE must be "none", "single", or
144 "double".
145 underline_color="COLOR"
147 The colour to be used for underlining, if enabled.
148 overline="TYPE"
150 Enables overlining. TYPE must be "none", "single", or
151 "double".
152 overline_color="COLOR"
154 The colour to be used for ovderlining, if enabled.
155 strikethrough="ARG"
157 Enables or diables overlining. ARG must be "true" or 1 to
158 enable, and "false" or 0 to disable.
159 strikethrough_color="COLOR"
161 The colour to be used for striking, if enabled.
162 rise="NUM"
164 In convenience mode, lowers the text by NUM/1024 of the font
165 size. May be negative to rise the text.
166 In Pango conformance mode, rises the text by NUM units from the
168 baseline. May be negative to lower the text.
169 Note: In Pango conformance mode, "rise" does not accumulate.
171 Use "baseline_shift" instead.
172 rise="NUM"pt rise="NUM"%
174 Rises the text from the baseline. May be negative to lower the
175 text.
176 Units are points if postfixed by pt, and a percentage of the
178 current font size if postfixed by %.
179 Note: This is not (yet?) part of the Pango markup standard.
181 baseline_shift="NUM" beseline_shift="NUM"pt baseline_shift="NUM"%
183 Like "rise", but accumulates.
184 Also supported but not part of the official Pango Markup specification.
186 href=""URL""
188 Creates a clickable target that activates the URL.
189 Shortcuts
191 Equivalent "span" attributes for shortcuts.
192 b weight=bold
194 big larger
196 emp style=italic
198 i style=italic
200 s strikethrough=true
202 small size=smaller
204 strong weight=bold
206 sub size=smaller rise=-30%
208 sup size=smaller rise=30%
210 tt face=monospace
212 u underline=single
214
216 new( $pdf )
217 Creates a new layout instance for PDF::API2. This is for
218 convenience. It is equivalent to
219 use Text::Layout::PDFAPI2;
221 $layout = Text::Layout::PDFAPI2->new($pdf);
222 For other implementations only the above method can be used.
224 The argument is the context for text formatting. In the case of
226 PDF::API2 this will be a PDF::API2 object.
227 copy
229 Copies (clones) a layout instance.
230 The content is copied deeply, the context and fonts are copied by
232 reference.
233 get_context
235 Gets the context of this layout.
236 context_changed
238 Not supported.
239 get_serial
241 Not supported.
242 set_text( $text )
244 Puts a string in this layout instance. No markup is processed.
245 Note that if you have used set_markup() on this layout before, you
247 may want to call set_attributes() to clear the attributes set on
248 the layout from the markup as this function does not clear all
249 attributes.
250 get_text
252 Gets the content of this layout instance as a single string.
253 Markup is ignored.
254 Returns undef if no text has been set.
256 get_character_count
258 Returns the number of characters in the text of this layout.
259 Basically the same as length of get_text().
261 Returns undef if no text has been set.
263 set_markup( $string )
265 Puts a string in this layout instance.
266 The string can contain Pango-compatible markup. See
268 <https://developer.gnome.org/pygtk/stable/pango-markup-language.html>.
269 Implementation note: Although all markup is parsed, not all is
271 implemented.
272 set_markup_with_accel
274 Not supported.
275 set_attributes
277 get_attributes
278 Not yet implemented.
279 set_font_description( $description )
281 Sets the default font description for the layout. If no font
282 description is set on the layout, the font description from the
283 layout's context is used.
284 $description is a Text::Layout::FontConfig object.
286 get_font_description
288 Gets the font description for the layout.
289 Returns undef if no font has been set yet.
291 set_width( $width )
293 Sets the width to which the lines of the layout should align, wrap
294 or ellipsized. A value of zero or less means unlimited width. The
295 width is in Pango units.
296 Implementation note: Only alignment is implemented.
298 get_width
300 Gets the width in Pango units for for this instance, or zero if
301 unlimited.
302 set_height( $height )
304 Sets the height in Pango units for this instance.
305 Implementation note: Height restrictions are not yet implemented.
307 get_height
309 Gets the height in Pango units for this instance, or zero if no
310 height restrictions apply.
311 set_wrap( $mode )
313 Sets the wrap mode; the wrap mode only has effect if a width is set
314 on the layout with set_width(). To turn off wrapping, set the width
315 to zero or less.
316 Not yet implemented.
318 get_wrap
320 Returns the current wrap mode.
321 Not yet implemented.
323 is_wrapped
325 Queries whether the layout had to wrap any paragraphs.
326 set_ellipsize( $mode )
328 Sets the type of ellipsization being performed for the layout.
329 Not yet implemented.
331 get_ellipsize
333 Gets the type of ellipsization being performed for the layout.
334 is_ellipsized
336 Queries whether the layout had to ellipsize any paragraphs.
337 Not yet implemented.
339 set_indent( $value )
341 Sets the width in Pango units to indent for each paragraph.
342 A negative value of indent will produce a hanging indentation. That
344 is, the first line will have the full width, and subsequent lines
345 will be indented by the absolute value of indent.
346 The indent setting is ignored if layout alignment is set to
348 "center".
349 Not yet implemented.
351 get_indent
353 Gets the current indent value in Pango units.
354 set_spacing( $value )
356 Sets the amount of spacing, in Pango units, between lines of the
357 layout.
358 When placing lines with spacing, things are arranged so that
360 line2.top = line1.bottom + spacing
362 Note: By default the line height (as determined by the font) for
364 placing lines is used. The spacing set with this function is only
365 taken into account when the line-height factor is set to zero with
366 set_line_spacing().
367 Not yet implemented.
369 get_spacing
371 Gets the current amount of spacing, in Pango units.
372 set_line_spacing( $factor )
374 Sets a factor for line spacing. Typical values are: 0, 1, 1.5, 2.
375 The default value is 0.
376 If factor is non-zero, lines are placed so that
378 baseline2 = baseline1 + factor * height2
380 where height2 is the line height of the second line (as determined
382 by the font(s)). In this case, the spacing set with set_spacing()
383 is ignored.
384 If factor is zero, spacing is applied as before.
386 Not yet implemented.
388 get_line_spacing
390 Gets the current line spacing factor.
391 set_justify( $state )
393 Sets whether each complete line should be stretched to fill the
394 entire width of the layout. This stretching is typically done by
395 adding whitespace.
396 Not yet implemented.
398 get_justify
400 Gets whether each complete line should be stretched to fill the
401 entire width of the layout.
402 set_auto_dir( $state )
404 get_auto_dir
405 Not supported.
406 set_alignment( $align )
408 Sets the alignment for the layout: how partial lines are positioned
409 within the horizontal space available.
410 $align must be one of "left", "center", or "right",
412 get_alignment
414 Gets the alignment for this instance.
415 set_tabs( $stops )
417 get_tabs
418 Not yet implemented.
419 set_single_paragraph_mode( $state )
421 get_single_paragraph_mode
422 Not yet implemented.
423 get_unknown_glyphs_count
425 Counts the number unknown glyphs in the layout.
426 Not yet implemented.
428 get_log_attrs
430 get_log_attrs_readonly
431 Not implemented.
432 index_to_pos( $index )
434 Converts from a character index within the layout to the onscreen
435 position corresponding to the grapheme at that index, which is
436 represented as rectangle.
437 Not yet implemented.
439 index_to_line_x ( $index )
441 Converts from a character index within the layout to line and X
442 position.
443 Not yet implemented.
445 xy_to_index ( $x, $y )
447 Converts from $x,$y position to a character index within the
448 layout.
449 Not yet implemented.
451 get_extents
453 Computes the logical and ink extents of the layout.
454 Logical extents are usually what you want for positioning things.
456 Return value in scalar context is a hash ref with 4 values:
458 "x", "y", "width", and "height" describing the logical extents of
459 the layout. In list context an array of two hashrefs is returned.
460 The first reflects the ink extents, the second the logical extents.
461 In the extents, "x" will reflect the offset when text is centered
463 or right aligned. It will be zero for left aligned text. For right
464 aligned text, it will be the width of the layout.
465 "y" will reflect the offset when text is centered vertically or
467 bottom aligned. It will be zero for top aligned text.
468 See also get_pixel_extents below.
470 Implementation note: If the PDF::API support layer cannot calculate
472 ink, this function returns two identical extents.
473 get_pixel_extents
475 Same as get_extents, but using device units.
476 The returned values are suitable for (assuming $pdf_text and
478 $pdf_gfx are the PDF text and graphics contexts):
479 $layout->render( $x, $y, $pdf_text );
481 $box = $layout->get_pixel_extents;
482 $pdf_gfx->translate( $x, $y );
483 $pdf_gfx->rect( @$box{ qw( x y width height ) } );
484 $pdf_gfx->stroke;
485 get_size
487 Returns the width and height of this layout.
488 In list context, width and height are returned as an two-element
490 list. In scalar context a hashref with keys "width" and "height"
491 is returned.
492 get_pixel_size
494 Same as get_size().
495 get_iter
497 Returns the layout for the first line.
498 Implementation note: This is a dummy, it returns the layout. It is
500 provided so you can write $layout->get_iter()->get_baseline() to be
501 compatible with the official Pango API.
502 get_baseline
504 Gets the Y position of the baseline of the first line in this
505 layout.
506 Implementation note: Position is relative to top left, so due to
508 the PDF coordinate system this is a negative number.
509 Note: The Python API only supports this method on iteration
511 objects. See get_iter().
512
514 get_line_count
515 get_line( $index )
516 get_line_readonly( $index )
517 get_lines
518 get_lines_readonly
519 line_get_extents
520 line_get_pixel_entents
521 line_index_to_x
522 line_x_to_index
523 line_get_x_ranges
524 line_get_height
525 get_cursor_pos
526 move_cursor_visually
527 ADDITIONAL METHODS
529 The following methods are not part of the Pango API.
530 set_font_size( $size )
532 Sets the size for the current font.
533 get_font_size
535 Returns the size of the current font.
536 get_bbox
538 Returns the bounding box of the text, w.r.t. the (top-left) origin.
539 bb = ( bl, x, y, width, height )
541 bb[0] = baseline distance from the top.
543 bb[1] = displacement from the left, nonzero for centered and right
545 aligned text
546 bb[2] = displacement from the top, usually zero
548 bb[3] = advancewidth
550 bb[4] = height
552 Note that the bounding box will in general be equal to the font
554 bounding box except for the advancewidth.
555 NOTE: Some fonts do not include accents on capital letters in the
557 ascend.
558 If an argument is supplied and true, get_bbox() will attempt to
560 calculate the ink extents as well, and add these as another set of
561 4 elements,
562 In list context returns the array of values, in scalar context an
564 array ref.
565 show( $x, $y, $text )
567 Transfers the content of this layout instance to the designated
568 graphics environment.
569 Use this instead of Pango::Cairo::show_layout().
571 For PDF::API2, $text must be an object created by the $page->text
573 method.
574 set_pango_mode( $enable )
576 Enable/disable Pango conformance mode. See "Pango Conformance
577 Mode".
578 Returns the internal Pango scaling factor if enabled.
580 get_pango
582 See "Pango Conformance Mode".
583 Returns the internal Pango scaling factor if conformance mode is
585 enabled, otherwise it returns 1 (one).
586
588 Description of the Pango Markup Language:
589 <https://docs.gtk.org/Pango/pango_markup.html#pango-markup>.
590 Documentation of the Pango Layout class:
592 <https://docs.gtk.org/Pango/class.Layout.html>.
593 PDF::API2, PDF::Builder, HarfBuzz::Shaper, Font::TTF.
595
597 Johan Vromans, "<JV at CPAN dot org>"
598
600 Development of this module takes place on GitHub:
601 <https://github.com/sciurius/perl-Text-Layout>.
602 You can find documentation for this module with the perldoc command.
604 perldoc Text::Layout
606 Please report any bugs or feature requests using the issue tracker on
608 GitHub.
609
611 Copyright (C) 2019, Johan Vromans
612 This module is free software. You can redistribute it and/or modify it
614 under the terms of the Artistic License 2.0.
615 This program is distributed in the hope that it will be useful, but
617 without any warranty; without even the implied warranty of
618 merchantability or fitness for a particular purpose.
619
621 Hey! The above document had some coding errors, which are explained
622 below:
623 Around line 147:
625 Non-ASCII character seen before =encoding in '‘12.5pt’),'. Assuming
626 UTF-8
627perl v5.36.0 2022-09-03 Text::Layout(3)