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: "rise" does not accumulate. Use "baseline_shift" instead.
171 rise="NUM"pt rise="NUM"%
173 Rises the text from the baseline. May be negative to lower the
174 text.
175 Units are points if postfixed by pt, and a percentage of the
177 current font size if postfixed by %.
178 Note: This is not (yet?) part of the Pango markup standard.
180 baseline_shift="NUM" beseline_shift="NUM"pt baseline_shift="NUM"%
182 Like "rise", but accumulates.
183 Also supported but not part of the official Pango Markup specification.
185 href=""URL""
187 Creates a clickable target that activates the URL.
188 Shortcuts
190 Equivalent "span" attributes for shortcuts.
191 b weight=bold
193 big larger
195 emp style=italic
197 i style=italic
199 s strikethrough=true
201 small size=smaller
203 strong weight=bold
205 sub size=smaller rise=-30%
207 sup size=smaller rise=30%
209 tt face=monospace
211 u underline=single
213
215 new( $pdf )
216 Creates a new layout instance for PDF::API2. This is for
217 convenience. It is equivalent to
218 use Text::Layout::PDFAPI2;
220 $layout = Text::Layout::PDFAPI2->new($pdf);
221 For other implementations only the above method can be used.
223 The argument is the context for text formatting. In the case of
225 PDF::API2 this will be a PDF::API2 object.
226 copy
228 Copies (clones) a layout instance.
229 The content is copied deeply, the context and fonts are copied by
231 reference.
232 get_context
234 Gets the context of this layout.
235 context_changed
237 Not supported.
238 get_serial
240 Not supported.
241 set_text( $text )
243 Puts a string in this layout instance. No markup is processed.
244 Note that if you have used set_markup() on this layout before, you
246 may want to call set_attributes() to clear the attributes set on
247 the layout from the markup as this function does not clear all
248 attributes.
249 get_text
251 Gets the content of this layout instance as a single string.
252 Markup is ignored.
253 Returns undef if no text has been set.
255 get_character_count
257 Returns the number of characters in the text of this layout.
258 Basically the same as length of get_text().
260 Returns undef if no text has been set.
262 set_markup( $string )
264 Puts a string in this layout instance.
265 The string can contain Pango-compatible markup. See
267 <https://developer.gnome.org/pygtk/stable/pango-markup-language.html>.
268 Implementation note: Although all markup is parsed, not all is
270 implemented.
271 set_markup_with_accel
273 Not supported.
274 set_attributes
276 get_attributes
277 Not yet implemented.
278 set_font_description( $description )
280 Sets the default font description for the layout. If no font
281 description is set on the layout, the font description from the
282 layout's context is used.
283 $description is a Text::Layout::FontConfig object.
285 get_font_description
287 Gets the font description for the layout.
288 Returns undef if no font has been set yet.
290 set_width( $width )
292 Sets the width to which the lines of the layout should align, wrap
293 or ellipsized. A value of zero or less means unlimited width. The
294 width is in Pango units.
295 Implementation note: Only alignment is implemented.
297 get_width
299 Gets the width in Pango units for for this instance, or zero if
300 unlimited.
301 set_height( $height )
303 Sets the height in Pango units for this instance.
304 Implementation note: Height restrictions are not yet implemented.
306 get_height
308 Gets the height in Pango units for this instance, or zero if no
309 height restrictions apply.
310 set_wrap( $mode )
312 Sets the wrap mode; the wrap mode only has effect if a width is set
313 on the layout with set_width(). To turn off wrapping, set the width
314 to zero or less.
315 Not yet implemented.
317 get_wrap
319 Returns the current wrap mode.
320 Not yet implemented.
322 is_wrapped
324 Queries whether the layout had to wrap any paragraphs.
325 set_ellipsize( $mode )
327 Sets the type of ellipsization being performed for the layout.
328 Not yet implemented.
330 get_ellipsize
332 Gets the type of ellipsization being performed for the layout.
333 is_ellipsized
335 Queries whether the layout had to ellipsize any paragraphs.
336 Not yet implemented.
338 set_indent( $value )
340 Sets the width in Pango units to indent for each paragraph.
341 A negative value of indent will produce a hanging indentation. That
343 is, the first line will have the full width, and subsequent lines
344 will be indented by the absolute value of indent.
345 The indent setting is ignored if layout alignment is set to
347 "center".
348 Not yet implemented.
350 get_indent
352 Gets the current indent value in Pango units.
353 set_spacing( $value )
355 Sets the amount of spacing, in Pango units, between lines of the
356 layout.
357 When placing lines with spacing, things are arranged so that
359 line2.top = line1.bottom + spacing
361 Note: By default the line height (as determined by the font) for
363 placing lines is used. The spacing set with this function is only
364 taken into account when the line-height factor is set to zero with
365 set_line_spacing().
366 Not yet implemented.
368 get_spacing
370 Gets the current amount of spacing, in Pango units.
371 set_line_spacing( $factor )
373 Sets a factor for line spacing. Typical values are: 0, 1, 1.5, 2.
374 The default value is 0.
375 If factor is non-zero, lines are placed so that
377 baseline2 = baseline1 + factor * height2
379 where height2 is the line height of the second line (as determined
381 by the font(s)). In this case, the spacing set with set_spacing()
382 is ignored.
383 If factor is zero, spacing is applied as before.
385 Not yet implemented.
387 get_line_spacing
389 Gets the current line spacing factor.
390 set_justify( $state )
392 Sets whether each complete line should be stretched to fill the
393 entire width of the layout. This stretching is typically done by
394 adding whitespace.
395 Not yet implemented.
397 get_justify
399 Gets whether each complete line should be stretched to fill the
400 entire width of the layout.
401 set_auto_dir( $state )
403 get_auto_dir
404 Not supported.
405 set_alignment( $align )
407 Sets the alignment for the layout: how partial lines are positioned
408 within the horizontal space available.
409 $align must be one of "left", "center", or "right",
411 get_alignment
413 Gets the alignment for this instance.
414 set_tabs( $stops )
416 get_tabs
417 Not yet implemented.
418 set_single_paragraph_mode( $state )
420 get_single_paragraph_mode
421 Not yet implemented.
422 get_unknown_glyphs_count
424 Counts the number unknown glyphs in the layout.
425 Not yet implemented.
427 get_log_attrs
429 get_log_attrs_readonly
430 Not implemented.
431 index_to_pos( $index )
433 Converts from a character index within the layout to the onscreen
434 position corresponding to the grapheme at that index, which is
435 represented as rectangle.
436 Not yet implemented.
438 index_to_line_x ( $index )
440 Converts from a character index within the layout to line and X
441 position.
442 Not yet implemented.
444 xy_to_index ( $x, $y )
446 Converts from $x,$y position to a character index within the
447 layout.
448 Not yet implemented.
450 get_extents
452 Computes the logical and ink extents of the layout.
453 Logical extents are usually what you want for positioning things.
455 Return value in scalar context is a hash ref with 4 values:
457 "x", "y", "width", and "height" describing the logical extents of
458 the layout. In list context an array of two hashrefs is returned.
459 The first reflects the ink extents, the second the logical extents.
460 In the extents, "x" will reflect the offset when text is centered
462 or right aligned. It will be zero for left aligned text. For right
463 aligned text, it will be the width of the layout.
464 "y" will reflect the offset when text is centered vertically or
466 bottom aligned. It will be zero for top aligned text.
467 See also get_pixel_extents below.
469 Implementation note: If the PDF::API support layer cannot calculate
471 ink, this function returns two identical extents.
472 get_pixel_extents
474 Same as get_extents, but using device units.
475 The returned values are suitable for (assuming $pdf_text and
477 $pdf_gfx are the PDF text and graphics contexts):
478 $layout->render( $x, $y, $pdf_text );
480 $box = $layout->get_pixel_extents;
481 $pdf_gfx->translate( $x, $y );
482 $pdf_gfx->rect( @$box{ qw( x y width height ) } );
483 $pdf_gfx->stroke;
484 get_size
486 Returns the width and height of this layout.
487 In list context, width and height are returned as an two-element
489 list. In scalar context a hashref with keys "width" and "height"
490 is returned.
491 get_pixel_size
493 Same as get_size().
494 get_iter
496 Returns the layout for the first line.
497 Implementation note: This is a dummy, it returns the layout. It is
499 provided so you can write $layout->get_iter()->get_baseline() to be
500 compatible with the official Pango API.
501 get_baseline
503 Gets the Y position of the baseline of the first line in this
504 layout.
505 Implementation note: Position is relative to top left, so due to
507 the PDF coordinate system this is a negative number.
508 Note: The Python API only supports this method on iteration
510 objects. See get_iter().
511
513 get_line_count
514 get_line( $index )
515 get_line_readonly( $index )
516 get_lines
517 get_lines_readonly
518 line_get_extents
519 line_get_pixel_entents
520 line_index_to_x
521 line_x_to_index
522 line_get_x_ranges
523 line_get_height
524 get_cursor_pos
525 move_cursor_visually
526 ADDITIONAL METHODS
528 The following methods are not part of the Pango API.
529 set_font_size( $size )
531 Sets the size for the current font.
532 get_font_size
534 Returns the size of the current font.
535 get_bbox
537 Returns the bounding box of the text, w.r.t. the (top-left) origin.
538 bb = ( bl, x, y, width, height )
540 bb[0] = baseline distance from the top.
542 bb[1] = displacement from the left, nonzero for centered and right
544 aligned text
545 bb[2] = displacement from the top, usually zero
547 bb[3] = advancewidth
549 bb[4] = height
551 Note that the bounding box will in general be equal to the font
553 bounding box except for the advancewidth.
554 NOTE: Some fonts do not include accents on capital letters in the
556 ascend.
557 If an argument is supplied and true, get_bbox() will attempt to
559 calculate the ink extents as well, and add these as another set of
560 4 elements,
561 In list context returns the array of values, in scalar context an
563 array ref.
564 show( $x, $y, $text )
566 Transfers the content of this layout instance to the designated
567 graphics environment.
568 Use this instead of Pango::Cairo::show_layout().
570 For PDF::API2, $text must be an object created by the $page->text
572 method.
573 set_pango_mode( $enable )
575 Enable/disable Pango conformance mode. See "Pango Conformance
576 Mode".
577 Returns the internal Pango scaling factor if enabled.
579 get_pango
581 See "Pango Conformance Mode".
582 Returns the internal Pango scaling factor if conformance mode is
584 enabled, otherwise it returns 1 (one).
585
587 Description of the Pango Markup Language:
588 <https://docs.gtk.org/Pango/pango_markup.html#pango-markup>.
589 Documentation of the Pango Layout class:
591 <https://docs.gtk.org/Pango/class.Layout.html>.
592 PDF::API2, PDF::Builder, HarfBuzz::Shaper, Font::TTF.
594
596 Johan Vromans, "<JV at CPAN dot org>"
597
599 Development of this module takes place on GitHub:
600 <https://github.com/sciurius/perl-Text-Layout>.
601 You can find documentation for this module with the perldoc command.
603 perldoc Text::Layout
605 Please report any bugs or feature requests using the issue tracker on
607 GitHub.
608
610 Copyright (C) 2019, Johan Vromans
611 This module is free software. You can redistribute it and/or modify it
613 under the terms of the Artistic License 2.0.
614 This program is distributed in the hope that it will be useful, but
616 without any warranty; without even the implied warranty of
617 merchantability or fitness for a particular purpose.
618
620 Hey! The above document had some coding errors, which are explained
621 below:
622 Around line 147:
624 Non-ASCII character seen before =encoding in '‘12.5pt’),'. Assuming
625 UTF-8
626perl v5.34.0 2022-02-04 Text::Layout(3)