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"% rise="NUM"em rise="NUM"ex
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 em units are equal to the current font size, ex half the font
181 size.
182 Note: This is not (yet?) part of the Pango markup standard.
184 baseline_shift="NUM" beseline_shift="NUM"pt baseline_shift="NUM"%
186 Like "rise", but accumulates.
187 Also supported but not part of the official Pango Markup specification.
189 href=""URL""
191 Creates a clickable target that activates the URL.
192 Shortcuts
194 Equivalent "span" attributes for shortcuts.
195 b weight=bold
197 big larger
199 emp style=italic
201 i style=italic
203 s strikethrough=true
205 small size=smaller
207 strong weight=bold
209 sub size=smaller rise=-30%
211 sup size=smaller rise=30%
213 tt face=monospace
215 u underline=single
217
219 new( $pdf )
220 Creates a new layout instance for PDF::API2. This is for
221 convenience. It is equivalent to
222 use Text::Layout::PDFAPI2;
224 $layout = Text::Layout::PDFAPI2->new($pdf);
225 For other implementations only the above method can be used.
227 The argument is the context for text formatting. In the case of
229 PDF::API2 this will be a PDF::API2 object.
230 copy
232 Copies (clones) a layout instance.
233 The content is copied deeply, the context and fonts are copied by
235 reference.
236 get_context
238 Gets the context of this layout.
239 context_changed
241 Not supported.
242 get_serial
244 Not supported.
245 set_text( $text )
247 Puts a string in this layout instance. No markup is processed.
248 Note that if you have used set_markup() on this layout before, you
250 may want to call set_attributes() to clear the attributes set on
251 the layout from the markup as this function does not clear all
252 attributes.
253 get_text
255 Gets the content of this layout instance as a single string.
256 Markup is ignored.
257 Returns undef if no text has been set.
259 get_character_count
261 Returns the number of characters in the text of this layout.
262 Basically the same as length of get_text().
264 Returns undef if no text has been set.
266 set_markup( $string )
268 Puts a string in this layout instance.
269 The string can contain Pango-compatible markup. See
271 <https://developer.gnome.org/pygtk/stable/pango-markup-language.html>.
272 Implementation note: Although all markup is parsed, not all is
274 implemented.
275 set_markup_with_accel
277 Not supported.
278 set_attributes
280 get_attributes
281 Not yet implemented.
282 set_font_description( $description )
284 Sets the default font description for the layout. If no font
285 description is set on the layout, the font description from the
286 layout's context is used.
287 $description is a Text::Layout::FontConfig object.
289 get_font_description
291 Gets the font description for the layout.
292 Returns undef if no font has been set yet.
294 set_width( $width )
296 Sets the width to which the lines of the layout should align, wrap
297 or ellipsized. A value of zero or less means unlimited width. The
298 width is in Pango units.
299 Implementation note: Only alignment is implemented.
301 get_width
303 Gets the width in Pango units for for this instance, or zero if
304 unlimited.
305 set_height( $height )
307 Sets the height in Pango units for this instance.
308 Implementation note: Height restrictions are not yet implemented.
310 get_height
312 Gets the height in Pango units for this instance, or zero if no
313 height restrictions apply.
314 set_wrap( $mode )
316 Sets the wrap mode; the wrap mode only has effect if a width is set
317 on the layout with set_width(). To turn off wrapping, set the width
318 to zero or less.
319 Not yet implemented.
321 get_wrap
323 Returns the current wrap mode.
324 Not yet implemented.
326 is_wrapped
328 Queries whether the layout had to wrap any paragraphs.
329 set_ellipsize( $mode )
331 Sets the type of ellipsization being performed for the layout.
332 Not yet implemented.
334 get_ellipsize
336 Gets the type of ellipsization being performed for the layout.
337 is_ellipsized
339 Queries whether the layout had to ellipsize any paragraphs.
340 Not yet implemented.
342 set_indent( $value )
344 Sets the width in Pango units to indent for each paragraph.
345 A negative value of indent will produce a hanging indentation. That
347 is, the first line will have the full width, and subsequent lines
348 will be indented by the absolute value of indent.
349 The indent setting is ignored if layout alignment is set to
351 "center".
352 Not yet implemented.
354 get_indent
356 Gets the current indent value in Pango units.
357 set_spacing( $value )
359 Sets the amount of spacing, in Pango units, between lines of the
360 layout.
361 When placing lines with spacing, things are arranged so that
363 line2.top = line1.bottom + spacing
365 Note: By default the line height (as determined by the font) for
367 placing lines is used. The spacing set with this function is only
368 taken into account when the line-height factor is set to zero with
369 set_line_spacing().
370 Not yet implemented.
372 get_spacing
374 Gets the current amount of spacing, in Pango units.
375 set_line_spacing( $factor )
377 Sets a factor for line spacing. Typical values are: 0, 1, 1.5, 2.
378 The default value is 0.
379 If factor is non-zero, lines are placed so that
381 baseline2 = baseline1 + factor * height2
383 where height2 is the line height of the second line (as determined
385 by the font(s)). In this case, the spacing set with set_spacing()
386 is ignored.
387 If factor is zero, spacing is applied as before.
389 Not yet implemented.
391 get_line_spacing
393 Gets the current line spacing factor.
394 set_justify( $state )
396 Sets whether each complete line should be stretched to fill the
397 entire width of the layout. This stretching is typically done by
398 adding whitespace.
399 Not yet implemented.
401 get_justify
403 Gets whether each complete line should be stretched to fill the
404 entire width of the layout.
405 set_auto_dir( $state )
407 get_auto_dir
408 Not supported.
409 set_alignment( $align )
411 Sets the alignment for the layout: how partial lines are positioned
412 within the horizontal space available.
413 $align must be one of "left", "center", or "right",
415 get_alignment
417 Gets the alignment for this instance.
418 set_tabs( $stops )
420 get_tabs
421 Not yet implemented.
422 set_single_paragraph_mode( $state )
424 get_single_paragraph_mode
425 Not yet implemented.
426 get_unknown_glyphs_count
428 Counts the number unknown glyphs in the layout.
429 Not yet implemented.
431 get_log_attrs
433 get_log_attrs_readonly
434 Not implemented.
435 index_to_pos( $index )
437 Converts from a character index within the layout to the onscreen
438 position corresponding to the grapheme at that index, which is
439 represented as rectangle.
440 Not yet implemented.
442 index_to_line_x ( $index )
444 Converts from a character index within the layout to line and X
445 position.
446 Not yet implemented.
448 xy_to_index ( $x, $y )
450 Converts from $x,$y position to a character index within the
451 layout.
452 Not yet implemented.
454 get_extents
456 Computes the logical and ink extents of the layout.
457 Logical extents are usually what you want for positioning things.
459 Return value in scalar context is a hash ref with 4 values:
461 "x", "y", "width", and "height" describing the logical extents of
462 the layout. In list context an array of two hashrefs is returned.
463 The first reflects the ink extents, the second the logical extents.
464 In the extents, "x" will reflect the offset when text is centered
466 or right aligned. It will be zero for left aligned text. For right
467 aligned text, it will be the width of the layout.
468 "y" will reflect the offset when text is centered vertically or
470 bottom aligned. It will be zero for top aligned text.
471 See also get_pixel_extents below.
473 Implementation note: If the PDF::API support layer cannot calculate
475 ink, this function returns two identical extents.
476 get_pixel_extents
478 Same as get_extents, but using device units.
479 The returned values are suitable for (assuming $pdf_text and
481 $pdf_gfx are the PDF text and graphics contexts):
482 $layout->render( $x, $y, $pdf_text );
484 $box = $layout->get_pixel_extents;
485 $pdf_gfx->translate( $x, $y );
486 $pdf_gfx->rect( @$box{ qw( x y width height ) } );
487 $pdf_gfx->stroke;
488 get_size
490 Returns the width and height of this layout.
491 In list context, width and height are returned as an two-element
493 list. In scalar context a hashref with keys "width" and "height"
494 is returned.
495 get_pixel_size
497 Same as get_size().
498 get_iter
500 Returns the layout for the first line.
501 Implementation note: This is a dummy, it returns the layout. It is
503 provided so you can write $layout->get_iter()->get_baseline() to be
504 compatible with the official Pango API.
505 get_baseline
507 Gets the Y position of the baseline of the first line in this
508 layout.
509 Implementation note: Position is relative to top left, so due to
511 the PDF coordinate system this is a negative number.
512 Note: The Python API only supports this method on iteration
514 objects. See get_iter().
515
517 get_line_count
518 get_line( $index )
519 get_line_readonly( $index )
520 get_lines
521 get_lines_readonly
522 line_get_extents
523 line_get_pixel_entents
524 line_index_to_x
525 line_x_to_index
526 line_get_x_ranges
527 line_get_height
528 get_cursor_pos
529 move_cursor_visually
530 ADDITIONAL METHODS
532 The following methods are not part of the Pango API.
533 set_font_size( $size )
535 Sets the size for the current font.
536 get_font_size
538 Returns the size of the current font.
539 get_bbox
541 Returns the bounding box of the text, w.r.t. the (top-left) origin.
542 bb = ( bl, x, y, width, height )
544 bb[0] = baseline distance from the top.
546 bb[1] = displacement from the left, nonzero for centered and right
548 aligned text
549 bb[2] = displacement from the top, usually zero
551 bb[3] = advancewidth
553 bb[4] = height
555 Note that the bounding box will in general be equal to the font
557 bounding box except for the advancewidth.
558 NOTE: Some fonts do not include accents on capital letters in the
560 ascend.
561 If an argument is supplied and true, get_bbox() will attempt to
563 calculate the ink extents as well, and add these as another set of
564 4 elements,
565 In list context returns the array of values, in scalar context an
567 array ref.
568 show( $x, $y, $text )
570 Transfers the content of this layout instance to the designated
571 graphics environment.
572 Use this instead of Pango::Cairo::show_layout().
574 For PDF::API2, $text must be an object created by the $page->text
576 method.
577 set_pango_mode( $enable )
579 Enable/disable Pango conformance mode. See "Pango Conformance
580 Mode".
581 Returns the internal Pango scaling factor if enabled.
583 get_pango
585 See "Pango Conformance Mode".
586 Returns the internal Pango scaling factor if conformance mode is
588 enabled, otherwise it returns 1 (one).
589
591 Description of the Pango Markup Language:
592 <https://docs.gtk.org/Pango/pango_markup.html#pango-markup>.
593 Documentation of the Pango Layout class:
595 <https://docs.gtk.org/Pango/class.Layout.html>.
596 PDF::API2, PDF::Builder, HarfBuzz::Shaper, Font::TTF.
598
600 Johan Vromans, "<JV at CPAN dot org>"
601
603 Development of this module takes place on GitHub:
604 <https://github.com/sciurius/perl-Text-Layout>.
605 You can find documentation for this module with the perldoc command.
607 perldoc Text::Layout
609 Please report any bugs or feature requests using the issue tracker on
611 GitHub.
612
614 Copyright (C) 2019, Johan Vromans
615 This module is free software. You can redistribute it and/or modify it
617 under the terms of the Artistic License 2.0.
618 This program is distributed in the hope that it will be useful, but
620 without any warranty; without even the implied warranty of
621 merchantability or fitness for a particular purpose.
622
624 Hey! The above document had some coding errors, which are explained
625 below:
626 Around line 147:
628 Non-ASCII character seen before =encoding in '‘12.5pt’),'. Assuming
629 UTF-8
630perl v5.38.0 2023-11-01 Text::Layout(3)