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           # This example uses PDF corefonts only.
42           Text::Layout::FontConfig->register_corefonts;
43
44           $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
47           # Center text.
48           $layout->set_width(595);    # width of A4 page
49           $layout->set_alignment("center");
50
51           # Render it.
52           $layout->show( 0, 600, $ctx );
53           $pdf->saveas("out.pdf");
54
55       All PDF::API2 graphic and text methods can still be used, they won't
56       interfere with the layout methods.
57

NOTES FOR PDF::API2/Builder USERS

59   Baselines
60       PDF::API2 and PDF::Builder render texts using the font baseline as
61       origin.
62
63       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
68       PDF::API2 and PDF::Builder coordinates have origin bottom left. This
69       module produces information with respect to top left coordinates.
70

IMPORTANT NOTES FOR PANGO USERS

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
77       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

Pango Conformance Mode

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
86   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
90       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
94       In convenience mode, this module assumes no scaling. All units are PDF
95       device units (1/72 inch).
96
97   Pango device units
98       Device units are used for font rendering. Pango device units are 96dpi
99       while PDF uses 72dpi.
100
101       In convenience mode this is ignored. E.g. a "Times 20" font will be of
102       equal size in the two systems,
103
104       In Pango conformance mode you would need to specify a font size of
105       15360 to get a 20pt font.
106

SUPPORTED MARKUP

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
112   Span attributes
113       font="DESC"   font_desc="DESC"
114               Specifies a font to be used, e.g. "Serif 20".
115
116       font_face="FAM"   face="FAM"
117               Specifies a font family to be used.
118
119       font_family="FAM"
120               Same as font_face="FAM".
121
122       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
127               Note that in Pango conformance mode, the actual font size is
128               96/72 larger. So "45pt" gives a 60pt font.
129
130       style="STYLE"   font_style="STYLE"
131               Specifes the font style, e.g. "italic".
132
133       weight="WEIGHT"   font_weight="WEIGHT"
134               Specifies the font weight, e.g. "bold".
135
136       foreground="COLOR"   fgcolor="COLOR"   color="COLOR"
137               Specifies the foreground colour, e.g. "black".
138
139       background="COLOR"   bgcolor="COLOR"
140               Specifies the background colour, e.g. "white".
141
142       underline="TYPE"
143               Enables underlining.  TYPE must be "none", "single", or
144               "double".
145
146       underline_color="COLOR"
147               The colour to be used for underlining, if enabled.
148
149       overline="TYPE"
150               Enables overlining.  TYPE must be "none", "single", or
151               "double".
152
153       overline_color="COLOR"
154               The colour to be used for ovderlining, if enabled.
155
156       strikethrough="ARG"
157               Enables or diables overlining. ARG must be "true" or 1 to
158               enable, and "false" or 0 to disable.
159
160       strikethrough_color="COLOR"
161               The colour to be used for striking, if enabled.
162
163       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
167               In Pango conformance mode, rises the text by NUM units from the
168               baseline.  May be negative to lower the text.
169
170               Note: In Pango conformance mode, "rise" does not accumulate.
171                Use "baseline_shift" instead.
172
173       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
177               Units are points if postfixed by pt, and a percentage of the
178               current font size if postfixed by %.
179
180               em units are equal to the current font size, ex half the font
181               size.
182
183               Note: This is not (yet?) part of the Pango markup standard.
184
185       baseline_shift="NUM"   beseline_shift="NUM"pt   baseline_shift="NUM"%
186               Like "rise", but accumulates.
187
188       Also supported but not part of the official Pango Markup specification.
189
190       href=""URL""
191               Creates a clickable target that activates the URL.
192
193   Shortcuts
194       Equivalent "span" attributes for shortcuts.
195
196       b       weight=bold
197
198       big     larger
199
200       emp     style=italic
201
202       i       style=italic
203
204       s       strikethrough=true
205
206       small   size=smaller
207
208       strong  weight=bold
209
210       sub     size=smaller rise=-30%
211
212       sup     size=smaller rise=30%
213
214       tt      face=monospace
215
216       u       underline=single
217

METHODS

