hexapdf 0.43.0 → 0.45.0

data/lib/hexapdf/layout/frame.rb

@@ -45,7 +45,7 @@ module HexaPDF
     #
     # == Usage
     #
-    # After a Frame object is initialized, it is ready for drawing boxes on it.
+    # After a Frame object is initialized, it is ready for fitting boxes in it and drawing them.
     #
     # The explicit way of drawing a box follows these steps:
     #
@@ -65,10 +65,6 @@ module HexaPDF
     #   splitting is successful, the first box can be drawn (Make sure that the second box is
     #   handled correctly). Otherwise, start over with #find_next_region.
     #
-    # For applications where splitting is not necessary, an easier way is to just use #draw and
-    # #find_next_region together, as #draw calls #fit if the box was not fit into the current
-    # region.
-    #
     # == Used Box Properties
     #
     # The style properties 'position', 'align', 'valign', 'margin' and 'mask_mode' are taken into
@@ -88,80 +84,6 @@ module HexaPDF
 
       include HexaPDF::Utils
 
-      # Stores the result of fitting a box in a Frame.
-      class FitResult
-
-        # The frame into which the box was fitted.
-        attr_accessor :frame
-
-        # The box that was fitted into the frame.
-        attr_accessor :box
-
-        # The horizontal position where the box will be drawn.
-        attr_accessor :x
-
-        # The vertical position where the box will be drawn.
-        attr_accessor :y
-
-        # The available width in the frame for this particular box.
-        attr_accessor :available_width
-
-        # The available height in the frame for this particular box.
-        attr_accessor :available_height
-
-        # The rectangle (a Geom2D::Rectangle object) that will be removed from the frame when
-        # drawing the box.
-        attr_accessor :mask
-
-        # Initialize the result object for the given frame and box.
-        def initialize(frame, box)
-          @frame = frame
-          @box = box
-          @available_width = 0
-          @available_height = 0
-          @success = false
-        end
-
-        # Marks the fitting status as success.
-        def success!
-          @success = true
-        end
-
-        # Returns +true+ if fitting was successful.
-        def success?
-          @success
-        end
-
-        # Draws the #box onto the canvas at (#x + *dx*, #y + *dy*).
-        #
-        # The relative offset (dx, dy) is useful when rendering results that were accumulated and
-        # then need to be moved because the container holding them changes its position.
-        #
-        # The configuration option "debug" can be used to add visual debug output with respect to
-        # box placement.
-        def draw(canvas, dx: 0, dy: 0)
-          doc = canvas.context.document
-          if doc.config['debug']
-            name = (frame.parent_boxes + [box]).map do |box|
-              box.class.to_s.sub(/.*::/, '')
-            end.join('-') << "##{box.object_id}"
-            name = "#{name} (#{(x + dx).to_i},#{(y + dy).to_i}-#{mask.width.to_i}x#{mask.height.to_i})"
-            ocg = doc.optional_content.ocg(name)
-            canvas.optional_content(ocg) do
-              canvas.translate(dx, dy) do
-                canvas.fill_color("green").stroke_color("darkgreen").
-                  opacity(fill_alpha: 0.1, stroke_alpha: 0.2).
-                  draw(:geom2d, object: mask, path_only: true).fill_stroke
-              end
-            end
-            page = "Page #{canvas.context.index + 1}" rescue "XObject"
-            doc.optional_content.default_configuration.add_ocg_to_ui(ocg, path: ['Debug', page])
-          end
-          box.draw(canvas, x + dx, y + dy)
-        end
-
-      end
-
       # The x-coordinate of the bottom-left corner.
       attr_reader :left
 
@@ -205,7 +127,7 @@ module HexaPDF
 
       # An array of box objects representing the parent boxes.
       #
-      # The immediate parent is the last array entry, the top most parent the first one. All boxes
+      # The immediate parent is the last array entry, the top-most parent the first one. All boxes
       # that are fitted into this frame have to be child boxes of the immediate parent box.
       attr_reader :parent_boxes
 
@@ -253,16 +175,15 @@ module HexaPDF
         @context&.document
       end
 
