hexapdf 0.8.0 → 0.9.0

data/lib/hexapdf/layout/image_box.rb

@@ -0,0 +1,96 @@
+# -*- 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'
+
+module HexaPDF
+  module Layout
+
+    # An Image box object is used for displaying an image.
+    #
+    # How an image is displayed inside an image box, depends on whether the +width+ and/or +height+
+    # of the box has been set:
+    #
+    # * If one of them has been set, the other is adjusted to retain the image ratio.
+    # * If both have been set, both are used as is.
+    # * If neither has been set, the image is scaled to fit the available space.
+    #
+    # Also see: HexaPDF::Content::Canvas#image
+    class ImageBox < Box
+
+      # The image that is shown in the box.
+      attr_reader :image
+
+      # Creates a new Image box object for the given +image+ argument which needs to be an image
+      # object (e.g. returned by HexaPDF::Document::Images#add).
+      def initialize(image, **kwargs)
+        super(kwargs, &:unused_draw_block)
+        @image = image
+      end
+
+      # Fits the image into the available space.
+      def fit(available_width, available_height, _)
+        image_width = @image.width.to_f
+        image_height = @image.height.to_f
+        image_ratio = image_width / image_height
+
+        if @initial_width > 0 && @initial_height > 0
+          @width = @initial_width
+          @height = @initial_height
+        elsif @initial_width > 0
+          @width = @initial_width
+          @height = (@width - reserved_width) / image_ratio + reserved_height
+        elsif @initial_height > 0
+          @height = @initial_height
+          @width = (@height - reserved_height) * image_ratio + reserved_width
+        else
+          rw = reserved_width
+          rh = reserved_height
+          ratio = [(available_width - rw) / image_width, (available_height - rh) / image_height].min
+          @width = image_width * ratio + rw
+          @height = image_height * ratio + rh
+        end
+
+        @width <= available_width && @height <= available_height
+      end
+
+      private
+
+      # Draws the image onto the canvas at position [x, y].
+      def draw_content(canvas, x, y)
+        canvas.image(@image, at: [x, y], width: content_width, height: content_height)
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/layout/inline_box.rb

@@ -98,6 +98,16 @@ module HexaPDF
         width
       end
 
+      # The minimum y-coordinate which is always 0.
+      def y_min
+        0
+      end
+
+      # The maximum y-coordinate which is equivalent to the height of the inline box.
+      def y_max
+        height
+      end
+
     end
 
   end

data/lib/hexapdf/layout/line.rb

@@ -153,7 +153,7 @@ module HexaPDF
           max_bottom_height = @max_bottom_height
           max_text_bottom_height = @max_text_bottom_height
           y_min, y_max, = add(item).result
-          y_max - y_min
+          [y_min, y_max, y_max - y_min]
         ensure
           @text_y_min = text_y_min
           @text_y_max = text_y_max

data/lib/hexapdf/layout/style.rb

@@ -78,7 +78,7 @@ module HexaPDF
 
         # 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)
+        def initialize(type:, value: 1)
           case type
           when :single
             @type = :proportional
@@ -207,6 +207,14 @@ module HexaPDF
           @style = Quad.new(style)
         end
 
+        # Duplicates a Border object's properties.
+        def initialize_copy(other)
+          super
+          @width = @width.dup
+          @color = @color.dup
+          @style = @style.dup
+        end
+
         # Returns +true+ if there is no border.
         def none?
           width.simple? && width.top == 0
@@ -372,6 +380,12 @@ module HexaPDF
           @layers = layers
         end
 
+        # Duplicates the array holding the layers.
+        def initialize_copy(other)
+          super
+          @layers = @layers.dup
+        end
+
         # :call-seq:
         #   layers.add {|canvas, box| block}
         #   layers.add(name, **options)
@@ -510,6 +524,20 @@ module HexaPDF
         @scaled_item_widths = {}
       end
 
