hexapdf 0.38.0 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6df8bc8bdf189f60287c3dc0a0eccb1e1bca2a8b4310c1d5c2bb5d6661bae11
-  data.tar.gz: a28fc9d3319f596774bda74476fbc77fe40ba8e29a2dcd1e588c18f0928e8538
+  metadata.gz: d0a43d232528df9bfc4a2c9baddd9cd1ddbd33fe7cce9d146b4e25760f25429b
+  data.tar.gz: 37cb10752d22bbc89fd18a779152ef7b5e02e6237318006a4b0e0a420d2890e2
 SHA512:
-  metadata.gz: 11a382eceaa702705fe15484314e8d8b21c26ce2bf50d082be5e4ae27749251562474bfe1f4d410e53008120b37b6f43b42b1f9ecaca0ce123a672a6868a0515
-  data.tar.gz: ef98043f0d6460bbfd4819ba34fd2fab4d9e7426b04d0005f1f65ae88d813ff92db6f9cb89cb3e88997c8b68dea7e7631ceb873f5091a6c1b8bd6aa72075ab32
+  metadata.gz: 79a27b101c502261e1bca7a25fa26fa434d38cec09a2ccb28a698a4364d8ed337ee63d82ce8cd4dd3097334ed54f0877565c25e20c2494c0ae7029156dc188ef
+  data.tar.gz: 69befc3a7066eb90a58ad4a65243939930f26ecc461e0f6f7c9bf0894ddfa58bf1a02567563caa453b0c6e745421de75e7dd433926d2a56b96aa4d71557059f5

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.39.0 - 2024-03-18
+
+### Added
+
+* Hierarchical box information to the document layout engine
+* Style property 'text_overflow' for controlling how overflowing text should be
+  handled
+
+### Changed
+
+* [HexaPDF::Layout::Frame::FitResult#draw] to provide better optional content
+  group names
+
+### Fixed
+
+* [HexaPDF::Layout::TextBox] to correctly respect a set height
+
+
 ## 0.38.0 - 2024-03-10
 
 ### Added

data/examples/030-pdfa.rb

@@ -1,4 +1,4 @@
-# # PDF/A Compliance
+# # PDF/A Conformance
 #
 # This example shows how to create a PDF file that is PDF/A compliant.
 #

data/lib/hexapdf/layout/column_box.rb

@@ -179,8 +179,8 @@ module HexaPDF
                                      [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, context: frame.context)
+            column_frame = frame.child_frame(column_left, column_bottom, column_width, height,
+                                             shape: shape, box: self)
             @box_fitter << column_frame
           end
 

data/lib/hexapdf/layout/container_box.rb

@@ -131,8 +131,9 @@ module HexaPDF
 
       # Fits the children into the container.
       def fit_content(_available_width, _available_height, frame)
-        my_frame = Frame.new(frame.x + reserved_width_left, frame.y - @height + reserved_height_bottom,
-                             content_width, content_height, context: frame.context)
+        my_frame = frame.child_frame(frame.x + reserved_width_left,
+                                     frame.y - @height + reserved_height_bottom,
+                                     content_width, content_height, box: self)
         @box_fitter = BoxFitter.new([my_frame])
         children.each {|box| @box_fitter.fit(box) }
 

data/lib/hexapdf/layout/frame.rb

@@ -91,6 +91,9 @@ module HexaPDF
       # 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
 
@@ -110,8 +113,9 @@ module HexaPDF
         # drawing the box.
         attr_accessor :mask
 
-        # Initialize the result object for the given box.
-        def initialize(box)
+        # Initialize the result object for the given frame and box.
+        def initialize(frame, box)
+          @frame = frame
           @box = box
           @available_width = 0
           @available_height = 0
@@ -138,7 +142,10 @@ module HexaPDF
         def draw(canvas, dx: 0, dy: 0)
           doc = canvas.context.document
           if doc.config['debug']
-            name = "#{box.class} (#{x.to_i},#{y.to_i}-#{box.width.to_i}x#{box.height.to_i})"
+            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
@@ -147,7 +154,8 @@ module HexaPDF
                   draw(:geom2d, object: mask, path_only: true).fill_stroke
               end
             end
-            doc.optional_content.default_configuration.add_ocg_to_ui(ocg, path: 'Debug')
+            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
@@ -195,14 +203,21 @@ module HexaPDF
       # should be used.
       attr_reader :context
 
+      # 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
+      # that are fitted into this frame have to be child boxes of the immediate parent box.
+      attr_reader :parent_boxes
+
       # Creates a new Frame object for the given rectangular area.
-      def initialize(left, bottom, width, height, shape: nil, context: nil)
+      def initialize(left, bottom, width, height, shape: nil, context: nil, parent_boxes: [])
         @left = left
         @bottom = bottom
         @width = width
         @height = height
         @shape = shape || create_rectangle(left, bottom, left + width, bottom + height)
         @context = context
+        @parent_boxes = parent_boxes.freeze
 
         @x = left
         @y = bottom + height
@@ -213,6 +228,25 @@ module HexaPDF
         @region_selection = :max_height
       end
 
+      # Creates a new Frame object based on this one.
+      #
+      # If the +init_args+ arguments are provided, a new Frame is created using the constructor. The
+      # optional +shape+ argument is then also passed to the constructor.
+      #
+      # Otherwise, this frame is duplicated. This kind of invocation is only useful if the +box+
+      # argument is provided (because otherwise there would be no difference to this frame).
+      #
+      # The +box+ argument can be used to add the appropriate parent box to the list of
+      # #parent_boxes for the newly created frame.
+      def child_frame(*init_args, shape: nil, box: nil)
+        parent_boxes = (box ? @parent_boxes.dup << box : @parent_boxes)
+        if init_args.empty?
+          dup.tap {|result| result.instance_variable_set(:@parent_boxes, parent_boxes) }
+        else
+          self.class.new(*init_args, shape: shape, context: @context, parent_boxes: parent_boxes)
+        end
+      end
+
       # Returns the HexaPDF::Document instance (through #context) that is associated with this Frame
       # object or +nil+ if no context object has been set.
       def document
@@ -227,7 +261,7 @@ module HexaPDF
       #
       # Use the FitResult#success? method to determine whether fitting was successful.
       def fit(box)
-        fit_result = FitResult.new(box)
+        fit_result = FitResult.new(self, box)
         return fit_result if full?
 
         margin = box.style.margin if box.style.margin?

data/lib/hexapdf/layout/inline_box.rb

@@ -126,10 +126,17 @@ module HexaPDF
         height
       end
 
-      # Fits the wrapped box, using the given context (see Frame#context).
-      def fit_wrapped_box(context)
-        @fit_result = Frame.new(0, 0, box.width, box.height == 0 ? 100_000 : box.height,
-                                context: context).fit(box)
+      # Fits the wrapped box.
+      #
+      # If the +frame+ argument is +nil+, a custom frame is created. Otherwise the given +frame+ is
+      # used for the fitting operation.
+      def fit_wrapped_box(frame)
+        frame = if frame
+                  frame.child_frame(0, 0, box.width, box.height == 0 ? 100_000 : box.height)
+                else
+                  Frame.new(0, 0, box.width, box.height == 0 ? 100_000 : box.height)
+                end
+        @fit_result = frame.fit(box)
         if !@fit_result.success?
           raise HexaPDF::Error, "Box for inline use could not be fit"
         elsif box.height > 99_000

data/lib/hexapdf/layout/list_box.rb

@@ -227,12 +227,12 @@ module HexaPDF
             remove_indent_from_frame_shape(shape) unless shape.polygons.empty?
           end
 
-          item_frame = Frame.new(item_frame_left, top - height, item_frame_width, height,
-                                 shape: shape, context: frame.context)
+          item_frame = frame.child_frame(item_frame_left, top - height, item_frame_width, height,
+                                         shape: shape, box: self)
 
           if index != 0 || !split_box? || @split_box == :show_first_marker
             box = item_marker_box(frame.document, index)
-            marker_frame = Frame.new(0, 0, content_indentation, height, context: frame.context)
+            marker_frame = frame.child_frame(0, 0, content_indentation, height, box: self)
             break unless box.fit(content_indentation, height, marker_frame)
             item_result.marker = box
             item_result.marker_pos_x = item_frame.x - content_indentation

data/lib/hexapdf/layout/style.rb

@@ -1084,6 +1084,25 @@ module HexaPDF
       #                            'Centered',
       #                            {text: "\u{00a0}", fill_horizontal: 1, overlays: overlays}])
 
+      ##
+      # :method: text_overflow
+      # :call-seq:
+      #   text_overflow(mode = nil)
+      #
+      # Specifies how text overflowing a box with a given initial height should be handled:
+      #
+      # Possible values:
+      #
+      # :error::    An error is raised (default).
+      # :truncate:: Truncates the overflowing text.
+      #
+      # Examples:
+      #
+      #   #>pdf-composer100
+      #   composer.text("This is some longer text that does appear in two lines.")
+      #   composer.text("This is some longer text that does not appear in two lines.",
+      #                 height: 15, text_overflow: :truncate)
+
       ##
       # :method: background_color
       # :call-seq:
@@ -1435,6 +1454,7 @@ module HexaPDF
           extra_args: ", extra_arg = nil"}],
         [:last_line_gap, false, {valid_values: [true, false]}],
         [:fill_horizontal, nil],