-      # Fits the given box into the current region of available space and returns a FitResult
-      # object.
+      # Fits the given box into the current region of available space and returns the associated
+      # Box::FitResult object.
       #
       # Fitting a box takes the style properties 'position', 'align', 'valign', 'margin', and
       # 'mask_mode' into account.
       #
-      # Use the FitResult#success? method to determine whether fitting was successful.
+      # Use the Box::FitResult#success? method to determine whether fitting was successful.
       def fit(box)
-        fit_result = FitResult.new(self, box)
-        return fit_result if full?
+        return Box::FitResult.new(box, frame: self) if full?
 
         margin = box.style.margin if box.style.margin?
 
@@ -277,7 +198,7 @@ module HexaPDF
 
           aw = width - x
           ah = height - y
-          box.fit(aw, ah, self)
+          fit_result = box.fit(aw, ah, self)
           fit_result.success!
 
           x += left
@@ -294,7 +215,8 @@ module HexaPDF
             ah -= margin_top = margin.top unless float_equal(@y, @bottom + @height)
           end
 
-          fit_result.success! if box.fit(aw, ah, self)
+          fit_result = box.fit(aw, ah, self)
+          return fit_result if fit_result.failure?
 
           width = box.width
           height = box.height
@@ -372,27 +294,24 @@ module HexaPDF
             create_rectangle(@x, @y - available_height, @x + available_width, @y)
           end
 
-        fit_result.available_width = aw
-        fit_result.available_height = ah
         fit_result.x = x
         fit_result.y = y
         fit_result.mask = rectangle
         fit_result
       end
 
-      # Tries to split the box of the given FitResult into two parts and returns both parts.
+      # Tries to split the box of the given Box::FitResult into two parts and returns both parts.
       #
       # See Box#split for further details.
       def split(fit_result)
-        fit_result.box.split(fit_result.available_width, fit_result.available_height, self)
+        fit_result.box.split
       end
 
-      # Draws the box of the given FitResult onto the canvas at the fitted position.
+      # Draws the box of the given Box::FitResult onto the canvas at the fitted position.
       #
       # After a box is successfully drawn, the frame's shape is adjusted to remove the occupied
       # area.
       def draw(canvas, fit_result)
-        return if fit_result.box.height == 0 || fit_result.box.width == 0
         fit_result.draw(canvas)
         remove_area(fit_result.mask)
       end
@@ -464,7 +383,7 @@ module HexaPDF
       # Since not all text may start at the top of the frame, the offset argument can be used to
       # specify a vertical offset from the top of the frame where layouting should start.
       #
-      # To be compatible with TextLayouter, the top left corner of the bounding box of the frame's
+      # To be compatible with TextLayouter, the top-left corner of the bounding box of the frame's
       # shape is the origin of the coordinate system for the width specification, with positive
       # x-values to the right and positive y-values downwards.
       #

data/lib/hexapdf/layout/image_box.rb

@@ -79,9 +79,11 @@ module HexaPDF
         false
       end
 
+      private
+
       # Fits the image into the current region of the frame, taking the initially set width and
       # height into account (see the class description for details).
-      def fit(available_width, available_height, _frame)
+      def fit_content(available_width, available_height, _frame)
         image_width = @image.width.to_f
         image_height = @image.height.to_f
         image_ratio = image_width / image_height
@@ -103,12 +105,10 @@ module HexaPDF
           @height = image_height * ratio + rh
         end
 
-        @fit_successful = float_compare(@width, available_width) <= 0 &&
+        fit_result.success! if float_compare(@width, available_width) <= 0 &&
           float_compare(@height, available_height) <= 0
       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)

data/lib/hexapdf/layout/list_box.rb

@@ -186,20 +186,12 @@ module HexaPDF
         super && (!@results || @results.all? {|result| result.box_fitter.fit_results.empty? })
       end
 