219       new( $pdf )
220           Creates a new layout instance for PDF::API2. This is for
221           convenience.  It is equivalent to
222
223               use Text::Layout::PDFAPI2;
224               $layout = Text::Layout::PDFAPI2->new($pdf);
225
226           For other implementations only the above method can be used.
227
228           The argument is the context for text formatting. In the case of
229           PDF::API2 this will be a PDF::API2 object.
230
231       copy
232           Copies (clones) a layout instance.
233
234           The content is copied deeply, the context and fonts are copied by
235           reference.
236
237       get_context
238           Gets the context of this layout.
239
240       context_changed
241           Not supported.
242
243       get_serial
244           Not supported.
245
246       set_text( $text )
247           Puts a string in this layout instance. No markup is processed.
248
249           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
254       get_text
255           Gets the content of this layout instance as a single string.
256           Markup is ignored.
257
258           Returns undef if no text has been set.
259
260       get_character_count
261           Returns the number of characters in the text of this layout.
262
263           Basically the same as length of get_text().
264
265           Returns undef if no text has been set.
266
267       set_markup( $string )
268           Puts a string in this layout instance.
269
270           The string can contain Pango-compatible markup. See
271           <https://developer.gnome.org/pygtk/stable/pango-markup-language.html>.
272
273           Implementation note: Although all markup is parsed, not all is
274           implemented.
275
276       set_markup_with_accel
277           Not supported.
278
279       set_attributes
280       get_attributes
281           Not yet implemented.
282
283       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
288           $description is a Text::Layout::FontConfig object.
289
290       get_font_description
291           Gets the font description for the layout.
292
293           Returns undef if no font has been set yet.
294
295       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
300           Implementation note: Only alignment is implemented.
301
302       get_width
303           Gets the width in Pango units for for this instance, or zero if
304           unlimited.
305
306       set_height( $height )
307           Sets the height in Pango units for this instance.
308
309           Implementation note: Height restrictions are not yet implemented.
310
311       get_height
312           Gets the height in Pango units for this instance, or zero if no
313           height restrictions apply.
314
315       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
320           Not yet implemented.
321
322       get_wrap
323           Returns the current wrap mode.
324
325           Not yet implemented.
326
327       is_wrapped
328           Queries whether the layout had to wrap any paragraphs.
329
330       set_ellipsize( $mode )
331           Sets the type of ellipsization being performed for the layout.
332
333           Not yet implemented.
334
335       get_ellipsize
336           Gets the type of ellipsization being performed for the layout.
337
338       is_ellipsized
339           Queries whether the layout had to ellipsize any paragraphs.
340
341           Not yet implemented.
342
343       set_indent( $value )
344           Sets the width in Pango units to indent for each paragraph.
345
346           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
350           The indent setting is ignored if layout alignment is set to
351           "center".
352
353           Not yet implemented.
354
355       get_indent
356           Gets the current indent value in Pango units.
357
358       set_spacing( $value )
359           Sets the amount of spacing, in Pango units, between lines of the
360           layout.
361
362           When placing lines with spacing, things are arranged so that
363
364               line2.top = line1.bottom + spacing
365
366           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
371           Not yet implemented.
372
373       get_spacing
374           Gets the current amount of spacing, in Pango units.
375
376       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
380           If factor is non-zero, lines are placed so that
381
382               baseline2 = baseline1 + factor * height2
383
384           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
388           If factor is zero, spacing is applied as before.
389
390           Not yet implemented.
391
392       get_line_spacing
393           Gets the current line spacing factor.
394
395       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
400           Not yet implemented.
401
402       get_justify
403           Gets whether each complete line should be stretched to fill the
404           entire width of the layout.
405
406       set_auto_dir( $state )
407       get_auto_dir
408           Not supported.
409
410       set_alignment( $align )
411           Sets the alignment for the layout: how partial lines are positioned
412           within the horizontal space available.
413
414           $align must be one of "left", "center", or "right",
415
416       get_alignment
417           Gets the alignment for this instance.
418
419       set_tabs( $stops )
420       get_tabs
421           Not yet implemented.
422
423       set_single_paragraph_mode( $state )
424       get_single_paragraph_mode
425           Not yet implemented.
426
427       get_unknown_glyphs_count
428           Counts the number unknown glyphs in the layout.
429
430           Not yet implemented.
431
432       get_log_attrs
433       get_log_attrs_readonly
434           Not implemented.
435
436       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
441           Not yet implemented.
442
443       index_to_line_x ( $index )
444           Converts from a character index within the layout to line and X
445           position.
446
447           Not yet implemented.
448
449       xy_to_index ( $x, $y )
450           Converts from $x,$y position to a character index within the
451           layout.
452
453           Not yet implemented.
454
455       get_extents
456           Computes the logical and ink extents of the layout.
457
458           Logical extents are usually what you want for positioning things.
459
460           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
465           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
469           "y" will reflect the offset when text is centered vertically or
470           bottom aligned. It will be zero for top aligned text.
471
472           See also get_pixel_extents below.
473
474           Implementation note: If the PDF::API support layer cannot calculate
475           ink, this function returns two identical extents.
476
477       get_pixel_extents
478           Same as get_extents, but using device units.
479
480           The returned values are suitable for (assuming $pdf_text and
481           $pdf_gfx are the PDF text and graphics contexts):
482
483               $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
489       get_size
490           Returns the width and height of this layout.
491
492           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
496       get_pixel_size
497           Same as get_size().
498
499       get_iter
500           Returns the layout for the first line.
501
502           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
506       get_baseline
507           Gets the Y position of the baseline of the first line in this
508           layout.
509
510           Implementation note: Position is relative to top left, so due to
511           the PDF coordinate system this is a negative number.
512
513           Note: The Python API only supports this method on iteration
514           objects.  See get_iter().
515

