hexapdf 0.7.0 → 0.8.0

data/lib/hexapdf/layout/inline_box.rb

@@ -43,11 +43,11 @@ module HexaPDF
     class InlineBox
 
       # Creates an InlineBox that wraps a basic Box. All arguments (except +valign+) and the block
-      # are passed to Box::new.
+      # are passed to Box::create.
       #
       # See ::new for the +valign+ argument.
       def self.create(valign: :baseline, **args, &block)
-        new(Box.new(**args, &block), valign: valign)
+        new(Box.create(**args, &block), valign: valign)
       end
 
       # The vertical alignment of the box.

data/lib/hexapdf/layout/line.rb

@@ -175,8 +175,8 @@ module HexaPDF
       # An optional vertical offset that should be taken into account when positioning the line.
       #
       # For the first line in a paragraph this describes the offset from the top of the box to the
-      # top of the line. For all other lines it describes the offset from the previous baseline to
-      # the baseline of this line.
+      # baseline of the line. For all other lines it describes the offset from the previous baseline
+      # to the baseline of this line.
       attr_accessor :y_offset
 
       # Creates a new Line object, adding all given items to it.
@@ -290,7 +290,7 @@ module HexaPDF
       #
       # Clears all cached values.
       #
-      # This method needs to be called if the fragment's items are changed!
+      # This method needs to be called if the line's items are changed!
       def clear_cache
         @x_max = @y_min = @y_max = @text_y_min = @text_y_max = @width = nil
         self

data/lib/hexapdf/layout/style.rb

@@ -138,12 +138,17 @@ module HexaPDF
         # The value for right.
         attr_accessor :right
 
+        # Creates a new Quad object. See #set for more information.
+        def initialize(obj)
+          set(obj)
+        end
+
         # :call-seq:
-        #   Quad.new(value)
-        #   Quad.new(array)
-        #   Quad.new(quad)
+        #   quad.set(value)
+        #   quad.set(array)
+        #   quad.set(quad)
         #
-        # Creates a new Quad object.
+        # Sets all values of the quad.
         #
         # * If a single value is provided that is neither a Quad nor an array, it is handled as if
         #   an array with one value was given.
@@ -159,7 +164,7 @@ module HexaPDF
         #     third value.
         #   * Four or more values: Top is set to the first, right to the second, bottom to the third
         #     and left to the fourth value.
-        def initialize(obj)
+        def set(obj)
           case obj
           when Quad
             @top = obj.top
@@ -209,6 +214,8 @@ module HexaPDF
 
         # Draws the border onto the canvas, inside the rectangle (x, y, w, h).
         def draw(canvas, x, y, w, h)
+          return if none?
+
           canvas.save_graphics_state do
             if width.simple? && color.simple? && style.simple?
               draw_simple_border(canvas, x, y, w, h)
@@ -229,12 +236,11 @@ module HexaPDF
             miter_limit(10).
             line_cap_style(line_cap_style(:top))
 
+          canvas.rectangle(x, y, w, h).clip_path.end_path
           if style.top == :solid
             canvas.line_dash_pattern(0).
               rectangle(x + offset, y + offset, w - 2 * offset, h - 2 * offset).stroke
           else
-            canvas.rectangle(x, y, w, h).clip_path.end_path
-
             canvas.line_dash_pattern(line_dash_pattern(:top, w)).
               line(x, y + h - offset, x + w, y + h - offset).
               line(x + w, y + offset, x, y + offset).stroke
@@ -336,7 +342,7 @@ module HexaPDF
           when :dotted
             # Adjust the gap so that full dots appear in the corners.
             w = width.send(edge)
-            gap = (length - w).to_f / (length.to_f / (w * 2)).ceil
+            gap = [(length - w).to_f / (length.to_f / (w * 2)).ceil, 1].max
             HexaPDF::Content::LineDashPattern.new([0, gap], [gap - w * 0.5, 0].max)
           end
         end
@@ -358,7 +364,7 @@ module HexaPDF
       # The object resolved in this way needs to respond to #call(canvas, box) where +canvas+ is the
       # HexaPDF::Content::Canvas object on which it should be drawn and +box+ is a box-like object
       # (e.g. Box or TextFragment). The coordinate system is translated so that the origin is at the
