hexapdf 0.37.2 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7633d38801df5768a809a8491de34a33ff90069c1ea55eed29a75d0ccd4e5c67
-  data.tar.gz: f74d51319f639d5e218e27cb264231e370943fa365b4b4c1ef9b0c47df123dfb
+  metadata.gz: d0a43d232528df9bfc4a2c9baddd9cd1ddbd33fe7cce9d146b4e25760f25429b
+  data.tar.gz: 37cb10752d22bbc89fd18a779152ef7b5e02e6237318006a4b0e0a420d2890e2
 SHA512:
-  metadata.gz: cfc63a537dacfece92e4df2116362b8a270b9f291e1350604368820a8e2e02ebc2e47b462391dcd74cf9a16ab498d9b3b72ab1a8ff063eab816ed65636405379
-  data.tar.gz: e90d2be37bc9150c9e040b06678fe98ea601c20dab39b75e689559418f043b63c0967784f0e5f0b0d11f1cce5ee10557d65a4e996099301bd27fb4962dcbe961
+  metadata.gz: 79a27b101c502261e1bca7a25fa26fa434d38cec09a2ccb28a698a4364d8ed337ee63d82ce8cd4dd3097334ed54f0877565c25e20c2494c0ae7029156dc188ef
+  data.tar.gz: 69befc3a7066eb90a58ad4a65243939930f26ecc461e0f6f7c9bf0894ddfa58bf1a02567563caa453b0c6e745421de75e7dd433926d2a56b96aa4d71557059f5

data/CHANGELOG.md

