hexapdf 0.4.0 → 0.5.0

data/lib/hexapdf/layout/numeric_refinements.rb

@@ -0,0 +1,56 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2017 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.
+#++
+
+module HexaPDF
+  module Layout
+
+    # Provides a refinement of the Numeric class so that kerning numbers can more seamlessly be used
+    # together with actual glyphs.
+    module NumericRefinements
+      refine Numeric do
+        def x_min
+          -self
+        end
+
+        def y_min
+          0
+        end
+
+        def y_max
+          0
+        end
+      end
+    end
+
+  end
+end

data/lib/hexapdf/layout/style.rb

@@ -0,0 +1,365 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2017 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/error'
+
+module HexaPDF
+  module Layout
+
+    # A Style is a container for properties that describe the appearance of text or graphics.
+    #
+    # Each property except #font has a default value, so only the desired properties need to be
+    # changed.
+    class Style
+
+      # Defines how the distance between the baselines of two adjacent text lines is determined:
+      #
+      # :single::
+      #     :proportional with value 1.
+      #
+      # :double::
+      #     :proportional with value 2.
+      #
+      # :proportional::
+      #     The y_min of the first line and the y_max of the second line are multiplied with the
+      #     specified value, and the sum is used as baseline distance.
+      #
+      # :fixed::
+      #     The distance between the baselines is set to the specified value.
+      #
+      # :leading::
+      #     The distance between the baselines is set to the sum of the y_min of the first line, the
+      #     y_max of the second line and the specified value.
+      class LineSpacing
+
+        # The type of line spacing - see LineSpacing
+        attr_reader :type
+
+        # The value (needed for some types) - see LineSpacing
+        attr_reader :value
+
+        # Creates a new LineSpacing object for the given type which can be any valid line spacing
+        # type or a LineSpacing object.
+        def initialize(type, value: 1)
+          case type
+          when :single
+            @type = :proportional
+            @value = 1
+          when :double
+            @type = :proportional
+            @value = 2
+          when :fixed, :proportional, :leading
+            unless value.kind_of?(Numeric)
+              raise ArgumentError, "Need a valid number for #{type} line spacing"
+            end
+            @type = type
+            @value = value
+          when LineSpacing
+            @type = type.type
+            @value = type.value
+          else
+            raise ArgumentError, "Invalid type #{type} for line spacing"
+          end
+        end
+
+        # Returns the distance between the baselines of the two given LineFragment objects.
+        def baseline_distance(line1, line2)
+          case type
+          when :proportional then (line1.y_min.abs + line2.y_max) * value
+          when :fixed then value
+          when :leading then line1.y_min.abs + line2.y_max + value
+          end
+        end
+
+        # Returns the gap between the two given LineFragment objects, i.e. the distance between the
+        # y_min of the first line and the y_max of the second line.
+        def gap(line1, line2)
+          case type
+          when :proportional then (line1.y_min.abs + line2.y_max) * (value - 1)
+          when :fixed then value - line1.y_min.abs - line2.y_max
+          when :leading then value
+          end
+        end
+
+      end
+
+      UNSET = ::Object.new # :nodoc:
+
+      # Creates a new Style object.
+      #
+      # The +options+ hash may be used to set the initial values of properties by using keys
+      # equivalent to the property names.
+      #
+      # Example:
+      #   Style.new(font_size: 15, align: :center, valign: center)
+      def initialize(**options)
+        options.each {|key, value| send(key, value)}
+        @scaled_item_widths = {}
+      end
+
+      ##
+      # :method: font
+      # :call-seq:
+      #   font(name = nil)
+      #
+      # The font to be used, must be set to a valid font wrapper object before it can be used.
+      #
+      # This is the only style property without a default value!
+      #
+      # See: HexaPDF::Content::Canvas#font
+
+      ##
+      # :method: font_size
+      # :call-seq:
+      #   font_size(size = nil)
+      #
+      # The font size, defaults to 10.
+      #
+      # See: HexaPDF::Content::Canvas#font_size
+
+      ##
+      # :method: character_spacing
+      # :call-seq:
+      #   character_spacing(amount = nil)
+      #
+      # The character spacing, defaults to 0 (i.e. no additional character spacing).
+      #
+      # See: HexaPDF::Content::Canvas#character_spacing
+
+      ##
+      # :method: word_spacing
+      # :call-seq:
+      #   word_spacing(amount = nil)
+      #
+      # The word spacing, defaults to 0 (i.e. no additional word spacing).
+      #
+      # See: HexaPDF::Content::Canvas#word_spacing
+
+      ##
+      # :method: horizontal_scaling
+      # :call-seq:
+      #   horizontal_scaling(percent = nil)
+      #
+      # The horizontal scaling, defaults to 100 (in percent, i.e. normal scaling).
+      #
+      # See: HexaPDF::Content::Canvas#horizontal_scaling
+
+      ##
+      # :method: text_rise
+      # :call-seq:
+      #   text_rise(amount = nil)
+      #
+      # The text rise, i.e. the vertical offset from the baseline, defaults to 0.
+      #
+      # See: HexaPDF::Content::Canvas#text_rise
+
+      ##
+      # :method: font_features
+      # :call-seq:
+      #   font_features(features = nil)
+      #
+      # The font features (e.g. kerning, ligatures, ...) that should be applied by the shaping
+      # engine, defaults to {} (i.e. no font features are applied).
+      #
+      # Each feature to be applied is indicated by a key with a truthy value.
+      #
+      # See: HexaPDF::Layout::TextShaper#shape_text for available features.
+
+      ##
+      # :method: align
+      # :call-seq:
+      #   align(direction = nil)
+      #
+      # The horizontal alignment of text, defaults to :left.
+      #
+      # Possible values:
+      #
+      # :left::    Left-align the text, i.e. the right side is rugged.
+      # :center::  Center the text horizontally.
+      # :right::   Right-align the text, i.e. the left side is rugged.
+      # :justify:: Justify the text, except for those lines that end in a hard line break.
+
+      ##
+      # :method: valign
+      # :call-seq:
+      #   valign(direction = nil)
+      #
+      # The vertical alignment of items (normally text) inside a box, defaults to :top.
+      #
+      # Possible values:
+      #
+      # :top::    Vertically align the items to the top of the box.
+      # :center:: Vertically align the items in the center of the box.
+      # :bottom:: Vertically align the items to the bottom of the box.
+
+      ##
+      # :method: text_indent
+      # :call-seq:
+      #   text_indent(amount = nil)
+      #
+      # The indentation to be used for the first line of a sequence of text lines, defaults to 0.
+
+      [
+        [:font, "raise HexaPDF::Error, 'No font set'"],
+        [:font_size, 10],
+        [:character_spacing, 0],
+        [:word_spacing, 0],
+        [:horizontal_scaling, 100],
+        [:text_rise, 0],
+        [:font_features, {}],
+        [:align, :left],
+        [:valign, :top],
+        [:text_indent, 0],
+      ].each do |name, default|
+        default = default.inspect unless default.kind_of?(String)
+        module_eval(<<-EOF, __FILE__, __LINE__)
+          def #{name}(value = UNSET)
+            value == UNSET ? (@#{name} ||= #{default}) : (@#{name} = value; self)
+          end
+        EOF
+        alias_method("#{name}=", name)
+      end
+
+      # :call-seq:
+      #   line_spacing(type = nil, value = nil)
+      #
+      # The spacing between consecutive lines, defaults to type = :single.
+      #
+      # See: LineSpacing
+      def line_spacing(type = UNSET, value = nil)
+        if type == UNSET
+          @line_spacing ||= LineSpacing.new(:single)
+        else
+          @line_spacing = LineSpacing.new(type, value: value)
+          self
+        end
+      end
+      alias_method(:line_spacing=, :line_spacing)
+
+      # :call-seq:
+      #   text_segmentation_algorithm(algorithm = nil) {|items| block }
+      #
+      # The algorithm to use for text segmentation purposes, defaults to
+      # TextBox::SimpleTextSegmentation.
+      #
+      # When setting the algorithm, either an object that responds to #call(items) or a block can be
+      # used.
+      def text_segmentation_algorithm(algorithm = UNSET, &block)
+        if algorithm == UNSET && !block
+          @text_segmentation_algorithm ||= TextBox::SimpleTextSegmentation
+        else
+          @text_segmentation_algorithm = (algorithm != UNSET ? algorithm : block)
+          self
+        end
+      end
+      alias_method(:text_segmentation_algorithm=, :text_segmentation_algorithm)
+
+      # :call-seq:
+      #   text_line_wrapping_algorithm(algorithm = nil) {|items| block }
+      #
+      # The line wrapping algorithm that should be used, defaults to TextBox::SimpleLineWrapping.
+      #
+      # When setting the algorithm, either an object that responds to #call or a block can be used.
+      # See TextBox::SimpleLineWrapping#call for the needed method signature.
+      def text_line_wrapping_algorithm(algorithm = UNSET, &block)
+        if algorithm == UNSET && !block
+          @text_line_wrapping_algorithm ||= TextBox::SimpleLineWrapping
+        else
+          @text_line_wrapping_algorithm = (algorithm != UNSET ? algorithm : block)
+          self
+        end
+      end
+      alias_method(:text_line_wrapping_algorithm=, :text_line_wrapping_algorithm)
+
+      # The font size scaled appropriately.
+      def scaled_font_size
+        @scaled_font_size ||= font_size / 1000.0 * scaled_horizontal_scaling
+      end
+
+      # The character spacing scaled appropriately.
+      def scaled_character_spacing
+        @scaled_character_spacing ||= character_spacing * scaled_horizontal_scaling
+      end
+
+      # The word spacing scaled appropriately.
+      def scaled_word_spacing
+        @scaled_word_spacing ||= word_spacing * scaled_horizontal_scaling
+      end
+
+      # The horizontal scaling scaled appropriately.
+      def scaled_horizontal_scaling
+        @scaled_horizontal_scaling ||= horizontal_scaling / 100.0
+      end
+
+      # The ascender of the font scaled appropriately.
+      def scaled_font_ascender
+        @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
+      end
+
+      # Returns the width of the item scaled appropriately (by taking font size, characters spacing,
+      # word spacing and horizontal scaling into account).
+      #
+      # The item may be a (singleton) glyph object or an integer/float, i.e. items that can appear
+      # inside a TextFragment.
+      def scaled_item_width(item)
+        @scaled_item_widths[item.object_id] ||=
+          begin
+            if item.kind_of?(Numeric)
+              -item * scaled_font_size
+            else
+              item.width * scaled_font_size + scaled_character_spacing +
+                (item.apply_word_spacing? ? scaled_word_spacing : 0)
+            end
+          end
+      end
+
+      # Clears all cached values.
+      #
+      # This method needs to be called if the following style properties are changed and values were
+      # already cached: font, font_size, character_spacing, word_spacing, horizontal_scaling,
+      # ascender, descender.
+      def clear_cache
+        @scaled_font_size = @scaled_character_spacing = @scaled_word_spacing = nil
+        @scaled_horizontal_scaling = @ascender = @descender = nil
+        @scaled_item_widths.clear
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/layout/text_box.rb

@@ -0,0 +1,727 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2017 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/error'
+require 'hexapdf/layout/text_fragment'
+require 'hexapdf/layout/inline_box'
+require 'hexapdf/layout/line_fragment'
+require 'hexapdf/layout/numeric_refinements'
+
+module HexaPDF
+  module Layout
+
+    # 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 may be indented by setting Style#text_indent which may also be negative.
+    #
+    # == Layouting Algorithm
+    #
+    # Laying out text consists of two phases:
+    #
+    # 1. The items of the text box 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.
+    #
+    # 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.
+    class TextBox
+
+      using NumericRefinements
+
+      # Used for layouting. Describes an item with a fixed width, like an InlineBox or TextFragment.
+      class Box
+
+        # The wrapped item.
+        attr_reader :item
+
+        # Creates a new Box for the item.
+        def initialize(item)
+          @item = item
+        end
+
+        # The width of the item.
+        def width
+          @item.width
+        end
+
+        # Returns :box.
+        def type
+          :box
+        end
+
+      end
+
+      # Used for layouting. Describes a glue item, i.e. an item describing white space that could
+      # potentially be shrunk or stretched.
+      class Glue
+
+        # The wrapped item.
+        attr_reader :item
+
+        # The amount by which the glue could be stretched.
+        attr_reader :stretchability
+
+        # The amount by which the glue could be shrunk.
+        attr_reader :shrinkability
+
+        # Creates a new Glue for the item.
+        def initialize(item, stretchability = item.width / 2, shrinkability = item.width / 3)
+          @item = item
+          @stretchability = stretchability
+          @shrinkability = shrinkability
+        end
+
+        # Returns :glue.
+        def type
+          :glue
+        end
+
+      end
+
+      # Used for layouting. Describes a penalty item, i.e. a point where a break is allowed.
+      #
+      # If the penalty is greater than or equal to INFINITY, a break is forbidden. If it is smaller
+      # than or equal to -INFINITY, a break is mandatory.
+      #
+      # If a penalty contains an item and a break occurs at the penalty (taking the width of the
+      # penalty/item into account), then the penality item must be the last item of the line.
+      class Penalty
+
+        # All numbers greater than this one are deemed infinite.
+        INFINITY = 1000
+
+        # The penalty for breaking at this point.
+        attr_reader :penalty
+
+        # The width assigned to this item.
+        attr_reader :width
+
+        # The wrapped item.
+        attr_reader :item
+
+        # Creates a new Penalty with the given penality.
+        def initialize(penalty, width = 0, item: nil)
+          @penalty = penalty
+          @width = width
+          @item = item
+        end
+
+        # Returns :penalty.
+        def type
+          :penalty
+        end
+
+        # Singleton object describing a Penalty for a mandatory break.
+        MandatoryBreak = new(-Penalty::INFINITY)
+
+        # Singleton object describing a Penalty for a prohibited break.
+        ProhibitedBreak = new(Penalty::INFINITY)
+
+        # Singleton object describing a standard Penalty, e.g. for hyphens.
+        Standard = new(50)
+
+      end
+
+      # Implementation of a simple text segmentation algorithm.
+      #
+      # The algorithm breaks TextFragment objects into objects wrapped by Box, Glue or Penalty
+      # items, and inserts additional Penalty items when needed:
+      #
+      # * Any valid Unicode newline separator inserts a Penalty object describing a mandatory break.
+      #
+      #   See http://www.unicode.org/reports/tr18/#Line_Boundaries
+      #
+      # * Spaces and tabulators are wrapped by Glue objects, allowing breaks.
+      #
+      # * Non-breaking spaces are wrapped into Penalty objects that prohibit line breaking.
+      #
+      # * Hyphens are attached to the preceeding text fragment (or are a standalone text fragment)
+      #   and followed by a Penalty object to allow a break.
+      #
+      # * If a soft-hyphens is encountered, a hyphen wrapped by a Penalty object is inserted to
+      #   allow a break.
+      #
+      # * If a zero-width-space is encountered, a Penalty object is inserted to allow a break.
+      module SimpleTextSegmentation
+
+        # Breaks are detected at: space, tab, zero-width-space, non-breaking space, hyphen,
+        # soft-hypen and any valid Unicode newline separator
+        BREAK_RE = /[ \u{A}-\u{D}\u{85}\u{2028}\u{2029}\t\u{200B}\u{00AD}\u{00A0}-]/
+
+        # Breaks the items (an array of InlineBox and TextFragment objects) into atomic pieces
+        # wrapped by Box, Glue or Penalty items, and returns those as an array.
+        def self.call(items)
+          result = []
+          glues = {}
+          items.each do |item|
+            if item.kind_of?(InlineBox)
+              result << Box.new(item)
+            else
+              i = 0
+              while i < item.items.size
+                # Collect characters and kerning values until break character is encountered
+                box_items = []
+                while (glyph = item.items[i]) &&
+                    (glyph.kind_of?(Numeric) || !BREAK_RE.match?(glyph.str))
+                  box_items << glyph
+                  i += 1
+                end
+
+                # A hyphen belongs to the text fragment
+                box_items << glyph if glyph && !glyph.kind_of?(Numeric) && glyph.str == '-'.freeze
+
+                unless box_items.empty?
+                  result << Box.new(TextFragment.new(items: box_items.freeze, style: item.style))
+                end
+
+                if glyph
+                  case glyph.str
+                  when ' '
+                    glues[item.style] ||=
+                      Glue.new(TextFragment.new(items: [glyph].freeze, style: item.style))
+                    result << glues[item.style]
+                  when "\n", "\v", "\f", "\u{85}", "\u{2028}", "\u{2029}"
+                    result << Penalty::MandatoryBreak
+                  when "\r"
+                    if item.items[i + 1]&.kind_of?(Numeric) || item.items[i + 1].str != "\n"
+                      result << Penalty::MandatoryBreak
+                    end
+                  when '-'
+                    result << Penalty::Standard
+                  when "\t"
+                    spaces = [item.style.font.decode_utf8(" ").first] * 8
+                    result << Glue.new(TextFragment.new(items: spaces.freeze, style: item.style))
+                  when "\u{00AD}"
+                    hyphen = item.style.font.decode_utf8("-").first
+                    frag = TextFragment.new(items: [hyphen].freeze, style: item.style)
+                    result << Penalty.new(Penalty::Standard.penalty, frag.width, item: frag)
+                  when "\u{00A0}"
+                    space = item.style.font.decode_utf8(" ").first
+                    frag = TextFragment.new(items: [space].freeze, style: item.style)
+                    result << Penalty.new(Penalty::ProhibitedBreak.penalty, frag.width, item: frag)
+                  when "\u{200B}"
+                    result << Penalty.new(0)
+                  end
+                end
+                i += 1
+              end
+            end
+          end
+          result
+        end
+      end
+
+      # 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.
+      class SimpleLineWrapping
+
+        # :call-seq:
+        #   SimpleLineWrapping.call(items, available_width) {|line, item| block }   -> rest
+        #
+        # Arranges the items into lines.
+        #
+        # The +available_width+ argument can either be a simple number or a callable object:
+        #
+        # * If all lines should have the same width, the +available_width+ argument should be a
+        #   number. This is the general case.
+        #
+        # * However, if lines should have varying lengths (e.g. for flowing text around shapes), the
+        #   +available_width+ argument should be an object responding to #call(line_height) where
+        #   +line_height+ is the height of the currently layed out line. The caller is responsible
+        #   for tracking the height of the already layed out lines. The result of the method call
+        #   should be the available width.
+        #
+        # Regardless of whether varying line widths are used or not, each time a line is finished,
+        # it is yielded to the caller. The second argument +item+ is the TextFragment or InlineBox
+        # that doesn't fit anymore, or +nil+ in case of mandatory line breaks or when the line break
+        # occured at a glue item. If the yielded line is empty and the yielded item is not +nil+,
+        # this single item doesn't fit into the available width; the caller has to handle this
+        # situation, e.g. by stopping.
+        #
+        # After the algorithm is finished, it returns the unused items.
+        def self.call(items, available_width, &block)
+          obj = new(items, available_width)
+          if available_width.respond_to?(:call)
+            obj.variable_width_wrapping(&block)
+          else
+            obj.fixed_width_wrapping(&block)
+          end
+        end
+
+        private_class_method :new
+
+        # Creates a new line wrapping object that arranges the +items+ on lines with the given
+        # width.
+        def initialize(items, available_width)
+          @items = items
+          @available_width = @width_block = available_width
+          @line_items = []
+          @width = 0
+          @glue_items = []
+          @beginning_of_line_index = 0
+          @last_breakpoint_index = 0
+          @last_breakpoint_line_items_index = 0
+          @break_prohibited_state = false
+
+          @height_calc = LineFragment::HeightCalculator.new
+          @line_height = 0
+        end
+
+        # Peforms the line wrapping with a fixed width.
+        def fixed_width_wrapping
+          index = 0
+
+          while (item = @items[index])
+            case item.type
+            when :box
+              unless add_box_item(item.item)
+                if @break_prohibited_state
+                  index = reset_line_to_last_breakpoint_state
+                  item = @items[index]
+                end
+                break unless yield(create_line, item.item)
+                reset_after_line_break(index)
+                redo
+              end
+            when :glue
+              unless add_glue_item(item.item, index)
+                break unless yield(create_line, nil)
+                reset_after_line_break(index + 1)
+              end
+            when :penalty
+              if item.penalty <= -Penalty::INFINITY
+                break unless yield(create_unjustified_line, nil)
+                reset_after_line_break(index + 1)
+              elsif item.penalty >= Penalty::INFINITY
+                @break_prohibited_state = true
+                add_box_item(item.item) if item.width > 0
+              elsif item.width > 0
+                if item_fits_on_line?(item)
+                  next_index = index + 1
+                  next_item = @items[next_index]
+                  next_item = @items[next_index += 1] while next_item && next_item.type == :penalty
+                  if next_item && !item_fits_on_line?(next_item)
+                    @line_items.concat(@glue_items).push(item.item)
+                    @width += item.width
+                  end
+                  update_last_breakpoint(index)
+                else
+                  @break_prohibited_state = true
+                end
+              else
+                update_last_breakpoint(index)
+              end
+            end
+
+            index += 1
+          end
+
+          line = create_unjustified_line
+          last_line_used = true
+          last_line_used = yield(line, nil) if item.nil? && !line.items.empty?
+
+          item.nil? && last_line_used ? [] : @items[@beginning_of_line_index..-1]
+        end
+
+        # Performs the line wrapping with variable widths.
+        def variable_width_wrapping
+          index = 0
+          @available_width = @width_block.call(@line_height)
+
+          while (item = @items[index])
+            case item.type
+            when :box
+              new_height = @height_calc.simulate_height(item.item)
+              if new_height > @line_height
+                @line_height = new_height
+                @available_width = @width_block.call(@line_height)
+              end
+              if add_box_item(item.item)
+                @height_calc << item.item
+              else
+                if @break_prohibited_state
+                  index = reset_line_to_last_breakpoint_state
+                  item = @items[index]
+                end
+                break unless yield(create_line, item.item)
+                reset_after_line_break(index)
+                redo
+              end
+            when :glue
+              unless add_glue_item(item.item, index)
+                break unless yield(create_line, nil)
+                reset_after_line_break(index + 1)
+              end
+            when :penalty
+              if item.penalty <= -Penalty::INFINITY
+                break unless yield(create_unjustified_line, nil)
+                reset_after_line_break(index + 1)
+              elsif item.penalty >= Penalty::INFINITY
+                @break_prohibited_state = true
+                add_box_item(item.item) if item.width > 0
+              elsif item.width > 0
+                if item_fits_on_line?(item)
+                  next_index = index + 1
+                  next_item = @items[next_index]
+                  next_item = @items[n_index += 1] while next_item && next_item.type == :penalty
+                  new_height = @height_calc.simulate_height(next_item.item)
+                  if next_item && @width + next_item.width > @width_block.call(new_height)
+                    @line_items.concat(@glue_items).push(item.item)
+                    @width += item.width
+                    # No need to clean up, since in the next iteration a line break occurs
+                  end
+                  update_last_breakpoint(index)
+                else
+                  @break_prohibited_state = true
+                end
+              else
+                update_last_breakpoint(index)
+              end
+            end
+
+            index += 1
+          end
+
+          line = create_unjustified_line
+          last_line_used = true
+          last_line_used = yield(line, nil) if item.nil? && !line.items.empty?
+
+          item.nil? && last_line_used ? [] : @items[@beginning_of_line_index..-1]
+        end
+
+        private
+
+        # Adds the box item to the line items if it fits on the line.
+        #
+        # Returns +true+ if the item could be added and +false+ otherwise.
+        def add_box_item(item)
+          return false unless @width + item.width <= @available_width
+          @line_items.concat(@glue_items).push(item)
+          @width += item.width
+          @glue_items.clear
+          true
+        end
+
+        # Adds the glue item to the line items if it fits on the line.
+        #
+        # Returns +true+ if the item could be added and +false+ otherwise.
+        def add_glue_item(item, index)
+          return false unless @width + item.width <= @available_width
+          unless @line_items.empty? # ignore glue at beginning of line
+            @glue_items << item
+            @width += item.width
+            update_last_breakpoint(index)
+          end
+          true
+        end
+
+        # Updates the information on the last possible breakpoint of the current line.
+        def update_last_breakpoint(index)
+          @break_prohibited_state = false
+          @last_breakpoint_index = index
+          @last_breakpoint_line_items_index = @line_items.size
+        end
+
+        # Resets the line items array to contain only those items that were in it when the last
+        # breakpoint was encountered and returns the items' index of the last breakpoint.
+        def reset_line_to_last_breakpoint_state
+          @line_items.slice!(@last_breakpoint_line_items_index..-1)
+          @break_prohibited_state = false
+          @last_breakpoint_index
+        end
+
+        # Returns +true+ if the item fits on the line.
+        def item_fits_on_line?(item)
+          @width + item.width <= @available_width
+        end
+
+        # Creates a LineFragment object from the current line items.
+        def create_line
+          LineFragment.new(@line_items)
+        end
+
+        # Creates a LineFragment object from the current line items that ignores line justification.
+        def create_unjustified_line
+          create_line.tap(&:ignore_justification!)
+        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)
+          @beginning_of_line_index = index
+          @line_items.clear
+          @width = 0
+          @glue_items.clear
+          @last_breakpoint_index = index
+          @last_breakpoint_line_items_index = 0
+          @break_prohibited_state = false
+
+          @line_height = 0
+          @height_calc.reset
+        end
+
+      end
+
+
+      # Creates a new TextBox object for the given text and returns it.
+      #
+      # See ::new for information on +height+.
+      #
+      # The style of the text box 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)
+      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
+      attr_reader :style
+
+      # The items (TextFragment and InlineBox objects) of the text box that should be layed out.
+      attr_reader :items
+
+      # Array of LineFragment objects describing the lines of the text box.
+      #
+      # The array is only valid after #fit was called.
+      attr_reader :lines
+
+      # The actual height of the text box. 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 TextBox 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 of the box (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 box has infinite height.
+      def initialize(items: [], width:, height: nil, x_offsets: nil, style: Style.new)
+        @style = 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 box, 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_box.fit  -> [remaining_items, actual_height]
+      #
+      # Fits the items into the text box and returns the remaining items as well as the actual
+      # height needed.
+      #
+      # Note: If the text box height has not 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.
+      #
+      # 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 text box.
+      def fit
+        @lines.clear
+        @actual_height = 0
+        y_offset = 0
+
+        items = @items
+        if style.text_indent != 0
+          items = [Box.new(InlineBox.new(style.text_indent, 0) { })].concat(items)
+        end
+
+        if @width.respond_to?(:call)
+          width_arg = proc {|h| @width.call(@actual_height, h)}
+          width_block = @width
+        else
+          width_arg = @width
+          width_block = proc { @width }
+        end
+
+        rest = style.text_line_wrapping_algorithm.call(items, width_arg) do |line, item|
+          line << TextFragment.new(items: [], style: style) if item.nil? && line.items.empty?
+          new_height = @actual_height + line.height +
+            (@lines.empty? ? 0 : style.line_spacing.gap(@lines.last, line))
+
+          if new_height <= @height && !line.items.empty?
+            # valid line found, use it
+            cur_width = width_block.call(@actual_height, line.height)
+            line.x_offset = 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
+            true
+          elsif new_height <= @height && @height != Float::INFINITY
+            # some height left but item didn't fit on the line, search downwards for usable space
+            new_height = @actual_height
+            while item.width > width_block.call(new_height, item.height) && new_height <= @height
+              new_height += item.height / 3
+            end
+            if new_height + item.height <= @height
+              y_offset = new_height - @actual_height
+              @actual_height = new_height
+              true
+            else
+              nil
+            end
+          else
+            nil
+          end
+        end
+
+        [rest, @actual_height]
+      end
+
+      # Draws the text box 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 been called before.
+      # * If +false+, then #fit is never called.
+      def draw(canvas, x, y, fit: :if_needed)
+        self.fit if fit == true || (!@actual_height && fit == :if_needed)
+        return if @lines.empty?
+
+        canvas.save_graphics_state do
+          y -= initial_baseline_offset + @lines.first.y_offset
+          @lines.each_with_index do |line, index|
+            line_x = x + line.x_offset
+            line.each {|item, item_x, item_y| item.draw(canvas, line_x + item_x, y + item_y) }
+            y -= @lines[index + 1].y_offset if @lines[index + 1]
+          end
+        end
+      end
+
+      private
+
+      # Returns the initial baseline offset from the top of the text box, based on the valign style
+      # option.
+      def initial_baseline_offset
+        case style.valign
+        when :top
+          @lines.first.y_max
+        when :center
+          if @height == Float::INFINITY
+            raise HexaPDF::Error, "Can't vertically align a text box with unlimited height"
+          end
+          (@height - @actual_height) / 2.0 + @lines.first.y_max
+        when :bottom
+          if @height == Float::INFINITY
+            raise HexaPDF::Error, "Can't vertically align a text box with unlimited height"
+          end
+          (@height - @actual_height) + @lines.first.y_max
+        end
+      end
+
+      # Returns the horizontal offset from the left side, based on the align style option.
+      def horizontal_alignment_offset(line, available_width)
+        case style.align
+        when :left then 0
+        when :center then (available_width - line.width) / 2
+        when :right then available_width - line.width
+        when :justify then (justify_line(line, available_width); 0)
+        end
+      end
+
+      # Justifies the given line.
+      def justify_line(line, width)
+        return if line.ignore_justification? || (width - line.width).abs < 0.001
+
+        indexes = []
+        sum = 0.0
+        line.items.each_with_index do |item, item_index|
+          next if item.kind_of?(InlineBox)
+          item.items.each_with_index do |glyph, glyph_index|
+            if !glyph.kind_of?(Numeric) && glyph.str == ' '.freeze
+              sum += glyph.width * item.style.scaled_font_size
+              indexes << item_index << glyph_index
+            end
+          end
+        end
+
+        if sum > 0
+          adjustment = (width - line.width) / sum
+          i = indexes.length - 2
+          while i >= 0
+            frag = line.items[indexes[i]]
+            value = -frag.items[indexes[i + 1]].width * adjustment
+            if frag.items.frozen?
+              value = HexaPDF::Layout::TextFragment.new(items: [value], style: frag.style)
+              line.items.insert(indexes[i], value)
+            else
+              frag.items.insert(indexes[i + 1], value)
+              frag.clear_cache
+            end
+            i -= 2
+          end
+          line.clear_cache
+        end
+      end
+
+    end
+
+  end
+end