+        [:text_overflow, :error],
         [:background_color, nil],
         [:background_alpha, 1],
         [:padding, "Quad.new(0)", {setter: "Quad.new(value)"}],

data/lib/hexapdf/layout/table_box.rb

@@ -218,7 +218,7 @@ module HexaPDF
           height = available_height - reserved_height
           return false if width <= 0 || height <= 0
 
-          frame = Frame.new(0, 0, width, height, context: frame.context)
+          frame = frame.child_frame(0, 0, width, height, box: self)
           case children
           when Box
             fit_result = frame.fit(children)
@@ -607,6 +607,7 @@ module HexaPDF
         columns = calculate_column_widths(width)
         return false if columns.empty?
 
+        frame = frame.child_frame(box: self)
         @special_cells_fit_not_successful = false
         [@header_cells, @footer_cells].each do |special_cells|
           next unless special_cells

data/lib/hexapdf/layout/text_box.rb

@@ -79,6 +79,7 @@ module HexaPDF
         return false if (@initial_width > 0 && @initial_width > available_width) ||
           (@initial_height > 0 && @initial_height > available_height)
 
+        frame = frame.child_frame(box: self)
         @width = @height = 0
         @result = if style.position == :flow
                     @tl.fit(@items, frame.width_specification, frame.shape.bbox.height,
@@ -104,7 +105,8 @@ module HexaPDF
           @height += style.line_spacing.gap(@result.lines.last, @result.lines.last)
         end
 
-        @result.status == :success
+        @result.status == :success ||
+          (@result.status == :height && @initial_height > 0 && style.text_overflow == :truncate)
       end
 
       # Splits the text box into two boxes if necessary and possible.
@@ -132,7 +134,14 @@ module HexaPDF
 
       # Draws the text into the box.
       def draw_content(canvas, x, y)
-        return unless @result && !@result.lines.empty?
+        return unless @result
+
+        if @result.status == :height && @initial_height > 0 && style.text_overflow == :error
+          raise HexaPDF::Error, "Text doesn't fit into box with limited height and " \
+            "style property text_overflow is set to :error"
+        end
+
+        return if @result.lines.empty?
         @result.draw(canvas, x, y + content_height)
       end
 

data/lib/hexapdf/layout/text_layouter.rb

@@ -307,10 +307,15 @@ module HexaPDF
       class SimpleLineWrapping
 
         # :call-seq:
-        #   SimpleLineWrapping.call(items, width_block) {|line, item| block }   -> rest
+        #   SimpleLineWrapping.call(items, width_block, frame = nil) {|line, item| block }   -> rest
         #
         # Arranges the items into lines.
         #
+        # The optional +frame+ argument needs to be a Frame object that is used when fitting inline
+        # boxes. If not provided, a custom Frame object is used. However, if the items contain
+        # inline boxes that need to access a frame's context object, it is mandatory to provide an
+        # appropriate Frame object.
+        #
         # The +width_block+ argument has to be a callable object that returns the width of the line:
         #
         # * If the line width doesn't depend on the height or the vertical position of the line
@@ -340,7 +345,7 @@ module HexaPDF
         # current start of the line index should be stored for later use.
         #
         # After the algorithm is finished, it returns the unused items.
-        def self.call(items, width_block, frame, &block)
+        def self.call(items, width_block, frame = nil, &block)
           obj = new(items, width_block, frame)
           if width_block.arity == 1
             obj.variable_width_wrapping(&block)
@@ -507,7 +512,7 @@ module HexaPDF
         #
         # Returns +true+ if the item could be added and +false+ otherwise.
         def add_box_item(item)
-          item.fit_wrapped_box(@frame&.context) if item.kind_of?(InlineBox)
+          item.fit_wrapped_box(@frame) if item.kind_of?(InlineBox)
           return false unless @width + item.width <= @available_width
           @line_items.concat(@glue_items).push(item)
           @width += item.width
@@ -718,6 +723,10 @@ module HexaPDF
       #     Specifies whether style.text_indent should be applied to the first line. This should be
       #     set to +false+ if the items start with a continuation of a paragraph instead of starting
       #     a new paragraph (e.g. after a page break).
+      #
+      # +frame+::
+      #     If used with the document layout functionality, this should be the frame into which the
+      #     text is laid out.
       def fit(items, width, height, apply_first_text_indent: true, frame: nil)
         unless items.empty? || items[0].respond_to?(:type)
           items = style.text_segmentation_algorithm.call(items)

data/lib/hexapdf/version.rb

@@ -37,6 +37,6 @@
 module HexaPDF
 
   # The version of HexaPDF.
-  VERSION = '0.38.0'
+  VERSION = '0.39.0'
 
 end

data/test/hexapdf/layout/test_frame.rb

@@ -10,7 +10,8 @@ describe HexaPDF::Layout::Frame::FitResult do
     doc = HexaPDF::Document.new(config: {'debug' => true})
     canvas = doc.pages.add.canvas
     box = HexaPDF::Layout::Box.create(width: 20, height: 20) {}
-    result = HexaPDF::Layout::Frame::FitResult.new(box)
+    frame = HexaPDF::Layout::Frame.new(5, 10, 100, 150)
+    result = HexaPDF::Layout::Frame::FitResult.new(frame, box)
     result.mask = Geom2D::Rectangle(0, 0, 20, 20)
     result.x = result.y = 0
     result.draw(canvas, dx: 10, dy: 15)
@@ -30,7 +31,8 @@ describe HexaPDF::Layout::Frame::FitResult do
       Q
     CONTENTS
     ocg = doc.optional_content.ocgs.first
-    assert_equal([['Debug', ocg]], doc.optional_content.default_configuration[:Order])
+    assert_equal([['Debug', ['Page 1', ocg]]], doc.optional_content.default_configuration[:Order])
+    assert_match(/10,15-20x20/, ocg.name)
   end
 end
 
@@ -61,6 +63,11 @@ describe HexaPDF::Layout::Frame do
     assert_equal(150, @frame.available_height)
   end
 
+  it "allows access to the frame's parent boxes" do
+    frame = HexaPDF::Layout::Frame.new(5, 10, 100, 150, parent_boxes: [:a])
+    assert_equal([:a], frame.parent_boxes)
+  end
+
   it "allows setting the shape of the frame on initialization" do
     shape = Geom2D::Polygon([50, 10], [55, 100], [105, 100], [105, 10])
     frame = HexaPDF::Layout::Frame.new(5, 10, 100, 150, shape: shape)
@@ -71,6 +78,27 @@ describe HexaPDF::Layout::Frame do
     assert_equal(90, frame.available_height)
   end
 
+  describe "child_frame" do
+    before do
+      @frame = HexaPDF::Layout::Frame.new(10, 10, 100, 100, parent_boxes: [:a])
+    end
+
+    it "duplicates the frame setting the parent boxes appropriately" do
+      assert_same(@frame.parent_boxes, @frame.child_frame.parent_boxes)
+      frame = @frame.child_frame(box: :b)
+      assert_equal([:a, :b], frame.parent_boxes)
+    end
+
+    it "creates a new frame, optionally adding a parent box" do
+      shape = Geom2D::Rectangle(0, 0, 20, 20)
+      frame = @frame.child_frame(0, 0, 20, 20, shape: shape)
+      assert_same(@frame.parent_boxes, frame.parent_boxes)
+      assert_equal(shape, frame.shape)
+      frame = @frame.child_frame(0, 0, 20, 20, box: :b)
+      assert_equal([:a, :b], frame.parent_boxes)
+    end
+  end
+
   it "returns an appropriate width specification object" do
     ws = @frame.width_specification(10)
     assert_kind_of(HexaPDF::Layout::WidthFromPolygon, ws)
@@ -97,6 +125,7 @@ describe HexaPDF::Layout::Frame do
       @canvas.expect(:translate, nil, pos)
       fit_result = @frame.fit(@box)
       refute_nil(fit_result)
+      assert_same(@frame, fit_result.frame)
       @frame.draw(@canvas, fit_result)
       assert_equal(mask, fit_result.mask.bbox.to_a)
       if @frame.shape.respond_to?(:polygons)

data/test/hexapdf/layout/test_inline_box.rb

@@ -31,7 +31,14 @@ describe HexaPDF::Layout::InlineBox do
   end
 
   describe "fit_wrapped_box" do
-    it "automatically fits the provided box into a frame" do
+    it "automatically fits the provided box into the given frame" do
+      ibox = inline_box(HexaPDF::Document.new.layout.text("test is going good", width: 20))
+      ibox.fit_wrapped_box(HexaPDF::Layout::Frame.new(0, 0, 50, 50))
+      assert_equal(20, ibox.width)
+      assert_equal(45, ibox.height)
+    end
+
+    it "automatically fits the provided box into a custom frame" do
       ibox = inline_box(HexaPDF::Document.new.layout.text("test is going good", width: 20))
       ibox.fit_wrapped_box(nil)
       assert_equal(20, ibox.width)

data/test/hexapdf/layout/test_style.rb

@@ -783,6 +783,7 @@ describe HexaPDF::Layout::Style do
     refute(@style.superscript)
     refute(@style.last_line_gap)
     refute(@style.fill_horizontal)
+    assert_equal(:error, @style.text_overflow)
     assert_kind_of(HexaPDF::Layout::Style::Layers, @style.underlays)
     assert_kind_of(HexaPDF::Layout::Style::Layers, @style.overlays)
     assert_equal(:default, @style.position)

data/test/hexapdf/layout/test_text_box.rb

@@ -50,8 +50,7 @@ describe HexaPDF::Layout::TextBox do
     end
 
     it "fits into the frame's outline" do
-      inline_box = HexaPDF::Layout::InlineBox.create(width: 10, height: 10) {}
-      box = create_box([inline_box] * 20, style: {position: :flow})
+      box = create_box([@inline_box] * 20, style: {position: :flow})
       assert(box.fit(100, 100, @frame))
       assert_equal(100, box.width)
       assert_equal(20, box.height)
@@ -80,6 +79,16 @@ describe HexaPDF::Layout::TextBox do
       end
     end
 
+    it "respects the style property text_overflow when fitting too much text" do
+      box = create_box([@inline_box] * 20, height: 15)
+      refute(box.fit(100, 100, @frame))
+      box.style.text_overflow = :truncate
+      assert(box.fit(100, 100, @frame))
+
+      box = create_box([@inline_box] * 20, style: {text_overflow: :truncate})
+      refute(box.fit(100, 15, @frame))
+    end
+
     it "can't fit the text box if the set width is bigger than the available width" do
       box = create_box([@inline_box], width: 101)
       refute(box.fit(100, 100, @frame))
@@ -154,13 +163,16 @@ describe HexaPDF::Layout::TextBox do
   end
 
   describe "draw" do
+    before do
+      @canvas = HexaPDF::Document.new.pages.add.canvas
+    end
+
     it "draws the layed out inline items onto the canvas" do
       inline_box = HexaPDF::Layout::InlineBox.create(width: 10, height: 10,
                                                      border: {width: 1})
       box = create_box([inline_box], width: 100, height: 30, style: {padding: [10, 5]})
-      box.fit(100, 100, nil)
+      box.fit(100, 100, @frame)
 
-      @canvas = HexaPDF::Document.new.pages.add.canvas
       box.draw(@canvas, 0, 0)
       assert_operators(@canvas.contents, [[:save_graphics_state],
                                           [:restore_graphics_state],
@@ -179,11 +191,16 @@ describe HexaPDF::Layout::TextBox do
     end
 
     it "draws nothing onto the canvas if the box is empty" do
-      @canvas = HexaPDF::Document.new.pages.add.canvas
       box = create_box([])
       box.draw(@canvas, 5, 5)
       assert_operators(@canvas.contents, [])
     end
+
+    it "raises an error if there is too much content for a set height with text_overlow=:error" do
+      box = create_box([@inline_box] * 20, height: 15)
+      box.fit(100, 100, @frame)
+      assert_raises(HexaPDF::Error) { box.draw(@canvas, 0, 0) }
+    end
   end
 
   it "is empty if there is a result without any text lines" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hexapdf
 version: !ruby/object:Gem::Version
-  version: 0.38.0
+  version: 0.39.0
 platform: ruby
 authors:
 - Thomas Leitner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-10 00:00:00.000000000 Z
+date: 2024-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cmdparse