@@ -1,3 +1,44 @@
+## 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
+
+* [HexaPDF::Task::PDFA] for creating PDF/A conforming PDF files
+* [HexaPDF::Type::OutputIntent] for defining output intents
+* [HexaPDF::Document::Metadata#delete] for deleting metadata properties
+* PDF/A metadata properties definitions
+* Added a /Name entry to the default optional content configuration dictionary
+  (needed by PDF/A)
+
+### Changed
+
+* Default language for XMP metadata from English to 'x-default'
+* [HexaPDF::Layout::ListBox] to use the style's font for drawing markers and to
+  fall back to Times and ZapfDingbats if necessary
+* [HexaPDF::Document::Layout#table_box] to merge the `:cell` keys that define
+  the cell style instead of using the last one
+* [HexaPDF::Document::Layout] style retrieval to fall back to using the font of
+  the `:base` style and only if that doesn't exist to 'Times'
+* XMP metadata stream contents to satisfy more PDF/A validators
+
+
 ## 0.37.2 - 2024-02-27
 
 ### Fixed

data/README.md

@@ -47,19 +47,19 @@ section](#License) for details.
 * [`hexapdf` binary][hp] for most common PDF manipulation tasks
 
 
-[canvas API]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Content/Canvas.html
-[document composition engine]: https://hexapdf.gettalong.org/documentation/key-topics/document-layout.html
+[canvas API]: https://hexapdf.gettalong.org/documentation/api/HexaPDF/Content/Canvas.html
+[document composition engine]: https://hexapdf.gettalong.org/documentation/document-creation/document-layout.html
 [flowing text]: https://hexapdf.gettalong.org/examples/frame_text_flow.html
-[styles]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Layout/Style/index.html
-[(un)ordered lists]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Layout/ListBox.html
-[multi-column layout]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Layout/ColumnBox.html
-[PDF forms]: https://hexapdf.gettalong.org/documentation/key-topics/forms.html
-[Document outline]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Type/Outline.html
-[attaching files]: https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Document/Files.html
-[Encryption]: https://hexapdf.gettalong.org/documentation/key-topics/encryption.html
-[Digital Signatures]: https://hexapdf.gettalong.org/documentation/key-topics/digital-signatures.html
+[styles]: https://hexapdf.gettalong.org/documentation/api/HexaPDF/Layout/Style/index.html
+[(un)ordered lists]: https://hexapdf.gettalong.org/documentation/api/HexaPDF/Layout/ListBox.html
+[multi-column layout]: https://hexapdf.gettalong.org/documentation/api/HexaPDF/Layout/ColumnBox.html
+[PDF forms]: https://hexapdf.gettalong.org/documentation/interactive-forms/index.html
+[Document outline]: https://hexapdf.gettalong.org/documentation/outline/index.html
+[attaching files]: https://hexapdf.gettalong.org/documentation/api/HexaPDF/Document/Files.html
+[Encryption]: https://hexapdf.gettalong.org/documentation/encryption/index.html
+[Digital Signatures]: https://hexapdf.gettalong.org/documentation/digital-signatures/index.html
 [File size optimization]: https://hexapdf.gettalong.org/documentation/benchmarks/optimization.html
-[hp]: https://hexapdf.gettalong.org/documentation/reference/hexapdf.1.html
+[hp]: https://hexapdf.gettalong.org/documentation/hexapdf.1.html
 
 
 ## Usage
@@ -126,7 +126,7 @@ featureful API when it comes to creating content, for individual pages as well a
 If you want to migrate from Prawn to HexaPDF, there is the [migration guide] with detailed
 information and examples, comparing the Prawn API to HexaPDF's equivalents.
 
-[migration guide]: https://hexapdf.gettalong.org/documentation/howtos/migrating-from-prawn.html
+[migration guide]: https://hexapdf.gettalong.org/documentation/document-creation/migrating-from-prawn.html
 
 Why use HexaPDF?
 
@@ -145,9 +145,10 @@ Why use HexaPDF?
   manipulating PDFs. This tool is intended to be a replacement for tools like `pdftk` and the
   various Poppler-based tools like `pdfinfo`, `pdfimages`, ...
 
-[Prawn]: http://prawnpdf.org
+[Prawn]: https://prawnpdf.org
 [page canvas API]: https://hexapdf.gettalong.org/api/HexaPDF/Content/Canvas.html
 
+
 ## Development
 
 Clone the repository and then run `rake dev:setup`. This will install the needed Rubygem
@@ -178,6 +179,9 @@ Some included files have a different license:
 * The AES test vector files in `test/data/aes-test-vectors` have been created using the test vector
   file available from <http://csrc.nist.gov/groups/STM/cavp/block-ciphers.html#test-vectors>.
 
+* The license of the file `data/hexapdf/sRGB2014.icc` is available in the
+  `data/hexapdf/sRGB2014.icc.LICENSE` file.
+
 
 ## Contributing
 

data/data/hexapdf/sRGB2014.icc.LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2015 International Color Consortium
+
+This profile is made available by the International Color Consortium,
+and may be copied, distributed, embedded, made, used, and sold without
+restriction. Altered versions of this profile shall have the original
+identification and copyright information removed and shall not be
+misrepresented as the original profile.

data/examples/030-pdfa.rb

@@ -0,0 +1,89 @@
+# # PDF/A Conformance
+#
+# This example shows how to create a PDF file that is PDF/A compliant.
+#
+# In this case we are creating a simple invoice, with multiple line
+# items that break across the page boundary.
+#
+# Usage:
+# : `ruby pdfa.rb`
+#
+require 'hexapdf'
+
+HexaPDF::Composer.create('pdfa.pdf') do |composer|
+  composer.document.task(:pdfa)
+  composer.document.config['font.map'] = {
+    'Lato' => {
+      none: '/usr/share/fonts/truetype/lato/Lato-Regular.ttf',
+      bold: '/usr/share/fonts/truetype/lato/Lato-Bold.ttf',
+      italic: '/usr/share/fonts/truetype/lato/Lato-Italic.ttf',
+      bold_italic: '/usr/share/fonts/truetype/lato/Lato-BoldItalic.ttf',
+    },
+  }
+
+  company = {
+    name: 'Sample Corp Limited',
+    address: ["Example Avenue 1", "12345 Runway"],
+  }
+
+  # Define all styles
+  composer.style(:base, font: 'Lato', font_size: 10, line_spacing: 1.3)
+  composer.style(:top, font_size: 8)
+  composer.style(:top_box, padding: [100, 0, 0], margin: [0, 0, 10], border: {width: [0, 0, 1]})
+  composer.style(:header, font: ['Lato', variant: :bold], font_size: 20, margin: [50, 0, 20])
+  composer.style(:line_items, border: {width: 1, color: "eee"}, margin: [20, 0])
+  composer.style(:line_item_cell, font_size: 8)
+  composer.style(:footer, border: {width: [1, 0, 0], color: "darkgrey"},
+                 padding: [5, 0, 0], valign: :bottom)
+  composer.style(:footer_heading, font: ['Lato', variant: :bold],
+                 font_size: 8, padding: [0, 0, 8])
+  composer.style(:footer_text,  font_size: 8, fill_color: "darkgrey")
+
+  # Top part
+  composer.box(:container, style: :top_box) do |container|
+    container.formatted_text([{text: company[:name], font: ['Lato', variant: :bold]},
+                              " - " + company[:address].join(' - ')], style: :top)
+  end
+  composer.text("Mega Client\nSmall Lane 5\n67890 Noonestown", mask_mode: :box)
+  cells = [["Invoice number:", "2024/01"],
+           ["Invoice date", "2024-03-10"],
+           ["Service date:", "2024-02-01"]]
+  composer.table(cells, column_widths: [150, 80], style: {align: :right}) do |args|
+    args[] = {cell: {border: {width: 0}, padding: 2}, text_align: :right}
+    args[0..-1, 0] = {font: ['Lato', variant: :bold]}
+  end
+
+  # Middle part
+  composer.text("Invoice - 2024/01", style: :header)
+  composer.text("Thank you for your order. Following are the items you purchased:")
+
+  cells = [["Description", "Price", "Amount", "Total"]]
+  max = 40
+  1.upto(max) do |index|
+    cells << ["Sample Item E.g. #{index}", "€ 250,00", index, "€ #{250 * index},00"]
+  end
+  cells << [nil, nil, nil, "€ #{250 * max * (max + 1) / 2},00"]
+  composer.table(cells, column_widths: [250, 80], style: :line_items) do |args|
+    args[] = {cell: {border: {width: 0}, padding: 8}, style: :line_item_cell}
+    args[0] = {cell: {background_color: "eee"}, font: ["Lato", variant: :bold]}
+    args[-1] = {cell: {background_color: "eee", border: {width: [2, 0, 0]}},
+                font: ["Lato", variant: :bold]}
+    args[0..-1, 1..-1] = {text_align: :right}
+  end
+
+  composer.text("Please transfer the total amount via SEPA transfer to the bank " \
+                "account below immediately after receiving the invoice - thank you.")
+
+  # Bottom part
+  l = composer.document.layout
+  cells = [
+    [l.text(company[:name], style: :footer_heading),
+     l.text(company[:address].join("\n"), style: :footer_text)],
+    [l.text('Contact', style: :footer_heading),
+     l.text("owner@samplecorp.com\nOwner: Me, Myself, And I", style: :footer_text)],
+    [l.text('Bank Account', style: :footer_heading),
+     l.text("Sample Corp Bank\nIBAN: SC01 2345 6789 0123 4567\nBIC: SACOZZB123",
+            style: :footer_text)],
+  ]
+  composer.table([cells], cell_style: {border: {width: 0}}, style: :footer)
+end

data/lib/hexapdf/configuration.rb

@@ -568,6 +568,7 @@ module HexaPDF
                       'task.map' => {
                         optimize: 'HexaPDF::Task::Optimize',
                         dereference: 'HexaPDF::Task::Dereference',
+                        pdfa: 'HexaPDF::Task::PDFA',
                       })
 
   # The global configuration object, providing the following options:
@@ -688,6 +689,8 @@ module HexaPDF
                         XXCIDSystemInfo: 'HexaPDF::Type::CIDFont::CIDSystemInfo',
                         Group: 'HexaPDF::Type::Form::Group',
                         Metadata: 'HexaPDF::Type::Metadata',
+                        OutputIntent: 'HexaPDF::Type::OutputIntent',
+                        XXDestOutputProfileRef: 'HexaPDF::Type::OutputIntent::DestOutputProfileRef',
                       },
                       'object.subtype_map' => {
                         nil => {
@@ -707,6 +710,9 @@ module HexaPDF
                           Link: 'HexaPDF::Type::Annotations::Link',
                           Widget: 'HexaPDF::Type::Annotations::Widget',
                           XML: 'HexaPDF::Type::Metadata',
+                          GTS_PDFX: 'HexaPDF::Type::OutputIntent',
+                          GTS_PDFA1: 'HexaPDF::Type::OutputIntent',
+                          ISO_PDFE1: 'HexaPDF::Type::OutputIntent',
                         },
                         XObject: {
                           Image: 'HexaPDF::Type::Image',
@@ -738,6 +744,11 @@ module HexaPDF
                           Ch: 'HexaPDF::Type::AcroForm::ChoiceField',
                           Sig: 'HexaPDF::Type::AcroForm::SignatureField',
                         },
+                        OutputIntent: {
+                          GTS_PDFX: 'HexaPDF::Type::OutputIntent',
+                          GTS_PDFA1: 'HexaPDF::Type::OutputIntent',
+                          ISO_PDFE1: 'HexaPDF::Type::OutputIntent',
+                        },
                       })
 
 end