+      # Duplicates the complex properties that can be modified, as well as the cache.
+      def initialize_copy(other)
+        super
+        @scaled_item_widths = {}
+        clear_cache
+
+        @font_features = @font_features.dup if defined?(@font_features)
+        @padding = @padding.dup if defined?(@padding)
+        @margin = @margin.dup if defined?(@margin)
+        @border = @border.dup if defined?(@border)
+        @overlays = @overlays.dup if defined?(@overlays)
+        @underlays = @underlays.dup if defined?(@underlays)
+      end
+
       # :call-seq:
       #   style.update(**properties)    -> style
       #
@@ -724,6 +752,28 @@ module HexaPDF
       #
       # The indentation to be used for the first line of a sequence of text lines, defaults to 0.
 
+      ##
+      # :method: line_spacing
+      # :call-seq:
+      #   line_spacing(type = nil, value = nil)
+      #   line_spacing(type:, value: 1)
+      #
+      # The type of line spacing to be used for text lines, defaults to type :single.
+      #
+      # This method can set the line spacing in two ways:
+      #
+      # * Using two positional arguments +type+ and +value+.
+      # * Or a hash with the keys +type+ and +value+.
+      #
+      # See LineSpacing for supported types of line spacing.
+
+      ##
+      # :method: last_line_gap
+      # :call-seq:
+      #   last_line_gap(enable = false)
+      #
+      # Add an appropriately sized gap after the last line of text if enabled, defaults to false.
+
       ##
       # :method: background_color
       # :call-seq:
@@ -842,8 +892,10 @@ module HexaPDF
         [:align, :left],
         [:valign, :top],
         [:text_indent, 0],
-        [:line_spacing, "LineSpacing.new(:single)",
-         "LineSpacing.new(value, value: extra_arg)", ", extra_arg = nil"],
+        [:line_spacing, "LineSpacing.new(type: :single)",
+         "LineSpacing.new(value.kind_of?(Symbol) ? {type: value, value: extra_arg} : value)",
+         ", extra_arg = nil"],
+        [:last_line_gap, false],
         [:background_color, nil],
         [:padding, "Quad.new(0)", "Quad.new(value)"],
         [:margin, "Quad.new(0)", "Quad.new(value)"],

data/lib/hexapdf/layout/text_box.rb

@@ -56,26 +56,56 @@ module HexaPDF
       # 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.
+      #
+      # The spacing after the last line can be controlled via the style property +last_line_gap+.
+      #
+      # Also see TextLayouter#style for other style properties taken into account.
       def fit(available_width, available_height, frame)
+        @width = @height = 0
         @result = if style.position == :flow
                     @tl.fit(@items, frame.width_specification, frame.contour_line.bbox.height)
                   else
-                    @tl.fit(@items, available_width, available_height)
+                    @width = reserved_width
+                    @height = reserved_height
+                    width = (@initial_width > 0 ? @initial_width : available_width) - @width
+                    height = (@initial_height > 0 ? @initial_height : available_height) - @height
+                    @tl.fit(@items, width, height)
                   end
-        @height = @result.height
-        @width = @result.lines.max_by(&:width)&.width || 0
+        @width += @result.lines.max_by(&:width)&.width || 0
+        @height += @result.height
+        if style.last_line_gap && @result.lines.last
+          @height += style.line_spacing.gap(@result.lines.last, @result.lines.last)
+        end
+
+        @result.status == :success
+      end
+
+      # Splits the text box into two boxes if necessary and possible.
+      def split(available_width, available_height, frame)
+        fit(available_width, available_height, frame) unless @result
+        if @result.remaining_items.empty?
+          [self]
+        elsif @result.lines.empty?
+          [nil, self]
+        else
+          box = clone
+          box.instance_variable_set(:@result, nil)
+          box.instance_variable_set(:@items, @result.remaining_items)
+          [self, box]
+        end
+      end
 
-        success = (@result.status == :success)
-        @draw_block = success ? method(:draw_text) : nil
-        success
+      # :nodoc:
+      def empty?
+        super && (!@result || @result.lines.empty?)
       end
 
       private
 
       # Draws the text into the box.
