hexapdf 0.21.1 → 0.24.0

data/lib/hexapdf/layout/column_box.rb

@@ -34,132 +34,211 @@
 # commercial licenses are available at <https://gettalong.at/hexapdf/>.
 #++
 require 'hexapdf/layout/box'
+require 'hexapdf/layout/box_fitter'
 
 module HexaPDF
   module Layout
 
     # A ColumnBox arranges boxes in one or more columns.
     #
-    # The number of columns as well as the size of the gap between the columns can be modified.
+    # The number and width of the columns as well as the size of the gap between the columns can be
+    # modified. Additionally, the contents can either fill the columns one after the other or the
+    # columns can be made equally high.
+    #
+    # If the column box has padding and/or borders specified, they are handled like with any other
+    # box. This means they are around all columns and their contents and are not used separately for
+    # each column.
+    #
+    # The following style properties are used (additionally to those used by the parent class):
+    #
+    # Style#position::
+    #    If this is set to :flow, the frames created for the columns will take the shape of the
+    #    frame into account. This also means that the +available_width+ and +available_height+
+    #    arguments are ignored.
     class ColumnBox < Box
 
-      # The child boxes of this ColumnBox.
+      # The child boxes of this ColumnBox. They need to be finalized before #fit is called.
       attr_reader :children
 
-      # The number of columns.
-      # TODO: allow array with column widths later like [100, :*, :*]; same for gaps
+      # The columns definition.
+      #
+      # This is an array containing the widths of the columns. The size of the array is the number
+      # of columns.
+      #
+      # If a negative integer is used for the width, the column is auto-sized. Such columns split
+      # the remaining width (after substracting the widths of the fixed columns) proportionally
+      # among them. For example, if the definition is [-1, -2, -2], the first column is a fifth of
+      # the width and the other columns are each two fifth of the width.
+      #
+      # Examples:
+      #
+      #   #>pdf-composer
+      #   composer.box(:column, columns: 2, gaps: 10,
+      #                children: [composer.document.layout.lorem_ipsum_box])
+      #
+      # ---
+      #
+      #   #>pdf-composer
+      #   composer.box(:column, columns: [50, -2, -1], gaps: [10, 5],
+      #                children: [composer.document.layout.lorem_ipsum_box])
       attr_reader :columns
 
-      # The size of the gap between the columns.
-      attr_reader :gap
+      # The size of the gaps between the columns.
+      #
+      # This is an array containing the width of the gaps. If there are more gaps than numbers in
+      # the array, the array is cycled.
+      #
+      # Examples: see #columns
+      attr_reader :gaps
+
+      # Determines whether the columns should all be equally high or not.
+      #
+      # Examples:
+      #
+      #   #>pdf-composer
+      #   composer.box(:column, children: [composer.document.layout.lorem_ipsum_box])
+      #
+      # ---
+      #
+      #   #>pdf-composer
+      #   composer.box(:column, equal_height: false,
+      #                children: [composer.document.layout.lorem_ipsum_box])
+      attr_reader :equal_height
 
-      # Creates a new ColumnBox object for the given +children+ boxes.
-      def initialize(children = [], columns = 2, gap: 36, **kwargs)
+      # Creates a new ColumnBox object for the given child boxes in +children+.
+      #
+      # +columns+::
+      #
+      #     Can either simply integer specify the number of columns or be a full column definition
+      #     (see #columns for details).
+      #
+      # +gaps+::
+      #     Can either be a simply integer specifying the width between two columns or a full gap
+      #     definition (see #gap for details).
+      #
+      # +equal_height+::
+      #     If +true+, the #fit method tries to balance the columns in terms of their height.
+      #     Otherwise the columns are filled from the left.
+      def initialize(children: [], columns: 2, gaps: 36, equal_height: true, **kwargs)
         super(**kwargs)
         @children = children
-        @columns = columns
-        @gap = gap
+        @columns = (columns.kind_of?(Array) ? columns : [-1] * columns)
+        @gaps = (gaps.kind_of?(Array) ? gaps : [gaps])
+        @equal_height = equal_height
+      end
+
+      # Returns +true+ as the 'position' style property value :flow is supported.
+      def supports_position_flow?
+        true
       end
 
       # Fits the column box into the available space.
