hexapdf 0.23.0 → 0.24.0

data/lib/hexapdf/layout/box.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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
@@ -40,6 +40,8 @@ module HexaPDF
 
     # The base class for all layout boxes.
     #
+    # == Box Model
+    #
     # HexaPDF uses the following box model:
     #
     # * Each box can specify a width and height. Padding and border are inside, the margin outside
@@ -49,12 +51,35 @@ module HexaPDF
     #   the content box without padding and the border.
     #
     # * If width or height is set to zero, they are determined automatically during layouting.
+    #
+    #
+    # == Subclasses
+    #
+    # Each subclass should only take keyword arguments on initialization so that the boxes can be
+    # instantiated from the common convenience method HexaPDF::Document::Layout#box. To use this
+    # facility subclasses need to be registered with the configuration option 'layout.boxes.map'.
+    #
+    # The methods #fit, #split or #split_content, and #draw or #draw_content need to be customized
+    # according to the subclass's use case.
+    #
+    # #fit:: This method should return +true+ if fitting was successful. Additionally, the
+    #        @fit_successful instance variable needs to be set to the fit result as it is used in
+    #        #split.
+    #
+    # #split:: This method splits the content so that the available space is used as good as
+    #          possible. The default implementation should be fine for most use-cases, so only
+    #          #split_content needs to be implemented. The method #create_split_box should be used
+    #          for getting a basic cloned box.
+    #
+    # #draw:: This method draws the content and the default implementation already handles things
+    #         like drawing the border and background. Therefore it's best to implement #draw_content
+    #         which should just draw the content.
     class Box
 
       # Creates a new Box object, using the provided block as drawing block (see ::new).
       #
       # If +content_box+ is +true+, the width and height are taken to mean the content width and
-      # height and the style's padding and border are removed from them appropriately.
+      # height and the style's padding and border are added to them appropriately.
       #
       # The +style+ argument defines the Style object (see Style::create for details) for the box.
       # Any additional keyword arguments have to be style properties and are applied to the style
@@ -102,6 +127,18 @@ module HexaPDF
         @height = @initial_height = height
         @style = Style.create(style)
         @draw_block = block
+        @fit_successful = false
+        @split_box = false
+      end
+
+      # Returns +true+ if this is a split box, i.e. the rest of another box after it was split.
+      def split_box?
+        @split_box
+      end
+
+      # Returns +false+ since a basic box doesn't support the 'position' style property value :flow.
+      def supports_position_flow?
+        false
       end
 
       # The width of the content box, i.e. without padding and/or borders.
@@ -123,16 +160,16 @@ module HexaPDF
       def fit(available_width, available_height, _frame)
         @width = (@initial_width > 0 ? @initial_width : available_width)
         @height = (@initial_height > 0 ? @initial_height : available_height)
-        @width <= available_width && @height <= available_height
+        @fit_successful = (@width <= available_width && @height <= available_height)
       end
 
       # Tries to split the box into two, the first of which needs to fit into the available space,
       # and returns the parts as array.
       #
-      # In many cases the first box in the list will be this box, meaning that even when #fit fails,
-      # a part of the box may still fit. Note that #fit may not be called if the first box is this
-      # box since it is assumed that it is already fitted. If not even a part of this box fits into
-      # the available space, +nil+ should be returned as the first array element.
+      # If the first item in the result array is not +nil+, it needs to be this box and it means
+      # that even when #fit fails, a part of the box may still fit. Note that #fit should not be
+      # called before #draw on the first box since it is already fitted. If not even a part of this
+      # box fits into the available space, +nil+ should be returned as the first array element.
       #
       # Possible return values:
       #
@@ -140,15 +177,24 @@ module HexaPDF
       # [nil, self]:: The box can't be split or no part of the box fits into the available space.
       # [self, new_box]:: A part of the box fits and a new box is returned for the rest.
       #
