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.
101 The arguments are passed to the backend. Read its documentation.
103 copy
105 Copies (clones) a layout instance.
106 The content is copied deeply, the context and fonts are copied by
108 reference.
109 get_context
111 Gets the context (PDF document) of this layout.
112 context_changed
114 Not supported.
115 get_serial
117 Not supported.
118 set_text( $text )
120 Puts a string in this layout instance. No markup is processed.
121 Note that if you have used set_markup() on this layout before, you
123 may want to call set_attributes() to clear the attributes set on
124 the layout from the markup as this function does not clear all
125 attributes.
126 get_text
128 Gets the content of this layout instance as a single string.
129 Markup is ignored.
130 Returns undef if no text has been set.
132 get_character_count
134 Returns the number of characters in the text of this layout.
135 Basically the same as length of get_text().
137 Returns undef if no text has been set.
139 set_markup( $string )
141 Puts a string in this layout instance.
142 The string can contain Pango-compatible markup. See
144 <https://developer.gnome.org/pygtk/stable/pango-markup-language.html>.
145 Implementation note: Although all markup is parsed, not all is
147 implemented.
148 set_markup_with_accel
150 Not supported.
151 set_attributes
153 get_attributes
154 Not yet implemented.
155 set_font_description( $description )
157 Sets the default font description for the layout. If no font
158 description is set on the layout, the font description from the
159 layout's context is used.
160 $description is a Text::Layout::FontConfig object.
162 get_font_description
164 Gets the font description for the layout.
165 Returns undef if no font has been set yet.
167 set_width( $width )
169 Sets the width to which the lines of the layout should align, wrap
170 or ellipsized. A value of zero or less means unlimited width. The
171 width is in Pango units.
172 Implementation note: Only alignment is implemented.
174 get_width
176 Gets the width in Pango units for for this instance, or zero if
177 unlimited.
178 set_height( $height )
180 Sets the height in Pango units for this instance.
181 Implementation note: Height restrictions are not yet implemented.
183 get_height
185 Gets the height in Pango units for this instance, or zero if no
186 height restrictions apply.
187 set_wrap( $mode )
189 Sets the wrap mode; the wrap mode only has effect if a width is set
190 on the layout with set_width(). To turn off wrapping, set the width
191 to zero or less.
192 Not yet implemented.
194 get_wrap
196 Returns the current wrap mode.
197 Not yet implemented.
199 is_wrapped
201 Queries whether the layout had to wrap any paragraphs.
202 set_ellipsize( $mode )
204 Sets the type of ellipsization being performed for the layout.
205 Not yet implemented.
207 get_ellipsize
209 Gets the type of ellipsization being performed for the layout.
210 is_ellipsized
212 Queries whether the layout had to ellipsize any paragraphs.
213 Not yet implemented.
215 set_indent( $value )
217 Sets the width in Pango units to indent for each paragraph.
218 A negative value of indent will produce a hanging indentation. That
220 is, the first line will have the full width, and subsequent lines
221 will be indented by the absolute value of indent.
222 The indent setting is ignored if layout alignment is set to
224 "center".
225 Not yet implemented.
227 get_indent
229 Gets the current indent value in Pango units.
230 set_spacing( $value )
232 Sets the amount of spacing, in Pango units, between lines of the
233 layout.
234 When placing lines with spacing, things are arranged so that
236 line2.top = line1.bottom + spacing
238 Note: By default the line height (as determined by the font) for
240 placing lines is used. The spacing set with this function is only
241 taken into account when the line-height factor is set to zero with
242 set_line_spacing().
243 Not yet implemented.
245 get_spacing
247 Gets the current amount of spacing, in Pango units.
248 set_line_spacing( $factor )
250 Sets a factor for line spacing. Typical values are: 0, 1, 1.5, 2.
251 The default value is 0.
252 If factor is non-zero, lines are placed so that
254 baseline2 = baseline1 + factor * height2
256 where height2 is the line height of the second line (as determined
258 by the font(s)). In this case, the spacing set with set_spacing()
259 is ignored.
260 If factor is zero, spacing is applied as before.
262 Not yet implemented.
264 get_line_spacing
266 Gets the current line spacing factor.
267 set_justify( $state )
269 Sets whether each complete line should be stretched to fill the
270 entire width of the layout. This stretching is typically done by
271 adding whitespace.
272 Not yet implemented.
274 get_justify
276 Gets whether each complete line should be stretched to fill the
277 entire width of the layout.
278 set_auto_dir( $state )
280 get_auto_dir
281 Not supported.
282 set_alignment( $align )
284 Sets the alignment for the layout: how partial lines are positioned
285 within the horizontal space available.
286 $align must be one of "left", "center", or "right",
288 get_alignment
290 Gets the alignment for this instance.
291 set_tabs( $stops )
293 get_tabs
294 Not yet implemented.
295 set_single_paragraph_mode( $state )
297 get_single_paragraph_mode
298 Not yet implemented.
299 get_unknown_glyphs_count
301 Counts the number unknown glyphs in the layout.
302 Not yet implemented.
304 get_log_attrs
306 get_log_attrs_readonly
307 Not implemented.
308 index_to_pos( $index )
310 Converts from a character index within the layout to the onscreen
311 position corresponding to the grapheme at that index, which is
312 represented as rectangle.
313 Not yet implemented.
315 index_to_line_x ( $index )
317 Converts from a character index within the layout to line and X
318 position.
319 Not yet implemented.
321 xy_to_index ( $x, $y )
323 Converts from $x,$y position to a character index within the
324 layout.
325 Not yet implemented.
327 get_extents
329 Computes the logical and ink extents of the layout.
330 Logical extents are usually what you want for positioning things.
332 Return value is an array (in list context) or an array ref (in
334 scalar context) containing two hash refs with 4 values: "x", "y",
335 "width", and "height". The first reflects the ink extents, the
336 second the logical extents.
337 "x" will reflect the offset when text is centered or right aligned.
339 It will be zero for left aligned text. For right aligned text, it
340 will be the width of the layout.
341 "y" will reflect the offset when text is centered vertically or
343 bottom aligned. It will be zero for top aligned text.
344 Implementation note: Since the PDF support layer cannot calculate
346 ink, this function returns two identical extents.
347 get_pixel_extents
349 Same as get_extents, but using device units.
350 get_size
352 Returns the width and height of this layout.
353 In list context, width and height are returned as an two-element
355 list. In scalar context a hashref with keys "width" and "height"
356 is returned.
357 get_pixel_size
359 Same as get_size().
360 get_iter
362 Returns the layout for the first line.
363 Implementation note: This is a dummy, it returns the layout. It is
365 provided so you can write $layout->get_iter()->get_baseline() to be
366 compatible with the official Pango API.
367 get_baseline
369 Gets the Y position of the baseline of the first line in this
370 layout.
371 Implementation note: Position is relative to top left, so due to
373 the PDF coordinate system this is a negative number.
374 Note: The Python API only supports this method on iteration
376 objects. See get_iter().
377
379 get_line_count
380 get_line( $index )
381 get_line_readonly( $index )
382 get_lines
383 get_lines_readonly
384 line_get_extents
385 line_get_pixel_entents
386 line_index_to_x
387 line_x_to_index
388 line_get_x_ranges
389 line_get_height
390 get_cursor_pos
391 move_cursor_visually
392 ADDITIONAL METHODS
394 The following methods are not part of the Pango API.
395 set_font_size( $size )
397 Sets the size for the current font.
398 get_font_size
400 Returns the size of the current font.
401 NOTE: This is not a Pango API method.
403 get_bbox
405 Returns the bounding box of the text, w.r.t. the origin.
406 +-----------+ ascend
408 | |
409 | |
410 | |
411 | |
412 | |
413 | <-width-> |
414 | |
415 | |
416 o-----------+ o = origin baseline
417 | |
418 | |
419 +-----------+ descend
420 bb = ( left, descend, right, ascend )
422 bb[0] = left is nonzero for centered and right aligned text
424 bb[1] = descend is a negative value
426 bb[2] - bb[0] = advancewidth
428 bb[2] = layout width for right aligned text
430 bb[3] = ascend is a positive value
432 NOTE: Some fonts do not include accents on capital letters in the
434 ascend.
435 show( $x, $y, $text )
437 Transfers the content of this layout instance to the designated
438 graphics environment.
439 Use this instead of Pango::Cairo::show_layout().
441 $text must be an object created by PDF $page->text method.
443 set_pango_scale( $scale )
445 Sets the pango scaling to $scale, which should be 1000.
446 Set to 1 to cancel scaling, causing all methods to use pixel units
448 instead of Pango units. Set to 0 to get the default behaviour.
449
451 Description of the Pango Markup Language:
452 <https://developer.gnome.org/pygtk/stable/pango-markup-language.html>.
453 Documentation of the Pango Layout class:
455 <https://developer.gnome.org/pango/stable/pango-Layout-Objects.html>.
456 PDF::API2, PDF::Builder, HarfBuzz::Shaper, Font::TTF.
458
460 Johan Vromans, "<JV at CPAN dot org>"
461
463 Development of this module takes place on GitHub:
464 <https://github.com/sciurius/perl-Text-Layout>.
465 You can find documentation for this module with the perldoc command.
467 perldoc Text::Layout
469 Please report any bugs or feature requests using the issue tracker on
471 GitHub.
472
474 Copyright (C) 2019, Johan Vromans
475 This module is free software. You can redistribute it and/or modify it
477 under the terms of the Artistic License 2.0.
478 This program is distributed in the hope that it will be useful, but
480 without any warranty; without even the implied warranty of
481 merchantability or fitness for a particular purpose.
482perl v5.30.1 2020-02-27 Text::Layout(3)