-      # Fits the list box into the current region of the frame.
-      def fit(available_width, available_height, frame)
-        @width = if @initial_width > 0
-                   @initial_width
-                 else
-                   (style.position == :flow ? frame.width : available_width)
-                 end
-        height = if @initial_height > 0
-                   @initial_height - reserved_height
-                 else
-                   (style.position == :flow ? frame.y - frame.bottom : available_height) - reserved_height
-                 end
+      private
 
+      # Fits the list box into the current region of the frame.
+      def fit_content(_available_width, _available_height, frame)
         width = @width - reserved_width
+        height = @height - reserved_height
         left = (style.position == :flow ? frame.left : frame.x) + reserved_width_left
         top = frame.y - reserved_height_top
 
@@ -243,7 +235,7 @@ module HexaPDF
           Array(child).each {|ibox| box_fitter.fit(ibox) }
           item_result.box_fitter = box_fitter
           item_result.height = [item_result.height.to_i, box_fitter.content_heights[0]].max
-          @results << item_result
+          @results << item_result unless box_fitter.fit_results.empty?
 
           top -= item_result.height + item_spacing
           height -= item_result.height + item_spacing
@@ -253,15 +245,13 @@ module HexaPDF
 
         @height = @results.sum(&:height) + (@results.count - 1) * item_spacing + reserved_height
 
-        @draw_pos_x = frame.x + reserved_width_left
-        @draw_pos_y = frame.y - @height + reserved_height_bottom
-        @all_items_fitted = @results.all? {|r| r.box_fitter.success? } &&
-          @results.size == @children.size
-        @fit_successful = @all_items_fitted || (@initial_height > 0 && style.overflow == :truncate)
+        if @results.size == @children.size && @results.all? {|r| r.box_fitter.success? }
+          fit_result.success!
+        elsif !@results.empty? && !@results[0].box_fitter.fit_results.empty?
+          fit_result.overflow!
+        end
       end
 
-      private
-
       # Removes the +content_indentation+ from the left side of the given shape (a Geom2D::PolygonSet).
       def remove_indent_from_frame_shape(shape)
         polygon_index = 0
@@ -307,7 +297,7 @@ module HexaPDF
       end
 
       # Splits the content of the list box. This method is called from Box#split.
-      def split_content(_available_width, _available_height, _frame)
+      def split_content
         remaining_boxes = @results[-1].box_fitter.remaining_boxes
         first_is_split_box = !remaining_boxes.empty?
         children = (remaining_boxes.empty? ? [] : [remaining_boxes]) + @children[@results.size..-1]
@@ -361,17 +351,9 @@ module HexaPDF
 
       # Draws the list items onto the canvas at position [x, y].
       def draw_content(canvas, x, y)
-        if !@all_items_fitted && (@initial_height > 0 && style.overflow == :error)
-          raise HexaPDF::Error, "Some items don't fit into box with limited height and " \
-            "style property overflow is set to :error"
-        end
+        translate = style.position != :flow && (x != @fit_x || y != @fit_y)
 
-        translate = style.position != :flow && (x != @draw_pos_x || y != @draw_pos_y)
-
-        if translate
-          canvas.save_graphics_state
-          canvas.translate(x - @draw_pos_x, y - @draw_pos_y)
-        end
+        canvas.save_graphics_state.translate(x - @fit_x, y - @fit_y) if translate
 
         @results.each do |item_result|
           box_fitter = item_result.box_fitter

data/lib/hexapdf/layout/style.rb

@@ -393,7 +393,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
-      # bottom left 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+.
@@ -1254,7 +1254,11 @@ module HexaPDF
       #     doesn't. If a box doesn't support this value, it is positioned as if the value :default
       #     was set.
       #
-      #     Note that the properties #align and #valign are not used with this value!
+      #     Notes:
+      #
+      #     * The properties #align and #valign are not used with this value.
+      #     * The rectangular area of the box is the rectangle containing all the flowed content.
+      #       That rectangle is used for drawing the border, background and so on.
       #
       #     Examples:
       #
@@ -1264,8 +1268,8 @@ module HexaPDF
       #       composer.lorem_ipsum(position: :flow)
       #
       # [x, y]::
