hexapdf 0.21.1 → 0.24.0

data/lib/hexapdf/layout/frame.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
@@ -75,53 +75,72 @@ module HexaPDF
     # fitting, splitting or drawing a box. Note that the margin is ignored if a box's side coincides
     # with the frame's original boundary.
     #
-    # == Frame Shape and Contour Line
+    # == Frame Shape
     #
-    # A frame's shape is used to determine the available space for laying out boxes and its contour
-    # line is used whenever text should be flown around objects. They are normally the same but can
-    # differ if a box with an arbitrary contour line is drawn onto the frame.
+    # A frame's shape is used to determine the available space for laying out boxes.
     #
     # Initially, a frame has a rectangular shape. However, once boxes are added and the frame's
     # available area gets reduced, a frame may have a polygon set consisting of arbitrary
     # rectilinear polygons as shape.
     #
-    # In contrast to the frame's shape its contour line may be a completely arbitrary polygon set.
+    # It is also possible to provide a different initial shape on initialization.
     class Frame
 
       include Geom2D::Utils
 
-      # Internal class for storing data of a fitted box.
-      class FitData
+      # Stores the result of fitting a box in a Frame.
+      class FitResult
 
         # The box that was fitted into the frame.
         attr_accessor :box
 
-        # The available width for this particular 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 for this particular box.
+        # The available height in the frame for this particular box.
         attr_accessor :available_height
 
-        # The left margin to use instead of +box.style.margin.left+.
-        attr_accessor :margin_left
+        # The rectangle (a Geom2D::Polygon object) that will be removed from the frame when drawing
+        # the box.
+        attr_accessor :mask
 
-        # The right margin to use instead of +box.style.margin.right+.
-        attr_accessor :margin_right
+        # Initialize the result object for the given box.
+        def initialize(box)
+          @box = box
+          @available_width = 0
+          @available_height = 0
+          @success = false
+        end
 
-        # The top margin to use instead of +box.style.margin.top+.
-        attr_accessor :margin_top
+        # Marks the fitting status as success.
+        def success!
+          @success = true
+        end
 
-        # Initialize the object by calling #reset.
-        def initialize
-          reset
+        # Returns +true+ if fitting was successful.
+        def success?
+          @success
         end
 
-        # Resets the object.
-        def reset(box = nil, available_width = 0, available_height = 0)
-          @box = box
-          @available_width = available_width
-          @available_height = available_height
-          @margin_left = @margin_right = @margin_top = 0
+        # Draws the #box onto the canvas at (#x, #y).
+        #
+        # The configuration option "debug" can be used to add visual debug output with respect to
+        # box placement.
+        def draw(canvas)
+          if canvas.context.document.config['debug']
+            canvas.save_graphics_state 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
+          box.draw(canvas, x, y)
         end
 
       end
@@ -163,131 +182,129 @@ module HexaPDF
       attr_reader :available_height
 
       # Creates a new Frame object for the given rectangular area.
-      def initialize(left, bottom, width, height, contour_line: nil)
+      def initialize(left, bottom, width, height, shape: nil)
         @left = left
         @bottom = bottom
         @width = width
         @height = height
