hexapdf 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0e469ae650b98b48c88b662dab27cb405b676c706639c8c1cf358d6aefc8f53
-  data.tar.gz: d170526233e1e9aa37403c1bd8d2aa38697641c1b4fb4d4a5f6d8f02f299585b
+  metadata.gz: 82d0430964f9f4c6925af5bb076a2e641908c3a4cb6796acc64dbe1303bc3407
+  data.tar.gz: 689a86b637a86331ca203d7d7ac90a9fb3c50c275f07b21d8109013faa509f07
 SHA512:
-  metadata.gz: fd18408ed2c2474e3395bf59b3a0281cb23005d16bf7d5b9d93f673dfa131fc215f342018d0cdce2de053db85c000a68c28a76ad980b0432b1a159bd51b1ed0c
-  data.tar.gz: c58b13ed27c980bb9670b9521a12b1640fc3960aea1188f6135951cfd1503a28e7633cb3f6be8c63d478d64a88e0bbdc9b84bdbc982aa3ec000aeac1a8627597
+  metadata.gz: 4cfe8038379e5dc7f3bebeb38b44525676b934cb2b2355ac7575fa7a4466a6c4ec9ab9e0a80a184aebab32b2aa87e06dff735c10915abebe11541ada95d8129c
+  data.tar.gz: 62562b4bae557ad3dac03cb51913a8d1d6796d6cad9ce0626bc901cc15afeb301e42d061c345a1ebcb30e09a018dbe4b7c26fc4c567423c262f67607d04b95c9

data/CHANGELOG.md