data/lib/hexapdf/document/layout.rb

@@ -486,10 +486,14 @@ module HexaPDF
 
         # Retrieves the merged keyword arguments for the cell in +row+ and +col+.
         #
-        # Earlier defined arguments are overridden by later ones.
+        # Earlier defined arguments are overridden by later ones, except for the +:cell+ key which
+        # is merged.
         def retrieve_arguments_for(row, col)
           @argument_infos.each_with_object({}) do |arg_info, result|
             next unless arg_info.rows.cover?(row) && arg_info.cols.cover?(col)
+            if arg_info.args[:cell]
+              arg_info.args[:cell] = (result[:cell] || {}).merge(arg_info.args[:cell])
+            end
             result.update(arg_info.args)
           end
         end
@@ -635,15 +639,15 @@ module HexaPDF
       # If the +properties+ hash is not empty, the retrieved style is duplicated and the properties
       # hash is applied to it.
       #
-      # Finally, a default font is set if necessary to ensure that the style object works in all
-      # cases.
+      # Finally, a default font (the one from the :base style or otherwise 'Times') is set if
+      # necessary to ensure that the style object works in all cases.
       def retrieve_style(style, properties = nil)
         if style.kind_of?(Symbol) && !@styles.key?(style)
           raise HexaPDF::Error, "Style #{style} not defined"
         end
         style = HexaPDF::Layout::Style.create(@styles[style] || style || @styles[:base])
         style = style.dup.update(**properties) unless properties.nil? || properties.empty?