-      # lower right corner of the box during the drawing operations.
+      # bottom left corner of the box during the drawing operations.
       class Layers
 
         # Creates a new Layers object popuplated with the given +layers+.
@@ -762,6 +768,54 @@ module HexaPDF
       # A Layers object containing all the layers that should be drawn under the box; defaults to no
       # layers being drawn.
 
+      ##
+      # :method: position
+      # :call-seq:
+      #   position(value = nil)
+      #
+      # Specifies how a box should be positioned in a frame. The property #position_hint provides
+      # additional, position specific data. Defaults to :default.
+      #
+      # Possible values:
+      #
+      # :default:: Position the box at the current position. The exact horizontal position is given
+      #            via the position hint. Space to the left/right of the box can't be used for other
+      #            boxes.
+      #
+      # :float:: Position the box at the current position but let it "float" so that the space to
+      #          the left/right can still be used. The position hint specifies where the box should
+      #          float.
+      #
+      # :absolute:: Position the box at an absolute position relative to the frame. The coordinates
+      #             are given via the position hint.
+
+      ##
+      # :method: position_hint
+      # :call-seq:
+      #   position_hint(value = nil)
+      #
+      # Specifies additional information on how a box should be positioned in a frame. The exact
+      # meaning depends on the value of the #position property.
+      #
+      # Possible values depending on the #position property:
+      #
+      # :default::
+      #
+      #   :left:: (default) Align the box to the left side of the available region.
+      #   :right:: Align the box to the right side of the available region.
+      #   :center:: Horizontally center the box in the available region.
+      #
+      # :float::
+      #
+      #   :left:: (default) Float the box to the left side of the available region.
+      #   :right::  Float the box to the right side of the available region.
+      #
+      # :absolute::
+      #
+      #    An array with the x- and y-coordinates of the bottom left corner of the absolutely
+      #    positioned box. The coordinates are taken as being relative to the bottom left corner of
+      #    the frame into which the box is drawn.
+
       [
         [:font, "raise HexaPDF::Error, 'No font set'"],
         [:font_size, 10],
@@ -796,9 +850,11 @@ module HexaPDF
         [:border, "Border.new", "Border.new(value)"],
         [:overlays, "Layers.new", "Layers.new(value)"],
         [:underlays, "Layers.new", "Layers.new(value)"],
+        [:position, :default],
+        [:position_hint, nil],
       ].each do |name, default, setter = "value", extra_args = ""|
         default = default.inspect unless default.kind_of?(String)
-        module_eval(<<-EOF, __FILE__, __LINE__)
+        module_eval(<<-EOF, __FILE__, __LINE__ + 1)
           def #{name}(value = UNSET#{extra_args})
             value == UNSET ? (@#{name} ||= #{default}) : (@#{name} = #{setter}; self)
           end
@@ -836,7 +892,7 @@ module HexaPDF
         [:text_line_wrapping_algorithm, 'TextLayouter::SimpleLineWrapping'],
       ].each do |name, default|
         default = default.inspect unless default.kind_of?(String)
-        module_eval(<<-EOF, __FILE__, __LINE__)
+        module_eval(<<-EOF, __FILE__, __LINE__ + 1)
           def #{name}(value = UNSET, &block)
             if value == UNSET && !block
               @#{name} ||= #{default}
@@ -914,12 +970,22 @@ module HexaPDF
 
       # The ascender of the font scaled appropriately.
       def scaled_font_ascender
-        @ascender ||= font.wrapped_font.ascender * font.scaling_factor * font_size / 1000
+        @scaled_font_ascender ||= font.wrapped_font.ascender * font.scaling_factor * font_size / 1000
       end
 
       # The descender of the font scaled appropriately.
       def scaled_font_descender
-        @descender ||= font.wrapped_font.descender * font.scaling_factor * font_size / 1000
+        @scaled_font_descender ||= font.wrapped_font.descender * font.scaling_factor * font_size / 1000
+      end
+
+      # The minimum y-coordinate, calculated using the scaled descender of the font.
+      def scaled_y_min
+        @scaled_y_min ||= scaled_font_descender + calculated_text_rise
+      end
+
+      # The maximum y-coordinate, calculated using the scaled descender of the font.
+      def scaled_y_max
+        @scaled_y_max ||= scaled_font_ascender + calculated_text_rise
       end
 
       # Returns the width of the item scaled appropriately (by taking font size, characters spacing,