-      #     Position the box with the bottom left corner at the given absolute position relative to
-      #     the bottom left corner of the frame.
+      #     Position the box with the bottom-left corner at the given absolute position relative to
+      #     the bottom-left corner of the frame.
       #
       #     Examples:
       #

data/lib/hexapdf/layout/table_box.rb

@@ -211,56 +211,55 @@ module HexaPDF
           @height = height
         end
 
+        # :nodoc:
+        def inspect
+          "<Cell (#{row},#{column}) #{row_span}x#{col_span} #{Array(children).map(&:class)}>"
+        end
+
+        private
+
         # Fits the children of the table cell into the given rectangular area.
-        def fit(available_width, available_height, frame)
-          @width = available_width
+        def fit_content(available_width, available_height, frame)
           width = available_width - reserved_width
-          height = available_height - reserved_height
-          return false if width <= 0 || height <= 0
+          height = @used_height = available_height - reserved_height
+          return if width <= 0 || height <= 0
 
           frame = frame.child_frame(0, 0, width, height, box: self)
           case children
           when Box
-            fit_result = frame.fit(children)
-            @preferred_width = fit_result.x + fit_result.box.width + reserved_width
-            @height = @preferred_height = fit_result.box.height + reserved_height
-            @fit_results = [fit_result]
-            @fit_successful = fit_result.success?
+            child_result = frame.fit(children)
+            if child_result.success?
+              @preferred_width = child_result.x + child_result.box.width + reserved_width
+              @height = @preferred_height = child_result.box.height + reserved_height
+              @fit_results = [child_result]
+              fit_result.success!
+            end
           when Array
             box_fitter = BoxFitter.new([frame])
             children.each {|box| box_fitter.fit(box) }
-            max_x_result = box_fitter.fit_results.max_by {|result| result.x + result.box.width }
-            @preferred_width = max_x_result.x + max_x_result.box.width + reserved_width
-            @height = @preferred_height = box_fitter.content_heights[0] + reserved_height
-            @fit_results = box_fitter.fit_results
-            @fit_successful = box_fitter.success?
+            if box_fitter.success?
+              max_x_result = box_fitter.fit_results.max_by {|result| result.x + result.box.width }
+              @preferred_width = max_x_result.x + max_x_result.box.width + reserved_width
+              @height = @preferred_height = box_fitter.content_heights[0] + reserved_height
+              @fit_results = box_fitter.fit_results
+              fit_result.success!
+            end
           else
             @preferred_width = reserved_width
             @height = @preferred_height = reserved_height
             @fit_results = []
-            @fit_successful = true
+            fit_result.success!
           end
         end
 
-        # :nodoc:
-        def inspect
-          "<Cell (#{row},#{column}) #{row_span}x#{col_span} #{Array(children).map(&:class)}>"
-        end
-
-        private
-
         # Draws the content of the cell.
         def draw_content(canvas, x, y)
           return if @fit_results.empty?
 
           # available_width is always equal to content_width but we need to adjust for the
           # difference in the y direction between fitting and drawing
-          y -= (@fit_results[0].available_height - content_height)
-          @fit_results.each do |fit_result|
-            #fit_result.x += x
-            #fit_result.y += y
-            fit_result.draw(canvas, dx: x, dy: y)
-          end
+          y -= (@used_height - content_height)
+          @fit_results.each {|fit_result| fit_result.draw(canvas, dx: x, dy: y) }
         end
 
       end
@@ -393,7 +392,7 @@ module HexaPDF
                                      else
                                        column_info[cell.column].last
                                      end
-              unless cell.fit(available_cell_width, available_height, frame)
+              unless cell.fit(available_cell_width, available_height, frame).success?
                 row_fit = false
                 break
               end
@@ -589,24 +588,23 @@ module HexaPDF
         super && (!@last_fitted_row_index || @last_fitted_row_index < 0)
       end
 
-      # Fits the table into the current region of the frame.
-      def fit(available_width, available_height, frame)
-        return false if (@initial_width > 0 && @initial_width > available_width) ||
-          (@initial_height > 0 && @initial_height > available_height)
+      private
 