-        style.font('Times') unless style.font?
+        style.font(@styles[:base].font? && @styles[:base].font || 'Times') unless style.font?
         unless style.font.respond_to?(:pdf_object)
           name, options = *style.font
           style.font(@document.fonts.add(name, **(options || {})))

data/lib/hexapdf/document/metadata.rb

@@ -80,6 +80,10 @@ module HexaPDF
     # String::
     #     Maps to the XMP simple string value. Values need to be of type String.
     #
+    # Integer::
+    #     Maps to the XMP integer core value type and gets formatted as string. Values need to be of
+    #     type Integer.
+    #
     # Date::
     #     Maps to the XMP simple string value, correctly formatted. Values need to be of type Time,
     #     Date, or DateTime
@@ -123,6 +127,7 @@ module HexaPDF
         "pdf" => "http://ns.adobe.com/pdf/1.3/",
         "dc" => "http://purl.org/dc/elements/1.1/",
         "x" => "adobe:ns:meta/",
+        "pdfaid" => "http://www.aiim.org/pdfa/ns/id/",
       }.freeze
 
       # Contains a mapping of predefined XMP properties to their types, i.e. from namespace to
@@ -143,6 +148,10 @@ module HexaPDF
           'description' => 'LanguageArray',
           'title' => 'LanguageArray',
         }.freeze,
+        "http://www.aiim.org/pdfa/ns/id/" => {
+          'part' => 'Integer',
+          'conformance' => 'String',
+        }.freeze,
       }.freeze
 
       # Creates a new Metadata object for the given PDF document.
@@ -150,7 +159,7 @@ module HexaPDF
         @document = document
         @namespaces = PREDEFINED_NAMESPACES.dup
         @properties = PREDEFINED_PROPERTIES.transform_values(&:dup)
-        @default_language = document.catalog[:Lang] || 'en'
+        @default_language = document.catalog[:Lang] || 'x-default'
         @metadata = Hash.new {|h, k| h[k] = {} }
         write_info_dict(true)
         write_metadata_stream(true)
@@ -166,7 +175,7 @@ module HexaPDF
       # is given. Otherwise sets the default language to the given language.
       #
       # The initial default lanuage is taken from the document catalog's /Lang entry. If that is not
-      # set, the default language is assumed to be English ('en').
+      # set, the default language is assumed to be default language ('x-default').
       def default_language(value = :UNSET)
         if value == :UNSET
           @default_language
@@ -213,8 +222,8 @@ module HexaPDF
 
       # Registers the +property+ for the namespace specified via +prefix+ as the given +type+.
       #
-      # The argument +type+ has to be one of the following: 'String', 'Date', 'URI', 'Boolean',
-      # 'OrderedArray', 'UnorderedArray', or 'LanguageArray'.
+      # The argument +type+ has to be one of the following: 'String', 'Integer', 'Date', 'URI',
+      # 'Boolean', 'OrderedArray', 'UnorderedArray', or 'LanguageArray'.
       def register_property_type(prefix, property, type)
         (@properties[namespace(prefix)] ||= {})[property] = type
       end
