hexapdf 0.42.0 → 0.44.0

data/lib/hexapdf/layout/column_box.rb

@@ -138,31 +138,29 @@ module HexaPDF
         super && (!@box_fitter || @box_fitter.fit_results.empty?)
       end
 
+      private
+
       # Fits the column box into the current region of the frame.
       #
-      # If the style property 'position' is set to :flow, the columns might not be rectangles but
-      # arbitrary (sets of) polygons since the +frame+s shape is taken into account.
-      def fit(available_width, available_height, frame)
-        return false if @initial_height > available_height || @initial_width > available_width
-
+      def fit_content(available_width, available_height, frame)
         initial_fit_successful = (@equal_height && @columns.size > 1 ? nil : false)
         tries = 0
-        @width = if style.position == :flow
-                   (@initial_width > 0 ? @initial_width : frame.width) - reserved_width
-                 else
-                   (@initial_width > 0 ? @initial_width : available_width) - reserved_width
-                 end
+        width = if style.position == :flow
+                  (@initial_width > 0 ? @initial_width : frame.width) - reserved_width
+                else
+                  (@initial_width > 0 ? @initial_width : available_width) - reserved_width
+                end
         height = if style.position == :flow
-                   (@initial_height > 0 ? @initial_height : frame.height) - reserved_height
+                   (@initial_height > 0 ? @initial_height : frame.y - frame.bottom) - reserved_height
                  else
                    (@initial_height > 0 ? @initial_height : available_height) - reserved_height
                  end
 
-        columns = calculate_columns(@width)
-        return false if columns.empty?
+        columns = calculate_columns(width)
+        return if columns.empty?
 
         left = (style.position == :flow ? frame.left : frame.x) + reserved_width_left
-        top = (style.position == :flow ? frame.bottom + frame.height : frame.y) - reserved_height_top
+        top = frame.y - reserved_height_top
         successful_height = height
         unsuccessful_height = 0
 
@@ -186,7 +184,7 @@ module HexaPDF
 
           children.each {|box| @box_fitter.fit(box) }
 
-          fit_successful = @box_fitter.fit_successful?
+          fit_successful = @box_fitter.success?
           initial_fit_successful = fit_successful if initial_fit_successful.nil?
 
           if fit_successful
@@ -206,16 +204,16 @@ module HexaPDF
           tries += 1
         end
 
-        @width = columns[-1].sum + reserved_width
-        @height = (@initial_height > 0 ? @initial_height : @box_fitter.content_heights.max + reserved_height)
-        @draw_pos_x = frame.x + reserved_width_left
-        @draw_pos_y = frame.y - @height + reserved_height_bottom
+        update_content_width { columns[-1].sum }
+        update_content_height { @box_fitter.content_heights.max }
 
-        @box_fitter.fit_successful?
+        if @box_fitter.success?
+          fit_result.success!
+        elsif !@box_fitter.fit_results.empty?
+          fit_result.overflow!
+        end
       end
 
-      private
-
       # Calculates the x-coordinates and widths of all columns based on the given total available
       # width.
       #
@@ -241,7 +239,7 @@ module HexaPDF
       end
 
       # Splits the content of the column box. This method is called from Box#split.
-      def split_content(_available_width, _available_height, _frame)
+      def split_content
         box = create_split_box
         box.instance_variable_set(:@children, @box_fitter.remaining_boxes)
         [self, box]
@@ -249,8 +247,8 @@ module HexaPDF
 
       # Draws the child boxes onto the canvas at position [x, y].
       def draw_content(canvas, x, y)
-        if style.position != :flow && (x != @draw_pos_x || y != @draw_pos_y)
-          canvas.translate(x - @draw_pos_x, y - @draw_pos_y) do
+        if style.position != :flow && (x != @fit_x || y != @fit_y)
+          canvas.translate(x - @fit_x, y - @fit_y) do
             @box_fitter.fit_results.each {|result| result.draw(canvas) }
           end
         else

data/lib/hexapdf/layout/container_box.rb

@@ -137,17 +137,17 @@ module HexaPDF
         @box_fitter = BoxFitter.new([my_frame])
         children.each {|box| @box_fitter.fit(box) }
 
-        if @box_fitter.fit_successful?
+        if @box_fitter.success?
           update_content_width do
             result = @box_fitter.fit_results.max_by {|r| r.mask.x + r.mask.width }
             children.empty? ? 0 : result.mask.x + result.mask.width - my_frame.left
           end
           update_content_height { @box_fitter.content_heights.max }
-          true
+          fit_result.success!
         end
       end
 
-      # Draws the image onto the canvas at position [x, y].
+      # Draws the children onto the canvas at position [x, y].
       def draw_content(canvas, x, y)
         dx = x - @fit_x
         dy = y - @fit_y

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:
     #
@@ -54,7 +54,7 @@ module HexaPDF
     #
     #   The method #fit is also called for absolutely positioned boxes but since these boxes are not
     #   subject to the normal constraints, the provided available width and height are the width and
-    #   height inside the frame to the right and top of the bottom-left corner of the box.
+    #   height inside the frame to the right and top of the bottom left corner of the box.
     #
     # * If the box didn't fit, call #find_next_region to determine the next region for placing the
     #   box. If a new region was found, start over with #fit. Otherwise the frame has no more space
@@ -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,84 +84,10 @@ 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.
+      # The x-coordinate of the bottom left corner.
       attr_reader :left
 
-      # The y-coordinate of the bottom-left corner.
+      # The y-coordinate of the bottom left corner.
       attr_reader :bottom
 
       # The width of the frame.
@@ -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,7 @@ 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)
 
           width = box.width
           height = box.height
@@ -372,27 +293,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

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/line.rb

@@ -173,6 +173,10 @@ module HexaPDF
       attr_accessor :items
 
       # An optional horizontal offset that should be taken into account when positioning the line.
+      #
+      # This offset always describes the offset from the left side (and not, for example, the offset
+      # from the right side of another line even if those two lines are actually on the same
+      # horizontal level).
       attr_accessor :x_offset
 
       # An optional vertical offset that should be taken into account when positioning the line.

data/lib/hexapdf/layout/list_box.rb

@@ -186,8 +186,10 @@ module HexaPDF
         super && (!@results || @results.all? {|result| result.box_fitter.fit_results.empty? })
       end
 
+      private
+
       # Fits the list box into the current region of the frame.
-      def fit(available_width, available_height, frame)
+      def fit_content(available_width, available_height, frame)
         @width = if @initial_width > 0
                    @initial_width
                  else
@@ -248,20 +250,18 @@ module HexaPDF
           top -= item_result.height + item_spacing
           height -= item_result.height + item_spacing
 
-          break if !box_fitter.fit_successful? || height <= 0
+          break if !box_fitter.success? || height <= 0
         end
 
         @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.fit_successful? } &&
-          @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 +307,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 +361,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

@@ -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:
       #

data/lib/hexapdf/layout/table_box.rb

@@ -211,21 +211,27 @@ 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)
+            @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! if child_result.success?
           when Array
             box_fitter = BoxFitter.new([frame])
             children.each {|box| box_fitter.fit(box) }
@@ -233,34 +239,23 @@ module HexaPDF
             @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.fit_successful?
+            fit_result.success! if box_fitter.success?
           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 +388,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 +584,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.
+        # 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 +610,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 +646,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].