@@ -946,7 +1012,8 @@ module HexaPDF
       # ascender, descender.
       def clear_cache
         @scaled_font_size = @scaled_character_spacing = @scaled_word_spacing = nil
-        @scaled_horizontal_scaling = @ascender = @descender = nil
+        @scaled_horizontal_scaling = @scaled_font_ascender = @scaled_font_descender = nil
+        @scaled_y_min = @scaled_y_max = nil
         @scaled_item_widths.clear
       end
 

data/lib/hexapdf/layout/text_box.rb

@@ -0,0 +1,84 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2018 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#++
+require 'hexapdf/layout/box'
+require 'hexapdf/layout/text_layouter'
+
+module HexaPDF
+  module Layout
+
+    # A TextBox is used for drawing text, either inside a rectangular box or by flowing it around
+    # objects of a Frame.
+    #
+    # This class uses TextLayouter behind the scenes to do the hard work.
+    class TextBox < Box
+
+      # Creates a new TextBox object with the given inline items (e.g. TextFragment and InlineBox
+      # objects).
+      def initialize(items, **kwargs)
+        super(kwargs)
+        @tl = TextLayouter.new(style)
+        @items = items
+        @result = nil
+      end
+
+      # Fits the text box into the Frame.
+      #
+      # Depending on the 'position' style property, the text is either fit into the rectangular area
+      # given by +available_width+ and +available_height+, or fit to the outline of the frame
+      # starting from the top.
+      def fit(available_width, available_height, frame)
+        @result = if style.position == :flow
+                    @tl.fit(@items, frame.width_specification, frame.contour_line.bbox.height)
+                  else
+                    @tl.fit(@items, available_width, available_height)
+                  end
+        @height = @result.height
+        @width = @result.lines.max_by(&:width)&.width || 0
+
+        success = (@result.status == :success)
+        @draw_block = success ? method(:draw_text) : nil
+        success
+      end
+
+      private
+
+      # Draws the text into the box.
+      def draw_text(canvas, _self)
+        return unless @result && !@result.lines.empty?
+        @result.draw(canvas, 0, @result.height)
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/layout/text_fragment.rb

@@ -49,7 +49,7 @@ module HexaPDF
     # The items of a text fragment may be frozen to indicate that the fragment is potentially used
     # multiple times.
     #
-    # The rectangle with the lower-left corner (#x_min, #y_min) and the upper right corner (#x_max,
+    # The rectangle with the bottom left corner (#x_min, #y_min) and the top right corner (#x_max,
     # #y_max) describes the minimum bounding box of the whole text fragment and is usually *not*
     # equal to the box (0, 0)-(#width, #height).
     class TextFragment
@@ -129,7 +129,7 @@ module HexaPDF
       # * It is assumed that the text matrix is not rotated, skewed, etc. so that setting the text
       #   position can be done using the optimal method.
       def draw(canvas, x, y, ignore_text_properties: false)
-        style.underlays.draw(canvas, x, y + y_min, self)
+        style.underlays.draw(canvas, x, y + y_min, self) if style.underlays?
 
         # Set general font related graphics state if necessary
         unless ignore_text_properties
@@ -173,7 +173,7 @@ module HexaPDF
         end
         canvas.show_glyphs_only(items)
 
-        if style.underline
+        if style.underline? && style.underline
           y_offset = style.calculated_underline_position
           canvas.save_graphics_state do
             canvas.stroke_color(style.fill_color).
@@ -185,7 +185,7 @@ module HexaPDF
           end
         end
 
-        if style.strikeout
+        if style.strikeout? && style.strikeout
           y_offset = style.calculated_strikeout_position
           canvas.save_graphics_state do
             canvas.stroke_color(style.fill_color).
@@ -197,7 +197,7 @@ module HexaPDF
           end
         end
 
-        style.overlays.draw(canvas, x, y + y_min, self)
+        style.overlays.draw(canvas, x, y + y_min, self) if style.overlays?
       end
 
       # The minimum x-coordinate of the first glyph.
@@ -212,12 +212,12 @@ module HexaPDF
 
       # The minimum y-coordinate, calculated using the scaled descender of the font.
       def y_min