-      def draw_text(canvas, _self)
+      def draw_content(canvas, x, y)
         return unless @result && !@result.lines.empty?
-        @result.draw(canvas, 0, @result.height)
+        @result.draw(canvas, x, y + content_height)
       end
 
     end

data/lib/hexapdf/layout/text_layouter.rb

@@ -276,6 +276,19 @@ module HexaPDF
         end
       end
 
+      # 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.
+      DummyLine = Struct.new(:y_min, :y_max) do
+        def update(y_min, y_max)
+          self.y_min = y_min
+          self.y_max = y_max
+        end
+
+        def height
+          y_max - y_min
+        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,
@@ -297,10 +310,11 @@ module HexaPDF
         #   is the indentation of the first line). This is the general case.
         #
         # * However, if lines should have varying widths (e.g. for flowing text around shapes), the
-        #   +width_block+ 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. This method involves more work
-        #   and is therefore slower.
+        #   +width_block+ argument should be an object responding to #call(line_like) where
+        #   +line_like+ is a Line-like object responding to #y_min, #y_max and #height holding the
+        #   values for the currently layed out line. The caller is responsible for tracking the
+        #   height of the already layed out lines. This method involves more work and is therefore
+        #   slower.
         #
         # 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 item that caused the line
@@ -332,7 +346,6 @@ module HexaPDF
         def initialize(items, width_block)
           @items = items
           @width_block = width_block
-          @available_width = @width_block.call(0)
           @line_items = []
           @width = 0
           @glue_items = []
@@ -342,7 +355,9 @@ module HexaPDF
           @break_prohibited_state = false
 
           @height_calc = Line::HeightCalculator.new
-          @line_height = 0
+          @line = DummyLine.new(0, 0)
+
+          @available_width = @width_block.call(@line)
         end
 
         # Peforms line wrapping with a fixed width per line, with line height playing no role.
@@ -408,14 +423,14 @@ module HexaPDF
           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)
+              y_min, y_max, new_height = @height_calc.simulate_height(item.item)
+              if new_height > @line.height
+                @line.update(y_min, y_max)
+                @available_width = @width_block.call(@line)
                 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)
+                  reset_after_line_break_variable_width(index)
                   redo
                 end
               end
@@ -427,18 +442,18 @@ module HexaPDF
                   item = @items[index]
                 end
                 break unless (action = yield(create_line, item))
-                reset_after_line_break_variable_width(index, 0, action)
+                reset_after_line_break_variable_width(index, true, action)
                 redo
               end
             when :glue
               unless add_glue_item(item.item, index)
                 break unless (action = yield(create_line, item))
-                reset_after_line_break_variable_width(index + 1, 0, action)
+                reset_after_line_break_variable_width(index + 1, true, action)
               end
             when :penalty
               if item.penalty <= -Penalty::INFINITY
                 break unless (action = yield(create_unjustified_line, item))
-                reset_after_line_break_variable_width(index + 1, 0, action)
+                reset_after_line_break_variable_width(index + 1, true, action)
               elsif item.penalty >= Penalty::INFINITY
                 @break_prohibited_state = true
                 add_box_item(item.item) if item.width > 0
@@ -447,8 +462,8 @@ module HexaPDF
                   next_index = index + 1
                   next_item = @items[next_index]
                   next_item = @items[next_index += 1] while 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)
+                  y_min, y_max, new_height = @height_calc.simulate_height(next_item.item)
+                  if next_item && @width + next_item.width > @width_block.call(DummyLine.new(y_min, y_max))
                     @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
@@ -531,7 +546,7 @@ module HexaPDF
         # Resets the line state variables to their initial values. The +index+ specifies the items
         # 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)
+        def reset_after_line_break(index)
           @beginning_of_line_index = index
           @line_items.clear
           @width = 0