-      # This default implementation provides no splitting functionality.
-      def split(_available_width, _available_height, _frame)
-        [nil, self]
+      # This default implementation provides the basic functionality based on the #fit result that
+      # should be sufficient for most subclasses; only #split_content needs to be implemented if
+      # necessary.
+      def split(available_width, available_height, frame)
+        if @fit_successful
+          [self, nil]
+        elsif (style.position != :flow && (@width > available_width || @height > available_height)) ||
+            content_height == 0 || content_width == 0
+          [nil, self]
+        else
+          split_content(available_width, available_height, frame)
+        end
       end
 
       # Draws the content of the box onto the canvas at the position (x, y).
       #
       # The coordinate system is translated so that the origin is at the bottom left corner of the
-      # **content box** during the drawing operations.
+      # **content box** during the drawing operations when +@draw_block+ is used.
       #
       # The block specified when creating the box is invoked with the canvas and the box as
       # arguments. Subclasses can specify an on-demand drawing method by setting the +@draw_block+
@@ -165,11 +211,7 @@ module HexaPDF
         style.underlays.draw(canvas, x, y, self) if style.underlays?
         style.border.draw(canvas, x, y, width, height) if style.border?
 
-        cx = x
-        cy = y
-        (cx += style.padding.left; cy += style.padding.bottom) if style.padding?
-        (cx += style.border.width.left; cy += style.border.width.bottom) if style.border?
-        draw_content(canvas, cx, cy)
+        draw_content(canvas, x + reserved_width_left, y + reserved_height_bottom)
 
         style.overlays.draw(canvas, x, y, self) if style.overlays?
       end
@@ -187,17 +229,47 @@ module HexaPDF
 
       # Returns the width that is reserved by the padding and border style properties.
       def reserved_width
-        result = 0
-        result += style.padding.left + style.padding.right if style.padding?
-        result += style.border.width.left + style.border.width.right if style.border?
-        result
+        reserved_width_left + reserved_width_right
       end
 
       # Returns the height that is reserved by the padding and border style properties.
       def reserved_height
+        reserved_height_top + reserved_height_bottom
+      end
+
+      # Returns the width that is reserved by the padding and the border style properties on the
+      # left side of the box.
+      def reserved_width_left
         result = 0
-        result += style.padding.top + style.padding.bottom if style.padding?
-        result += style.border.width.top + style.border.width.bottom if style.border?
+        result += style.padding.left if style.padding?
+        result += style.border.width.left if style.border?
+        result
+      end
+
+      # Returns the width that is reserved by the padding and the border style properties on the
+      # right side of the box.
+      def reserved_width_right
+        result = 0
+        result += style.padding.right if style.padding?
+        result += style.border.width.right if style.border?
+        result
+      end
+
+      # Returns the height that is reserved by the padding and the border style properties on the
+      # top side of the box.
+      def reserved_height_top
+        result = 0
+        result += style.padding.top if style.padding?
+        result += style.border.width.top if style.border?
+        result
+      end
+
+      # Returns the height that is reserved by the padding and the border style properties on the
+      # bottom side of the box.
+      def reserved_height_bottom
+        result = 0
+        result += style.padding.bottom if style.padding?
+        result += style.border.width.bottom if style.border?
         result
       end
 
@@ -209,6 +281,33 @@ module HexaPDF
         end
       end
 
+      # Splits the content of the box.
+      #
+      # This is just a stub implementation, returning [nil, self] since we can't know how to split
+      # the content when it didn't fit.
+      #
+      # Subclasses that support splitting content need to provide an appropriate implementation and
+      # use #create_split_box to create a cloned box to supply as the second argument.
+      def split_content(_available_width, _available_height, _frame)
+        [nil, self]
+      end
+
+      # Creates a new box based on this one and resets the data back to their original values.
+      #
+      # The variable +@split_box+ is set to +split_box_value+ (defaults to +true+) to make the new
+      # box aware that it is a split box. If needed, subclasses can set the variable to other truthy
+      # values to convey more meaning.
+      #
+      # This method should be used by subclasses to create their split box.
+      def create_split_box(split_box_value: true)
+        box = clone
+        box.instance_variable_set(:@width, @initial_width)
+        box.instance_variable_set(:@height, @initial_height)
+        box.instance_variable_set(:@fit_successful, nil)
+        box.instance_variable_set(:@split_box, split_box_value)
+        box
+      end
+
     end
 
   end