-        @contour_line = contour_line
-        @shape = Geom2D::PolygonSet.new(
+        @shape = shape || Geom2D::PolygonSet.new(
           [create_rectangle(left, bottom, left + width, bottom + height)]
         )
         @x = left
         @y = bottom + height
         @available_width = width
         @available_height = height
+
+        find_max_width_region if shape
         @region_selection = :max_height
-        @fit_data = FitData.new
       end
 
-      # Fits the given box into the current region of available space.
+      # Fits the given box into the current region of available space and returns a FitResult
+      # object.
+      #
+      # Use the FitResult#success? method to determine whether fitting was successful.
       def fit(box)
-        aw = available_width
-        ah = available_height
-        @fit_data.reset(box, aw, ah)
+        fit_result = FitResult.new(box)
+        return fit_result if full?
+
+        position = if box.style.position != :flow || box.supports_position_flow?
+                     box.style.position
+                   else
+                     :default
+                   end
 
-        if full?
-          false
-        elsif box.style.position == :absolute
+        if position == :absolute
           x, y = box.style.position_hint
-          box.fit(width - x, height - y, self)
-          true
-        else
-          if box.style.margin?
-            margin = box.style.margin
-            ah -= margin.bottom unless float_equal(@y - ah, @bottom)
-            ah -= @fit_data.margin_top = margin.top unless float_equal(@y, @bottom + @height)
-            aw -= @fit_data.margin_right = margin.right unless float_equal(@x + aw, @left + @width)
-            aw -= @fit_data.margin_left = margin.left unless float_equal(@x, @left)
-            @fit_data.available_width = aw
-            @fit_data.available_height = ah
-          end
 
+          aw = width - x
+          ah = height - y
           box.fit(aw, ah, self)
-        end
-      end
-
-      # Tries to split the (fitted) box into two parts, where the first part needs to fit into the
-      # available space, and returns both parts.
-      #
-      # If the given box is not the last fitted box, #fit is called before splitting the box.
-      #
-      # See Box#split for further details.
-      def split(box)
-        fit(box) unless box == @fit_data.box
-        boxes = box.split(@fit_data.available_width, @fit_data.available_height, self)
-        @fit_data.reset unless boxes[0] == @fit_data.box
-        boxes
-      end
+          fit_result.success!
 
-      # Draws the given (fitted) box onto the canvas at the frame's current position. Returns +true+
-      # if drawing was possible, +false+ otherwise.
-      #
-      # If the given box is not the last fitted box, #fit is called before drawing the box.
-      #
-      # After a box is successfully drawn, the frame's shape and contour line are adjusted to remove
-      # the occupied area.
-      def draw(canvas, box)
-        unless box == @fit_data.box
-          fit(box) || return
-        end
-
-        width = box.width
-        height = box.height
-        margin = box.style.margin if box.style.margin?
-
-        if height == 0
-          @fit_data.reset
-          return true
-        end
-
-        case box.style.position
-        when :absolute
-          x, y = box.style.position_hint
           x += left
           y += bottom
           rectangle = if box.style.margin?
+                        margin = box.style.margin
                         create_rectangle(x - margin.left, y - margin.bottom,
-                                         x + width + margin.right, y + height + margin.top)
+                                         x + box.width + margin.right, y + box.height + margin.top)
                       else
-                        create_rectangle(x, y, x + width, y + height)
+                        create_rectangle(x, y, x + box.width, y + box.height)
                       end
-        when :float
-          x = @x + @fit_data.margin_left
-          x += @fit_data.available_width - width if box.style.position_hint == :right
-          y = @y - height - @fit_data.margin_top
-          # We use the real margins from the box because they either have the desired effect or just
-          # extend the rectangle outside the frame.
-          rectangle = create_rectangle(x - (margin&.left || 0), y - (margin&.bottom || 0),
-                                       x + width + (margin&.right || 0), @y)
-        when :flow
-          x = 0
-          y = @y - height
-          rectangle = create_rectangle(left, y, left + self.width, @y)
         else
-          x = case box.style.position_hint
-              when :right
-                @x + @fit_data.margin_left + @fit_data.available_width - width
-              when :center
-                max_margin = [@fit_data.margin_left, @fit_data.margin_right].max
-                # If we have enough space left for equal margins, we center perfectly
-                if available_width - width >= 2 * max_margin
-                  @x + (available_width - width) / 2.0
-                else
-                  @x + @fit_data.margin_left + (@fit_data.available_width - width) / 2.0
+          aw = available_width
+          ah = available_height
+
+          margin_top = margin_right = margin_left = 0
+          if box.style.margin?
+            margin = box.style.margin
+            aw -= margin_right = margin.right unless float_equal(@x + aw, @left + @width)
+            aw -= margin_left = margin.left unless float_equal(@x, @left)
+            ah -= margin.bottom unless float_equal(@y - ah, @bottom)
+            ah -= margin_top = margin.top unless float_equal(@y, @bottom + @height)
+          end
+
+          fit_result.success! if box.fit(aw, ah, self)
+
+          width = box.width
+          height = box.height
+
+          case position
+          when :flow
+            x = 0
+            y = @y - height
+            rectangle = create_rectangle(left, [bottom, y - (margin&.bottom || 0)].max,
+                                         left + self.width, @y)
+          else
+            x = case box.style.position_hint
+                when nil, :left
+                  @x + margin_left
+                when :right
+                  @x + margin_left + aw - width
+                when :center
+                  max_margin = [margin_left, margin_right].max
+                  # If we have enough space left for equal margins, we center perfectly
+                  if available_width - width >= 2 * max_margin
+                    @x + (available_width - width) / 2.0
+                  else
+                    @x + margin_left + (aw - width) / 2.0
+                  end
                 end
-              else
-                @x + @fit_data.margin_left
-              end
-          y = @y - height - @fit_data.margin_top
-          rectangle = create_rectangle(left, y - (margin&.bottom || 0), left + self.width, @y)
+            y = @y - height - margin_top
+            rectangle = if position == :float
+                          create_rectangle([left, x - (margin&.left || 0)].max,
+                                           [bottom, y - (margin&.bottom || 0)].max,
+                                           [left + self.width, x + width + (margin&.right || 0)].min,
+                                           @y)
+                        else
+                          create_rectangle(left, [bottom, y - (margin&.bottom || 0)].max,
+                                           left + self.width, @y)
+                        end
+          end
         end
 