@@ -240,13 +249,31 @@ module HexaPDF
       end
 
       # :call-seq:
-      #   metadata.title          -> title or nil
-      #   metadata.title(value    -> value
+      #   metadata.delete
+      #   metadata.delete(ns_prefix)
+      #   metadata.delete(ns_prefix, name)
+      #
+      # Deletes either all metadata properties, only the ones from a specific namespace, or a
+      # specific one.
+      def delete(ns = nil, property = nil)
+        if ns.nil? && property.nil?
+          @metadata.clear
+        elsif property.nil?
+          @metadata.delete(namespace(ns))
+        else
+          @metadata[namespace(ns)].delete(property)
+        end
+      end
+
+      # :call-seq:
+      #   metadata.title           -> title or nil
+      #   metadata.title(value)    -> value
       #
       # Returns the document's title if no argument is given. Otherwise sets the document's title to
       # the given value.
       #
-      # The language for the title is specified via #default_language.
+      # If the +value+ is a LocalizedString, the language for the title is taken from it. Otherwise
+      # the language specified via #default_language is used.
       #
       # The value +nil+ is returned if the property is not set. And by using +nil+ as +value+ the
       # property is deleted from the metadata.
@@ -278,7 +305,8 @@ module HexaPDF
       # Returns the subject of the document if no argument is given. Otherwise sets the subject to
       # the given value.
       #
-      # The language for the subject is specified via #default_language.
+      # If the +value+ is a LocalizedString, the language for the subject is taken from it.
+      # Otherwise the language specified via #default_language is used.
       #
       # The value +nil+ is returned if the property ist not set. And by using +nil+ as +value+ the
       # property is deleted from the metadata.
@@ -406,23 +434,30 @@ module HexaPDF
         ns_xmp = namespace('xmp')
         ns_pdf = namespace('pdf')
 
+        producer("HexaPDF version #{HexaPDF::VERSION}")
+
         if write_info_dict?
           info_dict = @document.trailer.info
           info_dict[:Title] = Array(@metadata[ns_dc]['title']).first
-          info_dict[:Author] = Array(@metadata[ns_dc]['creator']).join(', ')
+          if @metadata[ns_dc].key?('creator')
+            info_dict[:Author] = Array(@metadata[ns_dc]['creator']).join(', ')
+          end
           info_dict[:Subject] = Array(@metadata[ns_dc]['description']).first
           info_dict[:Creator] = @metadata[ns_xmp]['CreatorTool']
           info_dict[:CreationDate] = @metadata[ns_xmp]['CreateDate']
           info_dict[:ModDate] = @metadata[ns_xmp]['ModifyDate']
           info_dict[:Keywords] = @metadata[ns_pdf]['Keywords']
           info_dict[:Producer] = @metadata[ns_pdf]['Producer']
-          info_dict[:Trapped] = @metadata[ns_pdf]['Trapped'] ? :True : :False
+          if @metadata[ns_pdf].key?('Trapped')
+            info_dict[:Trapped] = @metadata[ns_pdf]['Trapped'] ? :True : :False
+          end
         end
 
         if write_metadata_stream?
           descriptions = @metadata.map do |namespace, values|
+            next if values.empty?
             xmp_description(@namespaces.key(namespace), values)
-          end.join("\n")
+          end.compact.join("\n")
           obj = @document.catalog[:Metadata] ||= @document.add({Type: :Metadata, Subtype: :XML})
           obj.stream = xmp_packet(descriptions)
         end
@@ -432,9 +467,11 @@ module HexaPDF
       def xmp_packet(data)
         <<~XMP
           <?xpacket begin="\u{FEFF}" id="#{SecureRandom.uuid.tr('-', '')}"?>
+          <x:xmpmeta xmlns:x="adobe:ns:meta/">
           <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
           #{data}
           </rdf:RDF>
+          </x:xmpmeta>
           <?xpacket end="r"?>
         XMP
       end
@@ -444,8 +481,8 @@ module HexaPDF
         values = values.map do |name, value|
           str = +"<#{ns_prefix}:#{name}"
           case (property_type = @properties[namespace(ns_prefix)][name])
-          when 'String'
-            str << ">#{xmp_escape(value)}</#{ns_prefix}:#{name}>"
+          when 'String', 'Integer'
+            str << ">#{xmp_escape(value.to_s)}</#{ns_prefix}:#{name}>"
           when 'Date'
             str << ">#{xmp_date(value)}</#{ns_prefix}:#{name}>"
           when 'URI'

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