-        @y_min ||= style.scaled_font_descender + style.calculated_text_rise
+        style.scaled_y_min
       end
 
       # The maximum y-coordinate, calculated using the scaled ascender of the font.
       def y_max
-        @y_max ||= style.scaled_font_ascender + style.calculated_text_rise
+        style.scaled_y_max
       end
 
       # The minimum y-coordinate of any item.
@@ -263,7 +263,7 @@ module HexaPDF
       #
       # This method needs to be called if the fragment's items or attributes are changed!
       def clear_cache
-        @x_min = @x_max = @y_min = @y_max = @exact_y_min = @exact_y_max = @width = @height = nil
+        @x_min = @x_max = @exact_y_min = @exact_y_max = @width = @height = nil
         self
       end
 

data/lib/hexapdf/layout/text_layouter.rb

@@ -50,9 +50,11 @@ module HexaPDF
     #
     # * 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.
+    #
     # == Layouting Algorithm
     #
-    # Laying out text consists of two phases:
+    # Laying out text consists of three phases:
     #
     # 1. 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.
@@ -61,6 +63,10 @@ module HexaPDF
     # 2. 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.
+    #
+    # 3. 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.
     class TextLayouter
 
       using NumericRefinements
@@ -273,7 +279,8 @@ module HexaPDF
       # Implementation of a simple line wrapping algorithm.
       #
       # The algorithm arranges the given items so that the maximum number is put onto each line,
-      # taking the differences of Box, Glue and Penalty items into account.
+      # taking the differences of Box, Glue and Penalty items into account. It is not as advanced as
+      # say Knuth's line wrapping algorithm in that it doesn't optimize paragraphs.
       class SimpleLineWrapping
 
         # :call-seq:
@@ -302,6 +309,12 @@ module HexaPDF
         # item is a box item, this single item didn't fit into the available width; the caller has
         # to handle this situation, e.g. by stopping.
         #
+        # In case of varying widths, the +width_block+ may also return +nil+ in which case the
+        # algorithm should revert back to a stored item index and then start as if beginning a new
+        # line. Which index to use is told the algorithm through the special return value
+        # +:store_start_of_line+ of the yielded-to block. When this return value is used, the
+        # current start of the line index should be stored for later use.
+        #
         # After the algorithm is finished, it returns the unused items.
         def self.call(items, width_block, &block)
           obj = new(items, width_block)
@@ -390,7 +403,7 @@ module HexaPDF
 
         # Performs the line wrapping with variable widths.
         def variable_width_wrapping
-          index = 0
+          index = @stored_index = 0
 
           while (item = @items[index])
             case item.type
@@ -399,6 +412,12 @@ module HexaPDF
               if new_height > @line_height
                 @line_height = new_height
                 @available_width = @width_block.call(@line_height)
+                if !@available_width || @width > @available_width
+                  index = (@available_width ? @beginning_of_line_index : @stored_index)
+                  item = @items[index]
+                  reset_after_line_break_variable_width(index, @line_height)
+                  redo
+                end
               end
               if add_box_item(item.item)
                 @height_calc << item.item
@@ -407,19 +426,19 @@ module HexaPDF
                   index = reset_line_to_last_breakpoint_state
                   item = @items[index]
                 end
-                break unless yield(create_line, item)
-                reset_after_line_break(index)
+                break unless (action = yield(create_line, item))
+                reset_after_line_break_variable_width(index, 0, action)
                 redo
               end
             when :glue
               unless add_glue_item(item.item, index)
-                break unless yield(create_line, item)
-                reset_after_line_break(index + 1)
+                break unless (action = yield(create_line, item))
+                reset_after_line_break_variable_width(index + 1, 0, action)
               end
             when :penalty
               if item.penalty <= -Penalty::INFINITY
-                break unless yield(create_unjustified_line, item)
-                reset_after_line_break(index + 1)
+                break unless (action = yield(create_unjustified_line, item))
+                reset_after_line_break_variable_width(index + 1, 0, action)
               elsif item.penalty >= Penalty::INFINITY
                 @break_prohibited_state = true
                 add_box_item(item.item) if item.width > 0