+      #
+      # 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)
-        last_height_difference = 1_000_000
+        initial_fit_successful = (@equal_height ? 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
         height = if style.position == :flow
-                   frame.height
+                   (@initial_height > 0 ? @initial_height : frame.height) - reserved_height
                  else
                    (@initial_height > 0 ? @initial_height : available_height) - reserved_height
                  end
+
+        columns = calculate_columns(@width)
+        return false 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
+        successful_height = height
+        unsuccessful_height = 0
+
         while true
-          p '-'*100
-          @frames = []
-          if style.position == :flow
-            column_width = (frame.width - gap * (@columns - 1)).to_f / @columns
-            @columns.times do |col_nr|
-              left = (column_width + gap) * col_nr + frame.left
-              bottom = frame.bottom
-              rect = Geom2D::Polygon([left, bottom],
-                                     [left + column_width, bottom],
-                                     [left + column_width, bottom + height],
-                                     [left, bottom + height])
+          @box_fitter = BoxFitter.new
+
+          columns.each do |col_x, column_width|
+            column_left = left + col_x
+            column_bottom = top - height
+            if style.position == :flow
+              rect = Geom2D::Polygon([column_left, column_bottom],
+                                     [column_left + column_width, column_bottom],
+                                     [column_left + column_width, column_bottom + height],
+                                     [column_left, column_bottom + height])
               shape = Geom2D::Algorithms::PolygonOperation.run(frame.shape, rect, :intersection)
-              col_frame = Frame.new(left, bottom, column_width, height)
-              col_frame.shape = shape
-              @frames << col_frame
-            end
-            @frame_index = 0
-            @results = @children.map {|child_box| fit_box(child_box) }
-            @width = frame.width
-            @height = frame.height - @frames.min_by(&:y).y
-          else
-            width = (@initial_width > 0 ? @initial_width : available_width) - reserved_width
-            column_width = (width - gap * (@columns - 1)).to_f / @columns
-            @columns.times do |col_nr|
-              @frames << Frame.new((column_width + gap) * col_nr, 0, column_width, height)
             end
-            @frame_index = 0
-            @results = @children.map {|child_box| fit_box(child_box) }
-            @width = width
-            @height = height - @frames.min_by(&:y).y
+            column_frame = Frame.new(column_left, column_bottom, column_width, height, shape: shape)
+            @box_fitter << column_frame
           end
-          min_y, max_y = @frames.minmax_by(&:y).map(&:y)
-          p [height, @frames.map(&:y), last_height_difference, min_y, max_y]
-          # TOOD: @result.any?(&:empty?) only for the first run!!!! if the first run fails, we
-          # cannot balance the columns because there is too much content.
-          # TODO: another break condition is if the @results didn't change since the last run
-          p [:maybe_redo, min_y, max_y, height, last_height_difference]
-          p [@results.map {|arr| arr.all? {|r| r.status }}]
-          break if max_y != height && @results.all? {|arr| !arr.empty? && arr.all? {|r| r.success? }} &&
-            (@results.any?(&:empty?) ||
-             max_y - min_y >= last_height_difference ||
-             max_y - min_y < 0.5)
-          if max_y == 0 && min_y == 0
-            height += last_height_difference / 4.0
-          else
-            last_height_difference = max_y - min_y
-            height -= last_height_difference / 2.0
+
+          children.each {|box| @box_fitter.fit(box) }
+
+          fit_successful = @box_fitter.fit_successful?
+          initial_fit_successful = fit_successful if initial_fit_successful.nil?
+
+          if fit_successful
+            successful_height = height if successful_height > height
+          elsif unsuccessful_height < height
+            unsuccessful_height = height
           end
+
+          break if !initial_fit_successful || tries > 40 ||
+            (fit_successful && successful_height - unsuccessful_height < 10)
+
+          height = if successful_height - unsuccessful_height <= 5
+                     successful_height
+                   else
+                     (successful_height + unsuccessful_height) / 2.0
+                   end
+          tries += 1
         end
-        @results.all? {|res| res.length == 1 }
+
+        @width = columns[-1].sum + reserved_width
+        @height = @box_fitter.content_heights.max + reserved_height
+
+        @box_fitter.fit_successful?
       end
 
       private
 
-      def fit_box(box)
-        cur_frame = @frames[@frame_index]
-        fit_results = []
-        while cur_frame
-          result = cur_frame.fit(box)
-          if result.success?
-            cur_frame.remove_area(result.mask)
-            fit_results << result
-            break
-          elsif cur_frame.full?
-            @frame_index += 1
-            break if @frame_index == @frames.length
-            cur_frame = @frames[@frame_index]
-          else
-            draw_box, box = cur_frame.split(result)
-            if draw_box
-              cur_frame.remove_area(result.mask)
-              fit_results << result
-            elsif !cur_frame.find_next_region
-              @frame_index += 1
-              break if @frame_index == @frames.length
-              cur_frame = @frames[@frame_index]
-            end
-          end
+      # Calculates the x-coordinates and widths of all columns based on the given total available
+      # width.
+      #
+      # If it is not possible to fit all columns into the given +width+, an empty array is returned.
+      def calculate_columns(width)
+        number_of_columns = @columns.size
+        gaps = @gaps.cycle.take(number_of_columns - 1)
+        fixed_width, variable_width = @columns.partition(&:positive?).map {|c| c.sum(&:abs) }
+        rest_width = width - fixed_width - gaps.sum
+        return [] if rest_width <= 0
+
+        variable_width_unit = rest_width / variable_width.to_f
+        position = 0
+        @columns.map.with_index do |column, index|
+          result = if column > 0
+                     [position, column]
+                   else
+                     [position, column.abs * variable_width_unit]
+                   end
+          position += result[1] + (gaps[index] || 0)
+          result
         end
-        fit_results
+      end
+
+      # Splits the content of the column box. This method is called from Box#split.
+      def split_content(_available_width, _available_height, _frame)
+        box = create_split_box
+        box.instance_variable_set(:@children, @box_fitter.remaining_boxes)
+        [self, box]
       end
 
       # Draws the child boxes onto the canvas at position [x, y].
-      def draw_content(canvas, x, y)
-        x = y = 0 if style.position == :flow
-        @results.each do |result_boxes|
-          result_boxes.each do |result|
-            result.box.draw(canvas, x + result.x, y + result.y)
-          end
-        end
+      def draw_content(canvas, _x, _y)
+        @box_fitter.fit_results.each {|result| result.draw(canvas) }
       end
 
     end