@@ -539,7 +554,7 @@ module HexaPDF
           @last_breakpoint_index = index
           @last_breakpoint_line_items_index = 0
           @break_prohibited_state = false
-          @available_width = @width_block.call(line_height)
+          @available_width = @width_block.call(@line)
         end
 
         # Specialized reset method for variable width wrapping.
@@ -548,11 +563,11 @@ module HexaPDF
         #
         # * 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)
+        def reset_after_line_break_variable_width(index, reset_line = false, action = :none)
           @stored_index = @beginning_of_line_index if action == :store_start_of_line
-          @line_height = line_height
+          @line.update(0, 0) if reset_line
           @height_calc.reset
-          reset_after_line_break(index, line_height)
+          reset_after_line_break(index)
         end
 
       end
@@ -592,23 +607,23 @@ module HexaPDF
 
         # 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
+          last_text_fragment = 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
+            @lines.each do |line|
+              y -= line.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
+                            ignore_text_properties: last_text_fragment&.style == item.style)
+                  last_text_fragment = 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
+                  last_text_fragment = nil
                 end
               end
             end
@@ -681,21 +696,26 @@ module HexaPDF
         indent = style.text_indent
         line_fragments = []
         line_height = 0
-        last_line = nil
+        previous_line = nil
         y_offset = 0
         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)
+            previous_line_height = nil
+            proc do |cur_line|
+              line_height = [line_height, cur_line.height || 0].max
+              if last_actual_height != actual_height || previous_line_height != line_height
+                gap = if previous_line
+                        style.line_spacing.gap(previous_line, cur_line)
+                      else
+                        0
+                      end
+                spec = width.call(actual_height + gap, cur_line.height)
                 spec = [0, spec] unless spec.kind_of?(Array)
                 last_actual_height = actual_height
-                last_line_height = line_height
+                previous_line_height = line_height
               else
                 spec = width_spec
               end
@@ -732,7 +752,7 @@ module HexaPDF
             # 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
+              while item.width > width_block.call(item.item) && actual_height <= height
                 width_spec_index += 1
                 if width_spec_index >= width_spec.size / 2
                   actual_height += item.height / 3
@@ -761,11 +781,11 @@ module HexaPDF
 
             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)
+              (previous_line ? style.line_spacing.gap(previous_line, combined_line) : 0)
 
             if new_height <= height
               # valid line found, use it
-              apply_offsets(line_fragments, width_spec, indent, last_line, combined_line, y_offset)
+              apply_offsets(line_fragments, width_spec, indent, previous_line, combined_line, y_offset)
               lines.concat(line_fragments)
               line_fragments.clear
               width_spec_index = 0
@@ -774,7 +794,7 @@ module HexaPDF
                        else
                          0
                        end
-              last_line = combined_line
+              previous_line = combined_line
               actual_height = new_height
               line_height = 0
               y_offset = nil
@@ -805,16 +825,6 @@ module HexaPDF
 
       private
 
-      # :nodoc:
-      #
-      # 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
-
       # 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
@@ -828,7 +838,11 @@ module HexaPDF
       end
 
       # 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)
+      #
+      # Note that the offset for the first fragment of the first line is the top of the line since
+      # the #initial_baseline_offset method applies the correct offset to it once layouting is
+      # completely done.
+      def apply_offsets(line_frags, width_spec, indent, previous_line, combined_line, y_offset)
         cumulated_width = 0
         line_frags.each_with_index do |line, index|
           line.x_offset = cumulated_width + indent
@@ -838,12 +852,12 @@ module HexaPDF
           if index == 0
             line.y_offset = if y_offset
                               y_offset + combined_line.y_max -
-                                (last_line ? last_line.y_min : line.y_max)
+                                (previous_line ? previous_line.y_min : line.y_max)
                             else
-                              style.line_spacing.baseline_distance(last_line, combined_line)
+                              style.line_spacing.baseline_distance(previous_line, combined_line)
                             end
+            indent = 0
           end
-          indent = 0
         end
       end