@@ -1,3 +1,48 @@
+## 1.4.0 - 2025-08-03
+
+### Added
+
+* [HexaPDF::Type::Annotations::Polygon] for polygon annotations as well as
+  [HexaPDF::Document::Annotations#create_polygon]
+* [HexaPDF::Type::Annotations::Polyline] for polyline annotations as well as
+  [HexaPDF::Document::Annotations#create_polyline]
+* [HexaPDF::Layout::ContainerBox#splitable] for specifying whether the container
+  box may be split
+* [HexaPDF::Layout::Style::Layers#layers] for retrieving the list of defined
+  layers
+* [HexaPDF::Document::Layout#resolve_font] for resolving the font style property
+* [HexaPDF::Type::Measure] for representing the measure dictionary
+* [HexaPDF::Layout::Box::FitResult#failure!] for setting the result status to
+  failure
+
+### Changed
+
+* **Breaking change**: Extracted `#line_ending_style` and associated data class
+  from [HexaPDF::Type::Annotations::Line] into
+  [HexaPDF::Type::Annotations::LineEndingStyling]
+* [HexaPDF::Layout::TableBox] implementation to allow setting the minimum height
+  of a table cell
+* [HexaPDF::Layout::Style::Quad#set] to allow setting a subset of values using a
+  hash
+* CLI command `hp form` to show the names of radio button widgets
+* CLI command `hp form` to show position and size of widgets in easier to
+  understand form
+* Default signing handler to not set /DigestMethod entry on signature reference
+  dictionary anymore
+
+### Fixed
+
+* Parsing and writing the /ModDate and /CreationDate trailer info fields in case
+  of string values when using the XMP metadata handler
+* [HexaPDF::Layout::Style] to not accidentally set subscript or superscript
+  values
+* [HexaPDF::DictionaryFields::DateConverter] to handle invalid dates with two
+  trailing apostrophes
+* [HexaPDF::Document::Layout::CellArgumentCollector#retrieve_arguments_for] to
+  not change the stored data
+* Encryption when using AES with 256bits and an owner password
+
+
 ## 1.3.0 - 2025-04-23
 
 ### Added

data/lib/hexapdf/cli/form.rb

@@ -161,8 +161,8 @@ module HexaPDF
             (field.alternate_field_name ? " (#{field.alternate_field_name})" : '')
           concrete_field_type = field.concrete_field_type
           nice_field_type = concrete_field_type.to_s.split('_').map(&:capitalize).join(' ')
-          size = "(#{widget[:Rect].width.round(3)}x#{widget[:Rect].height.round(3)})"
-          position = "(#{widget[:Rect].left}, #{widget[:Rect].bottom})"
+          size = "#{widget[:Rect].width.round(3)}x#{widget[:Rect].height.round(3)}"
+          position = "x=#{widget[:Rect].left}, y=#{widget[:Rect].bottom}"
           field_value = if !field.field_value || concrete_field_type != :signature_field
                           field.field_value.inspect
                         else
@@ -172,10 +172,15 @@ module HexaPDF
                           temp
                         end
 
+          if concrete_field_type == :radio_button
+            rb_name = ((widget.appearance_dict&.normal_appearance&.value&.keys || []) - [:Off]).first
+            rb_name = " (#{rb_name.inspect})"
+          end
+
           flags = field_flags(field)
-          puts "  #{field_name}" << (flags.empty? ? '' : " (#{flags.join(', ')})")
+          puts "  #{field_name}#{rb_name}" << (flags.empty? ? '' : " (#{flags.join(', ')})")
           if command_parser.verbosity_info?
-            printf("    └─ %-22s | %-20s\n", nice_field_type, "#{size} #{position}")
+            printf("    └─ %-22s | %-20s\n", nice_field_type, "#{position}, #{size} ")
           end
           puts "    └─ #{field_value}"
           if command_parser.verbosity_info?

data/lib/hexapdf/configuration.rb

@@ -374,6 +374,11 @@ module HexaPDF
   #    The default implementation returns an object of class HexaPDF::Font::InvalidGlyph which, when
   #    not removed before encoding, will raise a HexaPDF::MissingGlyphError.
   #
+  #    Note: The 'font.on_invalid_glyph' configuration option does something similar but is used
+  #    later and only by the layout engine. If this callback hook returns an invalid glyph instance,
+  #    the 'font.on_invalid_glyph' callback hook is invoked when using the layout engine and it can
+  #    return a substitute glyph in any font.
+  #
   #    If a replacement glyph should be displayed instead of an error, the following provides a good
   #    starting implementation:
   #
@@ -748,6 +753,7 @@ module HexaPDF
                         Namespace: 'HexaPDF::Type::Namespace',
                         MCR: 'HexaPDF::Type::MarkedContentReference',
                         OBJR: 'HexaPDF::Type::ObjectReference',
+                        Measure: 'HexaPDF::Type::Measure',
                       },
                       'object.subtype_map' => {
                         nil => {
@@ -769,6 +775,8 @@ module HexaPDF
                           Line: 'HexaPDF::Type::Annotations::Line',
                           Square: 'HexaPDF::Type::Annotations::Square',
                           Circle: 'HexaPDF::Type::Annotations::Circle',
+                          Polygon: 'HexaPDF::Type::Annotations::Polygon',
+                          PolyLine: 'HexaPDF::Type::Annotations::Polyline',
                           XML: 'HexaPDF::Type::Metadata',
                           GTS_PDFX: 'HexaPDF::Type::OutputIntent',
                           GTS_PDFA1: 'HexaPDF::Type::OutputIntent',
@@ -800,6 +808,8 @@ module HexaPDF
                           Line: 'HexaPDF::Type::Annotations::Line',
                           Square: 'HexaPDF::Type::Annotations::Square',
                           Circle: 'HexaPDF::Type::Annotations::Circle',
+                          Polygon: 'HexaPDF::Type::Annotations::Polygon',
+                          PolyLine: 'HexaPDF::Type::Annotations::Polyline',
                         },
                         XXAcroFormField: {
                           Tx: 'HexaPDF::Type::AcroForm::TextField',

data/lib/hexapdf/dictionary_fields.rb

@@ -313,7 +313,7 @@ module HexaPDF
         [String, Time, Date, DateTime]
       end
 
-      DATE_RE = /\AD:(\d{4})(\d\d)?(\d\d)?(\d\d)?(\d\d)?(\d\d)?([Z+-])?(?:(\d+)(?:'|'(\d+)'?|\z)?)?\z/n # :nodoc:
+      DATE_RE = /\AD:(\d{4})(\d\d)?(\d\d)?(\d\d)?(\d\d)?(\d\d)?([Z+-])?(?:(\d+)(?:'|'(\d+)'?'?|\z)?)?\z/n # :nodoc:
 
       # Checks if the given object is a string and converts into a Time object if possible.
       # Otherwise returns +nil+.

data/lib/hexapdf/digital_signature/signing/default_handler.rb

@@ -297,8 +297,7 @@ module HexaPDF
               raise HexaPDF::Error, "Can set DocMDP access permissions only on first signature"
             end
             params = doc.add({Type: :TransformParams, V: :'1.2', P: doc_mdp_permissions})
-            sigref = doc.add({Type: :SigRef, TransformMethod: :DocMDP, DigestMethod: :SHA256,
-                              TransformParams: params})
+            sigref = doc.add({Type: :SigRef, TransformMethod: :DocMDP, TransformParams: params})
             signature[:Reference] = [sigref]
             (doc.catalog[:Perms] ||= {})[:DocMDP] = signature
           end

data/lib/hexapdf/document/annotations.rb

@@ -158,6 +158,53 @@ module HexaPDF
         annot
       end
 
+      # :call-seq:
+      #   annotations.create_polyline(page, *points)  -> annotation
+      #
+      # Creates a polyline annotation for the given +points+ (alternating horizontal and vertical
+      # coordinates) on the given page and returns it.
+      #
+      # The polyline uses a black color and a width of 1pt. It can be further styled using the
+      # convenience methods on the returned annotation object.
+      #
+      # Example:
+      #
+      #   #>pdf-small
+      #   doc.annotations.create_polyline(doc.pages[0], 20, 20, 30, 70, 80, 60, 40, 30).
+      #     border_style(color: "hp-blue", width: 2, style: [3, 1]).
+      #     regenerate_appearance
+      #
+      # See: Type::Annotations::Polyline
+      def create_polyline(page, *points)
+        create_and_add_to_page(:PolyLine, page).
+          vertices(*points).
+          border_style(color: 0, width: 1)
+      end
+
+      # :call-seq:
+      #   annotations.create_polygon(page, *points)  -> annotation
+      #
+      # Creates a polygon annotation for the given +points+ (alternating horizontal and vertical
+      # coordinates) on the given page and returns it.
+      #
+      # The polygon uses a black color and a width of 1pt for the border and no interior color. It
+      # can be further styled using the convenience methods on the returned annotation object.
+      #
+      # Example:
+      #
+      #   #>pdf-small
+      #   doc.annotations.create_polygon(doc.pages[0], 20, 20, 30, 70, 80, 60, 40, 30).
+      #     border_style(color: "hp-blue", width: 2, style: [3, 1]).
+      #     interior_color("hp-orange").
+      #     regenerate_appearance
+      #
+      # See: Type::Annotations::Polygon
+      def create_polygon(page, *points)
+        create_and_add_to_page(:Polygon, page).
+          vertices(*points).
+          border_style(color: 0, width: 1)
+      end
+
       private
 
       # Returns the root of the destinations name tree.

data/lib/hexapdf/document/layout.rb

@@ -92,13 +92,23 @@ module HexaPDF
     #
     #     style.font = ['Helvetica', variant: :bold]
     #
-    #   Helvetica in bold could also be set the conventional way:
+    #   Helvetica in bold could also be set in the following ways:
     #
     #     style.font = 'Helvetica bold'
+    #     # or
+    #     style.font_bold = true
+    #     style.font = 'Helvetica'
+    #
+    #   The font_bold and font_italic style properties are always taken into account. For example,
+    #   if the font is set to 'Helvetica italic' and font_bold to +true+, the actual font would be
+    #   the bold _and_ italic Helvetica font.
     #
     #   However, using an array it is also possible to specify other options when setting a font,
     #   like the :subset option.
     #
+    # * It is possible to resolve the font of a style object manually by using the #resolve_font
+    #   method.
+    #
     class Layout
 
       # This class is used when a box can contain child boxes and the creation of such boxes should
@@ -231,6 +241,64 @@ module HexaPDF
         @styles.key?(name)
       end
 
+      FONT_BOLD_VARIANT_MAPPER = { #:nodoc:
+        nil => {true => :bold, false: :none},
+        none: {true => :bold, false: :none},
+        bold: {true => :bold, false: :none},
+        italic: {true => :bold_italic, false: :italic},
+        bold_italic: {true => :bold_italic, false: :italic},
+      }
+
+      FONT_ITALIC_VARIANT_MAPPER = { #:nodoc:
+        nil => {true => :italic, false: :none},
+        none: {true => :italic, false: :none},
+        italic: {true => :italic, false: :none},
+        bold: {true => :bold_italic, false: :bold},
+        bold_italic: {true => :bold_italic, false: :bold},
+      }
+
+      # Resolves the font object for the given +style+ and applies the result to it.
+      #
+      # The Layout::Style#font property is the only one without a default value but is needed for
+      # many operations. This method ensures that the +style+ has a valid font object for the font
+      # property by resolving the font name.
+      #
+      # The font object is resolved in the following way:
+      #
+      # * If the font property is not set, the font value of the :base style is used and if that is
+      #   also not set, the 'font.default' configuration value is used.
+      #
+      # * Afterwards, if the font property is a valid font object, nothing needs to be done.
+      #
+      # * Otherwise, if the font property is a single font name or a [font name, options hash]
+      #   array, it is resolved to a font object, also taking the font_bold and font_italic style
+      #   properties into account.
+      #
+      # Example:
+      #
+      #   style = layout.style(:header, font: 'Helvetica')
+      #   style.font                   # => 'Helvetica'
+      #   layout.resolve_font(style)
+      #   style.font                   # => #<HexaPDF::Font::Type1Wrapper>
+      #
+      # See: The "Box Styles" section in Layout for more details.
+      def resolve_font(style)
+        unless style.font?
+          style.font(@styles[:base].font? && @styles[:base].font || @document.config['font.default'])
+        end
+        unless style.font.respond_to?(:pdf_object)
+          name, options = *style.font
+          options ||= {}
+          if style.font_bold?
+            options[:variant] = FONT_BOLD_VARIANT_MAPPER.dig(options[:variant], style.font_bold)
+          end
+          if style.font_italic?
+            options[:variant] = FONT_ITALIC_VARIANT_MAPPER.dig(options[:variant], style.font_italic)
+          end
+          style.font(@document.fonts.add(name, **options))
+        end
+      end
+
       # :call-seq:
       #    layout.styles            -> styles
       #    layout.styles(**mapping)   -> styles
@@ -548,9 +616,10 @@ module HexaPDF
           @argument_infos.each_with_object({}) do |arg_info, result|
             next unless arg_info.rows.include?(row) && arg_info.cols.include?(col)
             if arg_info.args[:cell]
-              arg_info.args[:cell] = (result[:cell] || {}).merge(arg_info.args[:cell])
+              result.update(arg_info.args, cell: (result[:cell] || {}).merge(arg_info.args[:cell]))
+            else
+              result.update(arg_info.args)
             end
-            result.update(arg_info.args)
           end
         end
 
@@ -682,22 +751,6 @@ module HexaPDF
         end
       end
 
-      FONT_BOLD_VARIANT_MAPPER = { #:nodoc:
-        nil => {true => :bold, false: :none},
-        none: {true => :bold, false: :none},
-        bold: {true => :bold, false: :none},
-        italic: {true => :bold_italic, false: :italic},
-        bold_italic: {true => :bold_italic, false: :italic},
-      }
-
-      FONT_ITALIC_VARIANT_MAPPER = { #:nodoc:
-        nil => {true => :italic, false: :none},
-        none: {true => :italic, false: :none},
-        italic: {true => :italic, false: :none},
-        bold: {true => :bold_italic, false: :bold},
-        bold_italic: {true => :bold_italic, false: :bold},
-      }
-
       # Retrieves the appropriate HexaPDF::Layout::Style object based on the +style+ and
       # +properties+ arguments.
       #
@@ -717,20 +770,7 @@ module HexaPDF
         end
         style = HexaPDF::Layout::Style.create(@styles[style] || style || @styles[:base])
         style = style.dup.update(**properties) unless properties.nil? || properties.empty?
-        unless style.font?
-          style.font(@styles[:base].font? && @styles[:base].font || @document.config['font.default'])
-        end
-        unless style.font.respond_to?(:pdf_object)
-          name, options = *style.font
-          options ||= {}
-          if style.font_bold?
-            options[:variant] = FONT_BOLD_VARIANT_MAPPER.dig(options[:variant], style.font_bold)
-          end
-          if style.font_italic?
-            options[:variant] = FONT_ITALIC_VARIANT_MAPPER.dig(options[:variant], style.font_italic)
-          end
-          style.font(@document.fonts.add(name, **options))
-        end
+        resolve_font(style)
         style
       end
 

data/lib/hexapdf/document/metadata.rb

@@ -430,8 +430,12 @@ module HexaPDF
         @metadata[ns_dc]['creator'] = info_dict[:Author] if info_dict.key?(:Author)
         @metadata[ns_dc]['description'] = info_dict[:Subject] if info_dict.key?(:Subject)
         @metadata[ns_xmp]['CreatorTool'] = info_dict[:Creator] if info_dict.key?(:Creator)
-        @metadata[ns_xmp]['CreateDate'] = info_dict[:CreationDate] if info_dict.key?(:CreationDate)
-        @metadata[ns_xmp]['ModifyDate'] = info_dict[:ModDate] if info_dict.key?(:ModDate)
+        if info_dict.key?(:CreationDate) && !info_dict[:CreationDate].kind_of?(String)
+          @metadata[ns_xmp]['CreateDate'] = info_dict[:CreationDate]
+        end
+        if info_dict.key?(:ModDate) && !info_dict[:ModDate].kind_of?(String)
+          @metadata[ns_xmp]['ModifyDate'] = info_dict[:ModDate] if info_dict.key?(:ModDate)
+        end
         @metadata[ns_pdf]['Keywords'] = info_dict[:Keywords] if info_dict.key?(:Keywords)
         @metadata[ns_pdf]['Producer'] = info_dict[:Producer] if info_dict.key?(:Producer)
         if info_dict.key?(:Trapped) && info_dict[:Trapped] != :Unknown
@@ -528,7 +532,10 @@ module HexaPDF
       # Formats the given date-time object (Time, Date, or DateTime) to be a valid XMP date-time
       # value.
       def xmp_date(date)
-        date.strftime("%Y-%m-%dT%H:%M:%S%:z")
+        case date
+        when Time, Date, DateTime then date.strftime("%Y-%m-%dT%H:%M:%S%:z")
+        else ''
+        end
       end
 
     end

data/lib/hexapdf/document.rb

@@ -743,6 +743,15 @@ module HexaPDF
     # Before the document is written, it is validated using #validate and an error is raised if the
     # document is not valid. However, this step can be skipped if needed.
     #
+    # The method dispatches two messages:
+    #
+    # :complete_objects::
+    #   This message is dispatched before anything is done and should be used to finalize objects.
+    #
+    # :before_write::
+    #   This message is dispatched directly before the document gets serialized and allows, for
+    #   example, overriding automatic HexaPDF changes (e.g. forcefully setting a document version).
+    #
     # Options:
     #
     # incremental::

data/lib/hexapdf/encryption/standard_security_handler.rb

@@ -325,8 +325,13 @@ module HexaPDF
         options.user_password = prepare_password(options.user_password)
         options.owner_password = prepare_password(options.owner_password)
 
-        dict[:O] = compute_o_field(options.owner_password, options.user_password)
-        dict[:U] = compute_u_field(options.user_password)
+        if dict[:R] <= 4
+          dict[:O] = compute_o_field(options.owner_password, options.user_password)
+          dict[:U] = compute_u_field(options.user_password)
+        else
+          dict[:U] = compute_u_field(options.user_password)
+          dict[:O] = compute_o_field(options.owner_password, options.user_password)
+        end
 
         if dict[:R] <= 4
           encryption_key = compute_user_encryption_key(options.user_password)

data/lib/hexapdf/layout/box.rb

@@ -166,6 +166,11 @@ module HexaPDF
           @status == :overflow
         end
 
+        # Sets the result status to failure.
+        def failure!
+          @status = :failure
+        end
+
         # Returns +true+ if fitting was a failure.
         def failure?
           @status == :failure

data/lib/hexapdf/layout/container_box.rb

@@ -44,21 +44,22 @@ module HexaPDF
     # under the :container name.
     #
     # The box does not support the value :flow for the style property position, so the child boxes
-    # are laid out in the current region only. Since the boxes should be laid out together, if any
-    # box doesn't fit, the whole container doesn't fit. Splitting the container is also not possible
-    # for the same reason.
+    # are laid out in the current region only.
     #
-    # By default the child boxes are laid out from top to bottom by default. By appropriately
-    # setting the style properties 'mask_mode', 'align' and 'valign', it is possible to lay out the
-    # children bottom to top, left to right, or right to left:
+    # If #splitable is +false+ (the default) and if any box doesn't fit, the whole container doesn't
+    # fit.
+    #
+    # By default the child boxes are laid out from top to bottom. By appropriately setting the style
+    # properties 'mask_mode', 'align' and 'valign', it is possible to lay out the children bottom to
+    # top, left to right, or right to left:
     #
     # * The standard top-to-bottom layout:
     #
     #     #>pdf-composer100
     #     composer.container do |container|
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue-dark"})
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue"})
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue-light"})
+    #       container.box(height: 20, style: {background_color: "hp-blue-dark"})
+    #       container.box(height: 20, style: {background_color: "hp-blue"})
+    #       container.box(height: 20, style: {background_color: "hp-blue-light"})
     #     end
     #
     # * The bottom-to-top layout (using valign = :bottom to fill up from the bottom and mask_mode =
@@ -66,12 +67,12 @@ module HexaPDF
     #
     #     #>pdf-composer100
     #     composer.container do |container|
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue-dark",
-    #                                                mask_mode: :fill_horizontal, valign: :bottom})
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue",
-    #                                                mask_mode: :fill_horizontal, valign: :bottom})
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue-light",
-    #                                                mask_mode: :fill_horizontal, valign: :bottom})
+    #       container.box(height: 20, style: {background_color: "hp-blue-dark",
+    #                                         mask_mode: :fill_horizontal, valign: :bottom})
+    #       container.box(height: 20, style: {background_color: "hp-blue",
+    #                                         mask_mode: :fill_horizontal, valign: :bottom})
+    #       container.box(height: 20, style: {background_color: "hp-blue-light",
+    #                                         mask_mode: :fill_horizontal, valign: :bottom})
     #     end
     #
     # * The left-to-right layout (using mask_mode = :fill_vertical to fill the area to the top and
@@ -79,12 +80,12 @@ module HexaPDF
     #
     #     #>pdf-composer100
     #     composer.container do |container|
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue-dark",
-    #                                               mask_mode: :fill_vertical})
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue",
-    #                                               mask_mode: :fill_vertical})
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue-light",
-    #                                               mask_mode: :fill_vertical})
+    #       container.box(width: 20, style: {background_color: "hp-blue-dark",
+    #                                        mask_mode: :fill_vertical})
+    #       container.box(width: 20, style: {background_color: "hp-blue",
+    #                                        mask_mode: :fill_vertical})
+    #       container.box(width: 20, style: {background_color: "hp-blue-light",
+    #                                        mask_mode: :fill_vertical})
     #     end
     #
     # * The right-to-left layout (using align = :right to fill up from the right and mask_mode =
@@ -92,18 +93,42 @@ module HexaPDF
     #
     #     #>pdf-composer100
     #     composer.container do |container|
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue-dark",
-    #                                               mask_mode: :fill_vertical, align: :right})
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue",
-    #                                               mask_mode: :fill_vertical, align: :right})
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue-light",
-    #                                               mask_mode: :fill_vertical, align: :right})
+    #       container.box(width: 20, style: {background_color: "hp-blue-dark",
+    #                                        mask_mode: :fill_vertical, align: :right})
+    #       container.box(width: 20, style: {background_color: "hp-blue",
+    #                                        mask_mode: :fill_vertical, align: :right})
+    #       container.box(width: 20, style: {background_color: "hp-blue-light",
+    #                                        mask_mode: :fill_vertical, align: :right})
     #     end
     class ContainerBox < Box
 
       # The child boxes of this ContainerBox. They need to be finalized before #fit is called.
       attr_reader :children
 
+      # Specifies whether the container box allows splitting its content.
+      #
+      # If splitting is not allowed (the default), all child boxes must fit together into one
+      # region.
+      #
+      # Examples:
+      #
+      #   # Fails with an error because the content of the container box is too big
+      #   composer.column do |col|
+      #     col.container do |container|
+      #       container.lorem_ipsum
+      #     end
+      #   end
+      #
+      # ---
+      #
+      #   #>pdf-composer
+      #   composer.column do |col|
+      #     col.container(splitable: true) do |container|
+      #       container.lorem_ipsum
+      #     end
+      #   end
+      attr_reader :splitable
+
       # Creates a new container box, optionally accepting an array of child boxes.
       #
       # Example:
@@ -117,9 +142,10 @@ module HexaPDF
       #     container.text("here", mask_mode: :fill_vertical, valign: :bottom)
       #   end
       #   composer.text("Another paragraph")
-      def initialize(children: [], **kwargs)
+      def initialize(children: [], splitable: false, **kwargs)
         super(**kwargs)
         @children = children
+        @splitable = splitable
       end
 
       # Returns +true+ if no box was fitted into the container.
@@ -144,9 +170,18 @@ module HexaPDF
           end
           update_content_height { @box_fitter.content_heights.max }
           fit_result.success!
+        elsif !@box_fitter.fit_results.empty? && @splitable
+          fit_result.overflow!
         end
       end
 
+      # Splits the content of the container box. This method is called from Box#split.
+      def split_content
+        box = create_split_box
+        box.instance_variable_set(:@children, @box_fitter.remaining_boxes)
+        [self, box]
+      end
+
       # Draws the children onto the canvas at position [x, y].
       def draw_content(canvas, x, y)
         dx = x - @fit_x