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 $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 # Center text.
45 $layout->set_width(595); # width of A4 page
46 $layout->set_alignment("center");
47 # Render it.
49 $layout->show( 0, 600, $ctx );
50 $pdf->saveas("out.pdf");
51 All PDF::API2 graphic and text methods can still be used, they won't
53 interfere with the layout methods.
54
56 Baselines
57 PDF::API2 and PDF::Builder render texts using the font baseline as
58 origin.
59 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 PDF::API2 and PDF::Builder coordinates have origin bottom left. This
66 module produces information with respect to top left coordinates.
67
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 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 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 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 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 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 DBD: Is this really a good idea?
97
99 new( $pdf )
100 Creates a new layout instance for PDF::API2. This is for
101 convenience. It is equivalent to
102 use Text::Layout::PDFAPI2;
104 $layout = Text::Layout::PDFAPI2->new($pdf);
105 For other implementations only the above method can be used.
107 The argument is the context for text formatting. In the case of
109 PDF::API2 this will be a PDF::API2 object.
110 copy
112 Copies (clones) a layout instance.
113 The content is copied deeply, the context and fonts are copied by
115 reference.
116 get_context
118 Gets the context of this layout.
119 context_changed
121 Not supported.
122 get_serial
124 Not supported.
125 set_text( $text )
127 Puts a string in this layout instance. No markup is processed.
128 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 get_text
135 Gets the content of this layout instance as a single string.
136 Markup is ignored.
137 Returns undef if no text has been set.
139 get_character_count
141 Returns the number of characters in the text of this layout.
142 Basically the same as length of get_text().
144 Returns undef if no text has been set.
146 set_markup( $string )
148 Puts a string in this layout instance.
149 The string can contain Pango-compatible markup. See
151 <https://developer.gnome.org/pygtk/stable/pango-markup-language.html>.
152 Implementation note: Although all markup is parsed, not all is
154 implemented.
155 set_markup_with_accel
157 Not supported.
158 set_attributes
160 get_attributes
161 Not yet implemented.
162 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 $description is a Text::Layout::FontConfig object.
169 get_font_description
171 Gets the font description for the layout.
172 Returns undef if no font has been set yet.
174 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 Implementation note: Only alignment is implemented.
181 get_width
183 Gets the width in Pango units for for this instance, or zero if
184 unlimited.
185 set_height( $height )
187 Sets the height in Pango units for this instance.
188 Implementation note: Height restrictions are not yet implemented.
190 get_height
192 Gets the height in Pango units for this instance, or zero if no
193 height restrictions apply.
194 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 Not yet implemented.
201 get_wrap
203 Returns the current wrap mode.
204 Not yet implemented.
206 is_wrapped
208 Queries whether the layout had to wrap any paragraphs.
209 set_ellipsize( $mode )
211 Sets the type of ellipsization being performed for the layout.
212 Not yet implemented.
214 get_ellipsize
216 Gets the type of ellipsization being performed for the layout.
217 is_ellipsized
219 Queries whether the layout had to ellipsize any paragraphs.
220 Not yet implemented.
222 set_indent( $value )
224 Sets the width in Pango units to indent for each paragraph.
225 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 The indent setting is ignored if layout alignment is set to
231 "center".
232 Not yet implemented.
234 get_indent
236 Gets the current indent value in Pango units.
237 set_spacing( $value )
239 Sets the amount of spacing, in Pango units, between lines of the
240 layout.
241 When placing lines with spacing, things are arranged so that
243 line2.top = line1.bottom + spacing
245 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 Not yet implemented.
252 get_spacing
254 Gets the current amount of spacing, in Pango units.
255 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 If factor is non-zero, lines are placed so that
261 baseline2 = baseline1 + factor * height2
263 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 If factor is zero, spacing is applied as before.
269 Not yet implemented.
271 get_line_spacing
273 Gets the current line spacing factor.
274 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 Not yet implemented.
281 get_justify
283 Gets whether each complete line should be stretched to fill the
284 entire width of the layout.
285 set_auto_dir( $state )
287 get_auto_dir
288 Not supported.
289 set_alignment( $align )
291 Sets the alignment for the layout: how partial lines are positioned
292 within the horizontal space available.
293 $align must be one of "left", "center", or "right",
295 get_alignment
297 Gets the alignment for this instance.
298 set_tabs( $stops )
300 get_tabs
301 Not yet implemented.
302 set_single_paragraph_mode( $state )
304 get_single_paragraph_mode
305 Not yet implemented.
306 get_unknown_glyphs_count
308 Counts the number unknown glyphs in the layout.
309 Not yet implemented.
311 get_log_attrs
313 get_log_attrs_readonly
314 Not implemented.
315 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 Not yet implemented.
322 index_to_line_x ( $index )
324 Converts from a character index within the layout to line and X
325 position.
326 Not yet implemented.
328 xy_to_index ( $x, $y )
330 Converts from $x,$y position to a character index within the
331 layout.
332 Not yet implemented.
334 get_extents
336 Computes the logical and ink extents of the layout.
337 Logical extents are usually what you want for positioning things.
339 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 "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 "y" will reflect the offset when text is centered vertically or
350 bottom aligned. It will be zero for top aligned text.
351 Implementation note: Since the PDF::API support layer cannot
353 calculate ink, this function returns two identical extents.
354 get_pixel_extents
356 Same as get_extents, but using device units.
357 get_size
359 Returns the width and height of this layout.
360 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 get_pixel_size
366 Same as get_size().
367 get_iter
369 Returns the layout for the first line.
370 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 get_baseline
376 Gets the Y position of the baseline of the first line in this
377 layout.
378 Implementation note: Position is relative to top left, so due to
380 the PDF coordinate system this is a negative number.
381 Note: The Python API only supports this method on iteration
383 objects. See get_iter().
384
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 ADDITIONAL METHODS
401 The following methods are not part of the Pango API.
402 set_font_size( $size )
404 Sets the size for the current font.
405 get_font_size
407 Returns the size of the current font.
408 NOTE: This is not a Pango API method.
410 get_bbox
412 Returns the bounding box of the text, w.r.t. the origin.
413 +-----------+ ascend
415 | |
416 | |
417 | |
418 | |
419 | |
420 | <-width-> |
421 | |
422 | |
423 o-----------+ o = origin baseline
424 | |
425 | |
426 +-----------+ descend
427 bb = ( left, descend, right, ascend )
429 bb[0] = left is nonzero for centered and right aligned text
431 bb[1] = descend is a negative value
433 bb[2] - bb[0] = advancewidth
435 bb[2] = layout width for right aligned text
437 bb[3] = ascend is a positive value
439 NOTE: Some fonts do not include accents on capital letters in the
441 ascend.
442 show( $x, $y, $text )
444 Transfers the content of this layout instance to the designated
445 graphics environment.
446 Use this instead of Pango::Cairo::show_layout().
448 For PDF::API2, $text must be an object created by the $page->text
450 method.
451 set_pango_scale( $scale )
453 Sets the pango scaling to $scale, which should be 1000.
454 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
459 Description of the Pango Markup Language:
460 <https://developer.gnome.org/pygtk/stable/pango-markup-language.html>.
461 Documentation of the Pango Layout class:
463 <https://developer.gnome.org/pango/stable/pango-Layout-Objects.html>.
464 PDF::API2, PDF::Builder, HarfBuzz::Shaper, Font::TTF.
466
468 Johan Vromans, "<JV at CPAN dot org>"
469
471 Development of this module takes place on GitHub:
472 <https://github.com/sciurius/perl-Text-Layout>.
473 You can find documentation for this module with the perldoc command.
475 perldoc Text::Layout
477 Please report any bugs or feature requests using the issue tracker on
479 GitHub.
480
482 Copyright (C) 2019, Johan Vromans
483 This module is free software. You can redistribute it and/or modify it
485 under the terms of the Artistic License 2.0.
486 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.
490perl v5.34.0 2021-08-21 Text::Layout(3)