@@ -510,8 +529,9 @@ module HexaPDF
         end
 
         # Resets the line state variables to their initial values. The +index+ specifies the items
-        # index of the first item on the new line.
-        def reset_after_line_break(index)
+        # index of the first item on the new line. The +line_height+ specifies the line height to
+        # use for getting the available width.
+        def reset_after_line_break(index, line_height = 0)
           @beginning_of_line_index = index
           @line_items.clear
           @width = 0
@@ -519,155 +539,247 @@ module HexaPDF
           @last_breakpoint_index = index
           @last_breakpoint_line_items_index = 0
           @break_prohibited_state = false
-          @available_width = @width_block.call(0)
+          @available_width = @width_block.call(line_height)
+        end
 
-          @line_height = 0
+        # Specialized reset method for variable width wrapping.
+        #
+        # * The arguments +index+ and +line_height+ are also passed to #reset_after_line_break.
+        #
+        # * If the +action+ argument is +:store_start_of_line+, the stored item index is reset to
+        #   the index of the first item of the line.
+        def reset_after_line_break_variable_width(index, line_height, action = :none)
+          @stored_index = @beginning_of_line_index if action == :store_start_of_line
+          @line_height = line_height
           @height_calc.reset
+          reset_after_line_break(index, line_height)
         end
 
       end
 
-      # Creates a new TextLayouter object for the given text and returns it.
-      #
-      # See ::new for information on +height+.
-      #
-      # The style that gets applied to the text and the layout itself can be specified using
-      # additional options, of which font is mandatory.
-      def self.create(text, width:, height: nil, x_offsets: nil, **options)
-        frag = TextFragment.create(text, **options)
-        new(items: [frag], width: width, height: height, x_offsets: x_offsets, style: frag.style)
+      # Encapsulates the result of layouting items using a TextLayouter and provides a method for
+      # drawing the result (i.e. the layed out lines) on a canvas.
+      class Result
+
+        # The status after layouting the items:
+        #
+        # +:success+:: There are no remaining items.
+        # +:box_too_wide+:: A single text or inline box was too wide to fit alone on a line.
+        # +:height+:: There was not enough height for all items to layout.
+        #
+        # Even if the result is not +:success+, the layouting may still be successful depending on
+        # the usage. For example, if we expect that there may be too many items to fit, +:height+ is
+        # still a success.
+        attr_reader :status
+
+        # Array of layed out lines.
+        attr_reader :lines
+
+        # The actual height of all layed out lines (this includes a possible offset for the first
+        # line).
+        attr_reader :height
+
+        # The remaining items that couldn't be layed out.
+        attr_reader :remaining_items
+
+        # Creates a new Result structure.
+        def initialize(status, lines, remaining_items)
+          @status = status
+          @lines = lines
+          @height = @lines.sum(&:y_offset) - (@lines.last&.y_min || 0)
+          @remaining_items = remaining_items
+        end
+
+        # Draws the layed out lines onto the canvas with the top-left corner being at [x, y].
+        def draw(canvas, x, y)
+          last_item = nil
+          canvas.save_graphics_state do
+            # Best effort for leading in case we have an evenly spaced paragraph
+            canvas.leading(@lines[1].y_offset) if @lines.size > 1
+            @lines.each_with_index do |line, index|
+              y -= @lines[index].y_offset
+              line_x = x + line.x_offset
+              line.each do |item, item_x, item_y|
+                if item.kind_of?(TextFragment)
+                  item.draw(canvas, line_x + item_x, y + item_y,
+                            ignore_text_properties: last_item&.style == item.style)
+                  last_item = item
+                elsif !item.empty?
+                  canvas.restore_graphics_state
+                  item.draw(canvas, line_x + item_x, y + item_y)
+                  canvas.save_graphics_state
+                  last_item = nil
+                end
+              end
+            end
+          end
+        end
+
       end
 
       # The style to be applied.
       #
       # Only the following properties are used: Style#text_indent, Style#align, Style#valign,
-      # Style#text_segmentation_algorithm, Style#text_line_wrapping_algorithm
+      # Style#line_spacing, Style#text_segmentation_algorithm, Style#text_line_wrapping_algorithm
       attr_reader :style
 