data/lib/hexapdf/layout/box_fitter.rb

@@ -0,0 +1,136 @@
+# -*- 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-2022 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.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+module HexaPDF
+  module Layout
+
+    # A BoxFitter instance contains an array of Frame objects and allows placing boxes one after the
+    # other in them. Such functionality is useful, for example, for boxes that provide multiple
+    # frames for content.
+    #
+    # == Usage
+    #
+    # * First one needs to add the frame objects via #<< or provide them on initialization.
+    #
+    # * Then use the #fit method to fit boxes one after the other. No drawing is done.
+    #
+    # * Once all boxes have been fitted, the #fit_results, #remaining_boxes and #fit_successful?
+    #   methods can be used to get the result:
+    #
+    #   - If there are no remaining boxes, all boxes were successfully fitted into the frames.
+    #   - If there are remaining boxes but no fit results, the first box could not be fitted.
+    #   - If there are remaining boxes and fit results, some boxes were able to fit.
+    class BoxFitter
+
+      # The array of frames inside of which the boxes should be laid out.
+      #
+      # Use #<< to add additional frames.
+      attr_reader :frames
+
+      # The Frame::FitResult objects for the successfully fitted objects in the order the boxes were
+      # fitted.
+      attr_reader :fit_results
+
+      # The boxes that could not be fitted into the frames.
+      attr_reader :remaining_boxes
+
+      # Creates a new BoxFitter object for the given +frames+.
+      def initialize(frames = [])
+        @frames = []
+        @content_heights = []
+        @initial_frame_y = []
+        @frame_index = 0
+        @fit_results = []
+        @remaining_boxes = []
+
+        frames.each {|frame| self << frame }
+      end
+
+      # Add the given frame to the list of frames.
+      def <<(frame)
+        @frames << frame
+        @initial_frame_y << frame.y
+        @content_heights << 0
+      end
+
+      # Fits the given box at the current location.
+      def fit(box)
+        unless @remaining_boxes.empty?
+          @remaining_boxes << box
+          return
+        end
+
+        while (current_frame = @frames[@frame_index])
+          result = current_frame.fit(box)
+          if result.success?
+            current_frame.remove_area(result.mask)
+            @content_heights[@frame_index] = [@content_heights[@frame_index],
+                                              @initial_frame_y[@frame_index] - result.mask[0].y].max
+            @fit_results << result
+            box = nil
+            break
+          elsif current_frame.full?
+            @frame_index += 1
+          else
+            draw_box, box = current_frame.split(result)
+            if draw_box
+              current_frame.remove_area(result.mask)
+              @content_heights[@frame_index] = [@content_heights[@frame_index],
+                                                @initial_frame_y[@frame_index] - result.mask[0].y].max
+              @fit_results << result
+            elsif !current_frame.find_next_region
+              @frame_index += 1
+            end
+          end
+        end
+
+        @remaining_boxes << box if box
+      end
+
+      # Returns an array with the heights of the content of each frame.
+      def content_heights
+        @content_heights
+      end
+
+      # Returns +true+ if all boxes were successfully fitted.
+      def fit_successful?
+        @remaining_boxes.empty?
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/layout/column_box.rb

@@ -0,0 +1,247 @@
+# -*- 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-2022 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.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# 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 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. They need to be finalized before #fit is called.
+      attr_reader :children
+
+      # 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 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 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.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)
+        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
+                   (@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
+          @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)
+            end
+            column_frame = Frame.new(column_left, column_bottom, column_width, height, shape: shape)
+            @box_fitter << column_frame
+          end
+
+          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
+
+        @width = columns[-1].sum + reserved_width
+        @height = @box_fitter.content_heights.max + reserved_height
+
+        @box_fitter.fit_successful?
+      end
+
+      private
+
+      # 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
+      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)
+        @box_fitter.fit_results.each {|result| result.draw(canvas) }
+      end
+
+    end
+
+  end
+end