-        box.draw(canvas, x, y)
-        remove_area(rectangle)
-        @fit_data.reset
+        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.
+      #
+      # See Box#split for further details.
+      def split(fit_result)
+        fit_result.box.split(fit_result.available_width, fit_result.available_height, self)
+      end
 
-        true
+      # Draws the box of the given 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
 
       # Finds the next region for placing boxes. Returns +false+ if no useful region was found.
@@ -316,18 +333,12 @@ module HexaPDF
           trim_shape
         end
 
-        @fit_data.reset
         available_width != 0
       end
 
-      # Removes the given *rectilinear* polygon from both the frame's shape and the frame's contour
-      # line.
+      # Removes the given *rectilinear* polygon from the frame's shape.
       def remove_area(polygon)
         @shape = Geom2D::Algorithms::PolygonOperation.run(@shape, polygon, :difference)
-        if @contour_line
-          @contour_line = Geom2D::Algorithms::PolygonOperation.run(@contour_line, polygon,
-                                                                   :difference)
-        end
         @region_selection = :max_width
         find_next_region
       end
@@ -337,25 +348,20 @@ module HexaPDF
         available_width == 0
       end
 
-      # The contour line of the frame, a Geom2D::PolygonSet consisting of arbitrary polygons.
-      def contour_line
-        @contour_line || @shape
-      end
-
-      # Returns a width specification for the frame's contour line that can be used, for example,
-      # with TextLayouter.
+      # Returns a width specification for the frame's shape that can be used, for example, with
+      # TextLayouter.
       #
       # 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
-      # contour line is the origin of the coordinate system for the width specification, with
-      # positive x-values to the right and positive y-values downwards.
+      # shape is the origin of the coordinate system for the width specification, with positive
+      # x-values to the right and positive y-values downwards.
       #
       # Depending on the complexity of the frame, the result may be any of the allowed width
       # specifications of TextLayouter#fit.
       def width_specification(offset = 0)
-        WidthFromPolygon.new(contour_line, offset)
+        WidthFromPolygon.new(shape, offset)
       end
 
       private
@@ -403,9 +409,18 @@ module HexaPDF
         # Just use the second top-most segment
         # TODO: not the optimal solution!
         index = segments.rindex {|s| s.start_point.y < @y }
-        y = segments[index].start_point.y
-        remove_area(Geom2D::Polygon([left, y], [left + width, y],
-                                    [left + width, @y], [left, @y]))
+        segment = segments[index]
+        y = segment.start_point.y
+        polygon = if segment.min.x == @x
+                    # Trim the rectangular part from the left to the segment's length
+                    Geom2D::Polygon([@x, @y], [@x, y],
+                                    [@x + segment.length, y], [@x + segment.length, @y])
+                  else
+                    # Trim the whole slice between the two top-most segments
+                    Geom2D::Polygon([left, y], [left + width, y],
+                                    [left + width, @y], [left, @y])
+                  end
+        remove_area(polygon)
       end
 
       # Finds and sets the top-left point for the next region. This is always the top-most,

data/lib/hexapdf/layout/image_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,13 +40,27 @@ module HexaPDF
 
     # An Image box object is used for displaying an image.
     #
+    # It can either be used directly or through the HexaPDF::Composer#image method.
+    #
     # 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.
+    #
+    #     #>pdf-composer100
+    #     composer.image(machu_picchu, width: 40)
+    #     composer.image(machu_picchu, height: 40)
+    #
     # * If both have been set, both are used as is.
+    #
+    #     #>pdf-composer100
+    #     composer.image(machu_picchu, width: 100, height: 30)
+    #
     # * If neither has been set, the image is scaled to fit the available space.
     #
+    #     #>pdf-composer100
+    #     composer.image(machu_picchu)
+    #
     # Also see: HexaPDF::Content::Canvas#image
     class ImageBox < Box
 
@@ -55,13 +69,14 @@ module HexaPDF
 
       # 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)
+      def initialize(image:, **kwargs)
         super(**kwargs)
         @image = image
       end
 
-      # Fits the image into the available space.
-      def fit(available_width, available_height, _)
+      # Fits the image into the available space, taking the initially set width and height into
+      # account (see the class description for details).
+      def fit(available_width, available_height, _frame)
         image_width = @image.width.to_f
         image_height = @image.height.to_f
         image_ratio = image_width / image_height

data/lib/hexapdf/layout/inline_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

data/lib/hexapdf/layout/line.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