-      # The items (TextFragment and InlineBox objects) that should be layed out.
-      attr_reader :items
-
-      # Array of Line objects describing the layed out lines.
-      #
-      # The array is only valid after #fit was called.
-      attr_reader :lines
-
-      # The actual height of the layed out text. Can be +nil+ if the items have not been layed out
-      # yet, i.e. if #fit has not been called.
-      attr_reader :actual_height
-
-      # Creates a new TextLayouter object with the given width containing the given items.
-      #
-      # The width can either be a simple number specifying a fixed width, or an object that responds
-      # to #call(height, line_height) where +height+ is the bottom of last line and +line_height+ is
-      # the height of the line to be layed out. The return value should be the available width given
-      # these height restrictions.
-      #
-      # The optional +x_offsets+ argument works like +width+ but can be used to specify (varying)
-      # offsets from the left side (e.g. when the left side of the text should follow a certain
-      # shape).
-      #
-      # The height is optional and if not specified means that the text layout has infinite height.
+      # 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.
-      def initialize(items: [], width:, height: nil, x_offsets: nil, style: Style.new)
+      def initialize(style = Style.new)
         @style = (style.kind_of?(Style) ? style : Style.new(style))
-        @lines = []
-        self.items = items
-        @width = width
-        @height = height || Float::INFINITY
-        @x_offsets = x_offsets && (x_offsets.respond_to?(:call) ? x_offsets : proc { x_offsets })
-      end
-
-      # Sets the items to be arranged by the text layouter, clearing the internal state.
-      #
-      # If the items array contains items before text segmentation, the text segmentation algorithm
-      # is automatically applied.
-      def items=(items)
-        unless items.empty? || items[0].respond_to?(:type)
-          items = style.text_segmentation_algorithm.call(items)
-        end
-        @items = items.freeze
-        @lines.clear
-        @actual_height = nil
       end
 
       # :call-seq:
-      #   text_layouter.fit  -> [remaining_items, reason]
+      #   text_layouter.fit(items, width, height) -> result
+      #
+      # Fits the items into the given area and returns a Result object with all the information.
       #
-      # Fits the items into the set area and returns the remaining items as well as the reason why
-      # there are remaining items.
+      # The +height+ argument is just a number specifying the maximum height that can be used.
       #
-      # The reason can be +:success+ if there are no remaining items, +:box+ if a single text or
-      # inline box item is too wide to fit alone on a line, or +:height+ if there was not enough
-      # height for all items.
+      # The +width+ argument can be one of the following:
       #
-      # The fitted lines can be retrieved via #lines and the total height via #actual_height.
+      # **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.
       #
-      # Note: If no height has been set and variable line widths are used, no search for a possible
-      # vertical offset is done in case a single item doesn't fit.
+      # **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.
       #
-      # This method is automatically called as part of the drawing routine but it can also be used
-      # by itself to determine the actual height of the layed out text.
-      def fit
-        @lines.clear
-        @actual_height = 0
+      #     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) and +line_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.
+      def fit(items, width, height)
+        unless items.empty? || items[0].respond_to?(:type)
+          items = style.text_segmentation_algorithm.call(items)
+        end
+
+        # result variables
+        lines = []
+        actual_height = 0
+        rest = items
 
-        rest = @items
+        # processing state variables
+        indent = style.text_indent
+        line_fragments = []
+        line_height = 0
+        last_line = nil
         y_offset = 0
-        indent = (style.text_indent != 0 ? style.text_indent : 0)
-        width_block = if @width.respond_to?(:call)
-                        proc {|h| @width.call(@actual_height, h) - indent }
-                      else
-                        proc { @width - indent }
-                      end
+        width_spec = nil
+        width_spec_index = 0
+        width_block =
+          if width.respond_to?(:call)
+            last_actual_height = nil
+            last_line_height = nil
+            proc do |h|
+              line_height = [line_height, h || 0].max
+              if last_actual_height != actual_height || last_line_height != line_height
+                spec = width.call(actual_height, line_height)
+                spec = [0, spec] unless spec.kind_of?(Array)
+                last_actual_height = actual_height
+                last_line_height = line_height
+              else
+                spec = width_spec
+              end
+              if spec == width_spec
+                # no changes, just need to return the width of the current part
+                width_spec[width_spec_index * 2 + 1] - (width_spec_index == 0 ? indent : 0)
+              elsif line_fragments.each_with_index.all? {|l, i| l.width <= spec[i * 2 + 1] }
+                # width_spec changed, parts can only get smaller but processed parts still fit
+                width_spec = spec
+                width_spec[width_spec_index * 2 + 1] - (width_spec_index == 0 ? indent : 0)
+              else
+                # width_spec changed and some processed part doesn't fit anymore, retry from start
+                line_fragments.clear
+                width_spec = spec
+                width_spec_index = 0
+                nil
+              end
+            end
+          elsif width.kind_of?(Array)
+            width_spec = width
+            proc { width_spec[width_spec_index * 2 + 1] - (width_spec_index == 0 ? indent : 0) }
+          else
+            width_spec = [0, width]
+            proc { width - indent }
+          end
 
         while true
           too_wide_box = nil
 
           rest = style.text_line_wrapping_algorithm.call(rest, width_block) do |line, item|
