class HexaPDF:: Layout:: TextLayouter
Parent | Object |
---|
Arranges text and inline objects into lines according to a specified width and height as well as other options.
Features¶ ↑
-
Existing line breaking characters inside of
TextFragment
objects are respected when fitting text. If this is not wanted, they have to be removed beforehand. -
The first line of each paragraph may be indented by setting
Style#text_indent
which may also be negative. -
Text can be fitted into arbitrarily shaped areas, even containing holes.
Layouting Algorithm¶ ↑
Laying out text consists of three phases:
-
The items are broken into pieces which are wrapped into
Box
,Glue
orPenalty
objects. AdditionalPenalty
objects marking line breaking opportunities are inserted where needed. This step is done by theSimpleTextSegmentation
module. -
The pieces are arranged into lines using a very simple algorithm that just puts the maximum number of consecutive pieces into each line. This step is done by the
SimpleLineWrapping
module. -
The lines of step two may actually not be whole lines but line fragments if the area has holes or other discontinuities. The
fit
method deals with those so that the line wrapping algorithm can be separate.
Constants
- DummyLine¶
A dummy line class for use with variable width wrapping, and
Style#line_spacing
methods in case a line actually consists of multiple line fragments.
Attributes
The style to be applied.
Only the following properties are used: Style#text_indent
, Style#text_align
, Style#text_valign
, Style#line_spacing
, Style#fill_horizontal
, Style#text_segmentation_algorithm
, Style#text_line_wrapping_algorithm
Public Class Methods
Creates a new TextLayouter
object with the given style.
The style
argument can either be a Style
object or a hash of style options. See style
for the properties that are used by the layouter.
Public Instance Methods
Fits the items into the given area and returns a Result
object with all the information.
The height
argument is just a number specifying the maximum height that can be used.
The width
argument can be one of the following:
- **a number**
-
In this case the layed out lines have this number as maximum width. This is the standard case and means that the area in which the text is layed out is a rectangle.
- **an array with an even number of numbers**
-
The array has to be of the form [offset, width, offset, width, …], so the even indices specify offsets (relative to the current position, not absolute offsets from the left), the odd indices widths. This allows laying out lines containing holes in them.
A simple example: [15, 100, 30, 40]. This means that a space of 15 on the left is never used, then comes text with a maximum width of 100, starting at the absolute offset 15, followed by a hole with a width of 30 and then text again with a width of 40, starting at the absolute offset 145 (=15 + 100 + 30).
- **an object responding to call(height, line_height)**
-
The provided argument
height
is the bottom of last line (or 0 in case of the first line) andline_height
is the height of the line to be layed out. The return value has to be of one of the forms above (i.e. a single number or an array of numbers) and should describe the area given these height restrictions.This allows laying out text inside complex, arbitrarily formed shapes and can be used, for example, for flowing text around objects.
The text segmentation algorithm specified via style
is applied to the items in case they are not already in segmented form. This also means that Result#remaining_items
always contains segmented items.
Optional arguments:
apply_first_text_indent
-
Specifies whether style.text_indent should be applied to the first line. This should be set to
false
if the items start with a continuation of a paragraph instead of starting a new paragraph (e.g. after a page break). frame
-
If used with the document layout functionality, this should be the frame into which the text is laid out.