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
TextFragmentobjects 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_indentwhich 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
Penaltyobjects marking line breaking opportunities are inserted where needed. This step is done by the
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
The lines of step two may actually not be whole lines but line fragments if the area has holes or other discontinuities. The
fitmethod 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
Result#remaining_items always contains segmented items.