+            # make sure empty lines broken by mandatory paragraph breaks are not empty
             line << TextFragment.new([], style) if item&.type != :box && line.items.empty?
-            new_height = @actual_height + line.height +
-              (@lines.empty? ? 0 : style.line_spacing.gap(@lines.last, line))
 
-            if new_height > @height
-              nil
-            elsif !line.items.empty?
+            # item didn't fit into first part, find next available part
+            if line.items.empty? && line_fragments.empty?
+              old_height = actual_height
+              while item.width > width_block.call(item.height) && actual_height <= height
+                width_spec_index += 1
+                if width_spec_index >= width_spec.size / 2
+                  actual_height += item.height / 3
+                  width_spec_index = 0
+                end
+              end
+              if actual_height + item.height <= height
+                width_spec_index.times { line_fragments << Line.new }
+                y_offset = actual_height - old_height
+                next true
+              else
+                actual_height = old_height
+                too_wide_box = item
+                next nil
+              end
+            end
+
+            # continue with line fragments of current line if there are still parts and items
+            # available; also handles the case if at least the first fragment is not empty and a
+            # single item didn't fit into at least one of the other parts
+            line_fragments << line
+            unless line_fragments.size == width_spec.size / 2 || !item || item.type == :penalty
+              width_spec_index += 1
+              next (width_spec_index == 1 ? :store_start_of_line : true)
+            end
+
+            combined_line = create_combined_line(line_fragments)
+            new_height = actual_height + combined_line.height +
+              (last_line ? style.line_spacing.gap(last_line, combined_line) : 0)
+
+            if new_height <= height
               # valid line found, use it
-              cur_width = width_block.call(line.height)
-              line.x_offset = indent + horizontal_alignment_offset(line, cur_width)
-              line.x_offset += @x_offsets.call(@actual_height, line.height) if @x_offsets
-              line.y_offset =  if y_offset
-                                 y_offset + (@lines.last ? -@lines.last.y_min + line.y_max : 0)
-                               else
-                                 style.line_spacing.baseline_distance(@lines.last, line)
-                               end
-              @actual_height = new_height
-              @lines << line
-              y_offset = nil
+              apply_offsets(line_fragments, width_spec, indent, last_line, combined_line, y_offset)
+              lines.concat(line_fragments)
+              line_fragments.clear
+              width_spec_index = 0
               indent = if item&.type == :penalty && item.penalty == Penalty::PARAGRAPH_BREAK
                          style.text_indent
                        else
                          0
                        end
+              last_line = combined_line
+              actual_height = new_height
+              line_height = 0
+              y_offset = nil
               true
-            elsif @height != Float::INFINITY
-              # some height left but item didn't fit on the line, search downwards for usable space
-              old_height = @actual_height
-              while item.width > width_block.call(item.height) && @actual_height <= @height
-                @actual_height += item.height / 3
-              end
-              if @actual_height + item.height <= @height
-                y_offset = @actual_height - old_height
-                true
-              else
-                @actual_height = old_height
-                too_wide_box = item
-                nil
-              end
             else
-              too_wide_box = item
               nil
             end
           end
@@ -679,74 +791,71 @@ module HexaPDF
             end
             too_wide_box = nil
           else
-            reason = (too_wide_box ? :box : (rest.empty? ? :success : :height))
+            status = (too_wide_box ? :box_too_wide : (rest.empty? ? :success : :height))
             break
           end
         end
 
