Arranges text and inline objects into lines according to a specified width and height as well as other options.
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 may be indented by setting Style#text_indent which may also be negative.
Text can be fitted into arbitrarily shaped areas, even containing holes.
Laying out text consists of three phases:
The items are broken into pieces which are wrapped into Box, Glue or Penalty objects. Additional Penalty objects marking line breaking opportunities are inserted where needed. This step is done by the SimpleTextSegmentation 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.
Public Class Methods
Public Instance Methods
Fits the items into the given area and returns a Result object with all the information.
height argument is just a number specifying the maximum
height that can be used.
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
heightis the bottom of last line (or 0 in case of the first line) and
line_heightis 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 HexaPDF::Layout::TextLayouter::Result#remaining_items always contains segmented items.