METHODS NOT IMPLEMENTED

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
531   ADDITIONAL METHODS
532       The following methods are not part of the Pango API.
533
534       set_font_size( $size )
535           Sets the size for the current font.
536
537       get_font_size
538           Returns the size of the current font.
539
540       get_bbox
541           Returns the bounding box of the text, w.r.t. the (top-left) origin.
542
543           bb = ( bl, x, y, width, height )
544
545           bb[0] = baseline distance from the top.
546
547           bb[1] = displacement from the left, nonzero for centered and right
548           aligned text
549
550           bb[2] = displacement from the top, usually zero
551
552           bb[3] = advancewidth
553
554           bb[4] = height
555
556           Note that the bounding box will in general be equal to the font
557           bounding box except for the advancewidth.
558
559           NOTE: Some fonts do not include accents on capital letters in the
560           ascend.
561
562           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
566           In list context returns the array of values, in scalar context an
567           array ref.
568
569       show( $x, $y, $text )
570           Transfers the content of this layout instance to the designated
571           graphics environment.
572
573           Use this instead of Pango::Cairo::show_layout().
574
575           For PDF::API2, $text must be an object created by the $page->text
576           method.
577
578       set_pango_mode( $enable )
579           Enable/disable Pango conformance mode.  See "Pango Conformance
580           Mode".
581
582           Returns the internal Pango scaling factor if enabled.
583
584       get_pango
585           See "Pango Conformance Mode".
586
587           Returns the internal Pango scaling factor if conformance mode is
588           enabled, otherwise it returns 1 (one).
589

SEE ALSO

591       Description of the Pango Markup Language:
592       <https://docs.gtk.org/Pango/pango_markup.html#pango-markup>.
593
594       Documentation of the Pango Layout class:
595       <https://docs.gtk.org/Pango/class.Layout.html>.
596
597       PDF::API2, PDF::Builder, HarfBuzz::Shaper, Font::TTF.
598

AUTHOR

600       Johan Vromans, "<JV at CPAN dot org>"
601

SUPPORT

603       Development of this module takes place on GitHub:
604       <https://github.com/sciurius/perl-Text-Layout>.
605
606       You can find documentation for this module with the perldoc command.
607
608         perldoc Text::Layout
609
610       Please report any bugs or feature requests using the issue tracker on
611       GitHub.
612

LICENSE

614       Copyright (C) 2019, Johan Vromans
615
616       This module is free software. You can redistribute it and/or modify it
617       under the terms of the Artistic License 2.0.
618
619       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

POD ERRORS

624       Hey! The above document had some coding errors, which are explained
625       below:
626
627       Around line 147:
628           Non-ASCII character seen before =encoding in '‘12.5pt’),'. Assuming
629           UTF-8
630
631
632
633perl v5.36.1                      2023-11-01                   Text::Layout(3)
Impressum