-        [rest, reason]
+        unless lines.empty?
+          lines.first.y_offset += initial_baseline_offset(lines, height, actual_height)
+        end
+
+        Result.new(status, lines, rest)
       end
 
-      # :call-seq:
-      #   tl.draws(canvas, x, y, fit: :if_needed) -> [remaining_items, reason] or nil
-      #
-      # Draws the layed out text onto the canvas with the top-left corner being at [x, y].
-      #
-      # Depending on the value of +fit+ the text may also be fitted:
-      #
-      # * If +true+, then #fit is always called.
-      # * If +:if_needed+, then #fit is only called if it has not been called before.
-      # * If +false+, then #fit is never called.
+      private
+
+      # :nodoc:
       #
-      # If #fit was called, its return value is returned. Otherwise +nil+ is returned.
-      def draw(canvas, x, y, fit: :if_needed)
-        fit_result = self.fit if fit == true || (!@actual_height && fit == :if_needed)
-        return fit_result if @lines.empty?
-
-        last_item = nil
-        canvas.save_graphics_state do
-          if @lines.size > 1
-            canvas.leading(style.line_spacing.baseline_distance(@lines[0], @lines[1]))
-          end
-          y -= initial_baseline_offset + @lines.first.y_offset
-          @lines.each_with_index do |line, index|
-            line_x = x + line.x_offset
-            line.each do |item, item_x, item_y|
-              if item.kind_of?(TextFragment)
-                item.draw(canvas, line_x + item_x, y + item_y,
-                          ignore_text_properties: last_item&.style == item.style)
-                last_item = item
-              elsif !item.empty?
-                canvas.restore_graphics_state
-                item.draw(canvas, line_x + item_x, y + item_y)
-                canvas.save_graphics_state
-                last_item = nil
-              end
-            end
-            y -= @lines[index + 1].y_offset if @lines[index + 1]
-          end
+      # A dummy line class for use with Style#line_spacing methods in case a line actually consists
+      # of multiple line fragments.
+      DummyLine = Struct.new(:y_min, :y_max) do
+        def height
+          y_max - y_min
         end
+      end
 
-        fit_result
+      # Creates a line combining all items from the given line fragments for height calculations.
+      def create_combined_line(line_frags)
+        if line_frags.size == 1
+          line_frags[0]
+        else
+          calc = Line::HeightCalculator.new
+          line_frags.each {|l| l.items.each {|i| calc << i } }
+          y_min, y_max, = calc.result
+          DummyLine.new(y_min, y_max)
+        end
       end
 
-      private
+      # Applies the necessary x- and y-offsets to the line fragments.
+      def apply_offsets(line_frags, width_spec, indent, last_line, combined_line, y_offset)
+        cumulated_width = 0
+        line_frags.each_with_index do |line, index|
+          line.x_offset = cumulated_width + indent
+          line.x_offset += width_spec[index * 2]
+          line.x_offset += horizontal_alignment_offset(line, width_spec[index * 2 + 1] - indent)
+          cumulated_width += width_spec[index * 2] + width_spec[index * 2 + 1]
+          if index == 0
+            line.y_offset = if y_offset
+                              y_offset + combined_line.y_max -
+                                (last_line ? last_line.y_min : line.y_max)
+                            else
+                              style.line_spacing.baseline_distance(last_line, combined_line)
+                            end
+          end
+          indent = 0
+        end
+      end
 
       # Returns the initial baseline offset from the top, based on the valign style option.
-      def initial_baseline_offset
+      def initial_baseline_offset(lines, height, actual_height)
         case style.valign
         when :top
-          @lines.first.y_max
+          lines.first.y_max
         when :center
-          if @height == Float::INFINITY
-            raise HexaPDF::Error, "Can't vertically align when using unlimited height"
-          end
-          (@height - @actual_height) / 2.0 + @lines.first.y_max
+          (height - actual_height) / 2.0 + lines.first.y_max
         when :bottom
-          if @height == Float::INFINITY
-            raise HexaPDF::Error, "Can't vertically align when using unlimited height"
-          end
-          (@height - @actual_height) + @lines.first.y_max
+          (height - actual_height) + lines.first.y_max
         end
       end