+      # Fits the table into the current region of the frame.
+      def fit_content(_available_width, _available_height, frame)
         # Adjust reserved width/height to include space used by the edge cells for their border
         # since cell borders are drawn on the bounds and not inside.
         # This uses the top-left and bottom-right cells and so might not be correct in all cases.
         @cell_tl_border_width = @cells[0, 0].style.border.width
         cell_br_border_width = @cells[-1, -1].style.border.width
-        rw = reserved_width + (@cell_tl_border_width.left + cell_br_border_width.right) / 2.0
-        rh = reserved_height + (@cell_tl_border_width.top + cell_br_border_width.bottom) / 2.0
+        rw = (@cell_tl_border_width.left + cell_br_border_width.right) / 2.0
+        rh = (@cell_tl_border_width.top + cell_br_border_width.bottom) / 2.0
 
-        width = (@initial_width > 0 ? @initial_width : available_width) - rw
-        height = (@initial_height > 0 ? @initial_height : available_height) - rh
+        width = @width - reserved_width - rw
+        height = @height - reserved_height - rh
         used_height = 0
         columns = calculate_column_widths(width)
-        return false if columns.empty?
+        return if columns.empty?
 
         frame = frame.child_frame(box: self)
         @special_cells_fit_not_successful = false
@@ -616,18 +614,21 @@ module HexaPDF
           height -= special_used_height
           used_height += special_used_height
           @special_cells_fit_not_successful = (last_fitted_row_index != special_cells.number_of_rows - 1)
-          return false if @special_cells_fit_not_successful
+          return nil if @special_cells_fit_not_successful
         end
 
         main_used_height, @last_fitted_row_index = @cells.fit_rows(@start_row_index, height, columns, frame)
         used_height += main_used_height
 
-        @width = (@initial_width > 0 ? @initial_width : columns[-1].sum + rw)
-        @height = (@initial_height > 0 ? @initial_height : used_height + rh)
-        @fit_successful = (@last_fitted_row_index == @cells.number_of_rows - 1)
-      end
+        update_content_width { columns[-1].sum + rw }
+        update_content_height { used_height + rh }
 
-      private
+        if @last_fitted_row_index == @cells.number_of_rows - 1
+          fit_result.success!
+        elsif @last_fitted_row_index >= 0
+          fit_result.overflow!
+        end
+      end
 
       # Calculates and returns the x-coordinates and widths of all columns based on the given total
       # available width.
@@ -649,20 +650,16 @@ module HexaPDF
       end
 
       # Splits the content of the table box. This method is called from Box#split.
-      def split_content(_available_width, _available_height, _frame)
-        if @special_cells_fit_not_successful || @last_fitted_row_index < 0
-          [nil, self]
-        else
-          box = create_split_box
-          box.instance_variable_set(:@start_row_index, @last_fitted_row_index + 1)
-          box.instance_variable_set(:@last_fitted_row_index, -1)
-          box.instance_variable_set(:@special_cells_fit_not_successful, nil)
-          header_cells = @header ? Cells.new(@header.call(self), cell_style: @cell_style) : nil
-          box.instance_variable_set(:@header_cells, header_cells)
-          footer_cells = @footer ? Cells.new(@footer.call(self), cell_style: @cell_style) : nil
-          box.instance_variable_set(:@footer_cells, footer_cells)
-          [self, box]
-        end
+      def split_content
+        box = create_split_box
+        box.instance_variable_set(:@start_row_index, @last_fitted_row_index + 1)
+        box.instance_variable_set(:@last_fitted_row_index, -1)
+        box.instance_variable_set(:@special_cells_fit_not_successful, nil)
+        header_cells = @header ? Cells.new(@header.call(self), cell_style: @cell_style) : nil
+        box.instance_variable_set(:@header_cells, header_cells)
+        footer_cells = @footer ? Cells.new(@footer.call(self), cell_style: @cell_style) : nil
+        box.instance_variable_set(:@footer_cells, footer_cells)
+        [self, box]
       end
 
       # Draws the child boxes onto the canvas at position [x, y].