hexapdf 0.8.0 → 0.9.0

data/lib/hexapdf/configuration.rb

@@ -443,7 +443,7 @@ module HexaPDF
                         XXViewerPreferences: 'HexaPDF::Type::ViewerPreferences',
                         Action: 'HexaPDF::Type::Action',
                         XXLaunchActionWinParameters: 'HexaPDF::Type::Actions::Launch::WinParameters',
-                        Annotation: 'HexaPDF::Type::Annotation',
+                        Annot: 'HexaPDF::Type::Annotation',
                       },
                       'object.subtype_map' => {
                         nil => {
@@ -479,7 +479,7 @@ module HexaPDF
                           Launch: 'HexaPDF::Type::Actions::Launch',
                           URI: 'HexaPDF::Type::Actions::URI',
                         },
-                        Annotation: {
+                        Annot: {
                           Text: 'HexaPDF::Type::Annotations::Text',
                           Link: 'HexaPDF::Type::Annotations::Link',
                         },

data/lib/hexapdf/content/canvas.rb

@@ -1258,12 +1258,9 @@ module HexaPDF
           obj = context.document.images.add(obj)
         end
 
-        if obj[:Subtype] == :Image
-          width, height = calculate_dimensions(obj[:Width], obj[:Height],
-                                               rwidth: width, rheight: height)
-        else
-          width, height = calculate_dimensions(obj.box.width, obj.box.height,
-                                               rwidth: width, rheight: height)
+        width, height = calculate_dimensions(obj.width, obj.height,
+                                             rwidth: width, rheight: height)
+        if obj[:Subtype] != :Image
           width /= obj.box.width.to_f
           height /= obj.box.height.to_f
           at[0] -= obj.box.left

data/lib/hexapdf/dictionary.rb

@@ -261,9 +261,6 @@ module HexaPDF
       each_set_key_or_required_field do |name, field|
         obj = key?(name) ? self[name] : nil
 
-        # Validate nested objects
-        validate_nested(obj, &block)
-
         # The checks below need a valid field definition
         next if field.nil?
 

data/lib/hexapdf/document.rb

@@ -57,6 +57,8 @@ require 'hexapdf/layout'
 # * HexaPDF::Content::Canvas provides the canvas API for drawing/writing on a page or form XObject
 module HexaPDF
 
+  autoload(:Composer, 'hexapdf/composer')
+
   # Represents one PDF document.
   #
   # A PDF document consists of (indirect) objects, so the main job of this class is to provide
@@ -367,12 +369,13 @@ module HexaPDF
     end
 
     # :call-seq:
-    #   doc.each(current: true) {|obj| block }        -> doc
-    #   doc.each(current: true) {|obj, rev| block }   -> doc
-    #   doc.each(current: true)                       -> Enumerator
+    #   doc.each(only_current: true, only_loaded: false) {|obj| block }        -> doc
+    #   doc.each(only_current: true, only_loaded: false) {|obj, rev| block }   -> doc
+    #   doc.each(only_current: true, only_loaded: false)                       -> Enumerator
     #
-    # Calls the given block once for every object in the PDF document. The block may either accept
-    # only the object or the object and the revision it is in.
+    # Calls the given block once for every object, or, if +only_loaded+ is +true+, for every loaded
+    # object in the PDF document. The block may either accept only the object or the object and the
+    # revision it is in.
     #
     # By default, only the current version of each object is returned which implies that each
     # object number is yielded exactly once. If the +current+ option is +false+, all stored
@@ -387,14 +390,16 @@ module HexaPDF
     # * Additionally, there may also be objects with the same object number but different
     #   generation numbers in different revisions, e.g. one object with oid/gen [3,0] and one with
     #   oid/gen [3,1].
-    def each(current: true, &block)
-      return to_enum(__method__, current: current) unless block_given?
+    def each(only_current: true, only_loaded: false, &block)
+      unless block_given?
+        return to_enum(__method__, only_current: only_current, only_loaded: only_loaded)
+      end
 
       yield_rev = (block.arity == 2)
       oids = {}
       @revisions.reverse_each do |rev|
-        rev.each do |obj|
-          next if current && oids.include?(obj.oid)
+        rev.each(only_loaded: only_loaded) do |obj|
+          next if only_current && oids.include?(obj.oid)
           (yield_rev ? yield(obj, rev) : yield(obj))
           oids[obj.oid] = true
         end
@@ -553,22 +558,18 @@ module HexaPDF
       @security_handler
     end
 
-    # :call-seq:
-    #   doc.validate(auto_correct: true)                                       -> true or false
-    #   doc.validate(auto_correct: true) {|object, msg, correctable| block }   -> true or false
-    #
-    # Validates all objects of the document, with optional auto-correction, and returns +true+ if
-    # everything is fine.
+    # Validates all objects, or, if +only_loaded+ is +true+, only loaded objects, with optional
+    # auto-correction, and returns +true+ if everything is fine.
     #
     # If a block is given, it is called on validation problems.
     #
     # See HexaPDF::Object#validate for more information.
-    def validate(auto_correct: true)
+    def validate(auto_correct: true, only_loaded: false) #:yield: object, msg, correctable
       cur_obj = trailer
       block = (block_given? ? lambda {|msg, correctable| yield(cur_obj, msg, correctable) } : nil)
 
       result = trailer.validate(auto_correct: auto_correct, &block)
-      each(current: false) do |obj|
+      each(only_current: false, only_loaded: only_loaded) do |obj|
         cur_obj = obj
         result &&= obj.validate(auto_correct: auto_correct, &block)
       end
@@ -576,8 +577,8 @@ module HexaPDF
     end
 
     # :call-seq:
-    #   doc.write(filename, validate: true, update_fields: true, optimize: false)
-    #   doc.write(io, validate: true, update_fields: true, optimize: false)
+    #   doc.write(filename, incremental: false, validate: true, update_fields: true, optimize: false)
+    #   doc.write(io, incremental: false, validate: true, update_fields: true, optimize: false)
     #
     # Writes the document to the given file (in case +io+ is a String) or IO stream.
     #
@@ -586,6 +587,13 @@ module HexaPDF
     #
     # Options:
     #
+    # incremental::
+    #   Use the incremental writing mode which just adds a new revision to an existing document.
+    #   This is needed, for example, when modifying a signed PDF and the original signature should
+    #   stay valid.
+    #
+    #   See: PDF1.7 s7.5.6
+    #
     # validate::
     #   Validates the document and raises an error if an uncorrectable problem is found.
     #
@@ -596,7 +604,7 @@ module HexaPDF
     # optimize::
     #   Optimize the file size by using object and cross-reference streams. This will raise the PDF
     #   version to at least 1.5.
-    def write(file_or_io, validate: true, update_fields: true, optimize: false)
+    def write(file_or_io, incremental: false, validate: true, update_fields: true, optimize: false)
       dispatch_message(:complete_objects)
 
       if update_fields
@@ -619,9 +627,9 @@ module HexaPDF
       dispatch_message(:before_write)
 
       if file_or_io.kind_of?(String)
-        File.open(file_or_io, 'w+') {|file| Writer.write(self, file) }
+        File.open(file_or_io, 'w+') {|file| Writer.write(self, file, incremental: incremental) }
       else
-        Writer.write(self, file_or_io)
+        Writer.write(self, file_or_io, incremental: incremental)
       end
     end
 

data/lib/hexapdf/document/files.rb

@@ -101,7 +101,7 @@ module HexaPDF
         return to_enum(__method__, search: search) unless block_given?
 
         if search
-          @document.each(current: false) do |obj|
+          @document.each(only_current: false) do |obj|
             yield(obj) if obj.type == :Filespec
           end
         else

data/lib/hexapdf/document/images.rb

@@ -85,7 +85,7 @@ module HexaPDF
       # Note that only real images are yielded which means, for example, that images used as soft
       # mask are not.
       def each(&block)
-        images = @document.each(current: false).select do |obj|
+        images = @document.each(only_current: false).select do |obj|
           next unless obj.kind_of?(HexaPDF::Dictionary)
           obj[:Subtype] == :Image && !obj[:ImageMask]
         end

data/lib/hexapdf/filter/predictor.rb

@@ -163,16 +163,16 @@ module HexaPDF
             case data.getbyte(pos)
             when PREDICTOR_PNG_SUB
               bytes_per_pixel.upto(bytes_per_row - 2) do |i|
-                line.setbyte(i, line.getbyte(i) + line.getbyte(i - bytes_per_pixel))
+                line.setbyte(i, (line.getbyte(i) + line.getbyte(i - bytes_per_pixel)) % 256)
               end
             when PREDICTOR_PNG_UP
               0.upto(bytes_per_row - 2) do |i|
-                line.setbyte(i, line.getbyte(i) + last_line.getbyte(i))
+                line.setbyte(i, (line.getbyte(i) + last_line.getbyte(i)) % 256)
               end
             when PREDICTOR_PNG_AVERAGE
               0.upto(bytes_per_row - 2) do |i|
                 a = i < bytes_per_pixel ? 0 : line.getbyte(i - bytes_per_pixel)
-                line.setbyte(i, line.getbyte(i) + ((a + last_line.getbyte(i)) >> 1))
+                line.setbyte(i, (line.getbyte(i) + ((a + last_line.getbyte(i)) >> 1)) % 256)
               end
             when PREDICTOR_PNG_PAETH
               0.upto(bytes_per_row - 2) do |i|
@@ -187,7 +187,7 @@ module HexaPDF
 
                 point = ((pa <= pb && pa <= pc) ? a : (pb <= pc ? b : c))
 
-                line.setbyte(i, line.getbyte(i) + point)
+                line.setbyte(i, (line.getbyte(i) + point) % 256)
               end
             end
 
@@ -202,16 +202,16 @@ module HexaPDF
             case predictor
             when PREDICTOR_PNG_SUB
               bytes_per_row.downto(bytes_per_pixel + 1) do |i|
-                line.setbyte(i, line.getbyte(i) - line.getbyte(i - bytes_per_pixel))
+                line.setbyte(i, (line.getbyte(i) - line.getbyte(i - bytes_per_pixel)) % 256)
               end
             when PREDICTOR_PNG_UP
               bytes_per_row.downto(1) do |i|
-                line.setbyte(i, line.getbyte(i) - last_line.getbyte(i))
+                line.setbyte(i, (line.getbyte(i) - last_line.getbyte(i)) % 256)
               end
             when PREDICTOR_PNG_AVERAGE
               bytes_per_row.downto(1) do |i|
                 a = i <= bytes_per_pixel ? 0 : line.getbyte(i - bytes_per_pixel)
-                line.setbyte(i, line.getbyte(i) - ((a + last_line.getbyte(i)) >> 1))
+                line.setbyte(i, (line.getbyte(i) - ((a + last_line.getbyte(i)) >> 1)) % 256)
               end
             when PREDICTOR_PNG_PAETH
               bytes_per_row.downto(1) do |i|
@@ -226,7 +226,7 @@ module HexaPDF
 
                 point = ((pa <= pb && pa <= pc) ? a : (pb <= pc ? b : c))
 
-                line.setbyte(i, line.getbyte(i) - point)
+                line.setbyte(i, (line.getbyte(i) - point) % 256)
               end
             end
 

data/lib/hexapdf/layout.rb

@@ -49,6 +49,7 @@ module HexaPDF
     autoload(:Frame, 'hexapdf/layout/frame')
     autoload(:WidthFromPolygon, 'hexapdf/layout/width_from_polygon')
     autoload(:TextBox, 'hexapdf/layout/text_box')
+    autoload(:ImageBox, 'hexapdf/layout/image_box')
 
   end
 

data/lib/hexapdf/layout/box.rb

@@ -95,31 +95,49 @@ module HexaPDF
         @height = @initial_height = height
         @style = (style.kind_of?(Style) ? style : Style.new(style))
         @draw_block = block
-        @outline = nil
       end
 
       # The width of the content box, i.e. without padding and/or borders.
       def content_width
-        [0, width - (@style.padding.left + @style.padding.right +
-                     @style.border.width.left + @style.border.width.right)].max
+        width = @width - reserved_width
+        width < 0 ? 0 : width
       end
 
       # The height of the content box, i.e. without padding and/or borders.
       def content_height
-        [0, height - (@style.padding.top + @style.padding.bottom +
-                      @style.border.width.top + @style.border.width.bottom)].max
+        height = @height - reserved_height
+        height < 0 ? 0 : height
       end
 
       # Fits the box into the Frame and returns +true+ if fitting was successful.
       #
       # The default implementation uses the whole available space for width and height if they were
       # initially set to 0. Otherwise the specified dimensions are used.
-      def fit(available_width, available_height, frame)
+      def fit(available_width, available_height, _frame)
         @width = (@initial_width > 0 ? @initial_width : available_width)
         @height = (@initial_height > 0 ? @initial_height : available_height)
         @width <= available_width && @height <= available_height
       end
 
+      # Tries to split the box into two, the first of which needs to fit into the available space,
+      # and returns the parts as array.
+      #
+      # In many cases the first box in the list will be this box, meaning that even when #fit fails,
+      # a part of the box may still fit. Note that #fit may not be called if the first box is this
+      # box since it is assumed that it is already fitted. If not even a part of this box fits into
+      # the available space, +nil+ should be returned as the first array element.
+      #
+      # Possible return values:
+      #
+      # [self]:: The box fully fits into the available space.
+      # [nil, self]:: The box can't be split or no part of the box fits into the available space.
+      # [self, new_box]:: A part of the box fits and a new box is returned for the rest.
+      #
+      # This default implementation provides no splitting functionality.
+      def split(_available_width, _available_height, _frame)
+        [nil, self]
+      end
+
       # Draws the content of the box onto the canvas at the position (x, y).
       #
       # The coordinate system is translated so that the origin is at the bottom left corner of the
@@ -139,12 +157,11 @@ module HexaPDF
         style.underlays.draw(canvas, x, y, self) if style.underlays?
         style.border.draw(canvas, x, y, width, height) if style.border?
 
-        if @draw_block
-          canvas.translate(x + style.padding.left + style.border.width.left,
-                           y + style.padding.bottom + style.border.width.bottom) do
-            @draw_block.call(canvas, self)
-          end
-        end
+        cx = x
+        cy = y
+        (cx += style.padding.left; cy += style.padding.bottom) if style.padding?
+        (cx += style.border.width.left; cy += style.border.width.bottom) if style.border?
+        draw_content(canvas, cx, cy)
 
         style.overlays.draw(canvas, x, y, self) if style.overlays?
       end
@@ -158,6 +175,32 @@ module HexaPDF
           (style.overlays? && !style.overlays.none?))
       end
 
+      private
+
+      # Returns the width that is reserved by the padding and border style properties.
+      def reserved_width
+        result = 0
+        result += style.padding.left + style.padding.right if style.padding?
+        result += style.border.width.left + style.border.width.right if style.border?
+        result
+      end
+
+      # Returns the height that is reserved by the padding and border style properties.
+      def reserved_height
+        result = 0
+        result += style.padding.top + style.padding.bottom if style.padding?
+        result += style.border.width.top + style.border.width.bottom if style.border?
+        result
+      end
+
+      # Draws the content of the box at position [x, y] which is the bottom-left corner of the
+      # content box.
+      def draw_content(canvas, x, y)
+        if @draw_block
+          canvas.translate(x, y) { @draw_block.call(canvas, self) }
+        end
+      end
+
     end
 
   end

data/lib/hexapdf/layout/frame.rb

@@ -42,11 +42,35 @@ module HexaPDF
     #
     # == Usage
     #
-    # After a Frame object is initialized, the #draw method can be used to draw a box onto frame. If
-    # drawing is successful, the next box can be drawn. Otherwise, #find_next_region should be
-    # called to determine the next region for placing the box. If the call returns +true+, a region
-    # was found and #draw can be tried again. Once #find_next_region returns +false+ the frame has
-    # no more space for placing boxes.
+    # After a Frame object is initialized, it is ready for drawing boxes on it.
+    #
+    # The explicit way of drawing a box follows these steps:
+    #
+    # * Call #fit with the box to see if the box can fit into the currently selected region of
+    #   available space. If fitting is successful, the box can be drawn using #draw.
+    #
+    #   The method #fit is also called for absolutely positioned boxes but since these boxes are not
+    #   subject to the normal constraints, the available space used is the width and height inside
+    #   the frame to the right and top of the bottom-left corner of the box.
+    #
+    # * If the box didn't fit, call #find_next_region to determine the next region for placing the
+    #   box. If a new region was found, start over with #fit. Otherwise the frame has no more space
+    #   for placing boxes.
+    #
+    # * Alternatively to calling #find_next_region it is also possible to call #split. This method
+    #   tries to split the box into two so that the first part fits into the current region. If
+    #   splitting is successful, the first box can be drawn (Make sure that the second box is
+    #   handled correctly). Otherwise, start over with #find_next_region.
+    #
+    # For applications where splitting is not necessary, an easier way is to just use #draw and
+    # #find_next_region together, as #draw calls #fit if the box was not fit into the current
+    # region.
+    #
+    # == Used Box Properties
+    #
+    # The style properties "position", "position_hint" and "margin" are taken into account when
+    # 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
     #
@@ -63,6 +87,42 @@ module HexaPDF
 
       include Geom2D::Utils
 
+      # Internal class for storing data of a fitted box.
+      class FitData
+
+        # The box that was fitted into the frame.
+        attr_accessor :box
+
+        # The available width for this particular box.
+        attr_accessor :available_width
+
+        # The available height for this particular box.
+        attr_accessor :available_height
+
+        # The left margin to use instead of +box.style.margin.left+.
+        attr_accessor :margin_left
+
+        # The right margin to use instead of +box.style.margin.right+.
+        attr_accessor :margin_right
+
+        # The top margin to use instead of +box.style.margin.top+.
+        attr_accessor :margin_top
+
+        # Initialize the object by calling #reset.
+        def initialize
+          reset
+        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
+        end
+
+      end
+
       # The x-coordinate of the bottom-left corner.
       attr_reader :left
 
@@ -78,12 +138,9 @@ module HexaPDF
       # The shape of the frame, a Geom2D::PolygonSet consisting of rectilinear polygons.
       attr_reader :shape
 
-      # The contour line of the frame, a Geom2D::PolygonSet consisting of arbitrary polygons.
-      attr_reader :contour_line
-
       # The x-coordinate where the next box will be placed.
       #
-      # Note: Since the algorithm for #draw takes the margin of a box into account, the actual
+      # Note: Since the algorithm for drawing takes the margin of a box into account, the actual
       # x-coordinate (and y-coordinate, available width and available height) might be different.
       attr_reader :x
 
@@ -103,18 +160,12 @@ module HexaPDF
       attr_reader :available_height
 
       # Creates a new Frame object for the given rectangular area.
-      #
-      # If the contour line of the frame is not specified, then the rectangular area is used as
-      # contour line.
       def initialize(left, bottom, width, height, contour_line: nil)
         @left = left
         @bottom = bottom
         @width = width
         @height = height
-        @contour_line = contour_line || Geom2D::PolygonSet.new(
-          [create_rectangle(left, bottom, left + width, bottom + height)]
-        )
-
+        @contour_line = contour_line
         @shape = Geom2D::PolygonSet.new(
           [create_rectangle(left, bottom, left + width, bottom + height)]
         )
@@ -123,36 +174,69 @@ module HexaPDF
         @available_width = width
         @available_height = height
         @region_selection = :max_height
+        @fit_data = FitData.new
       end
 
-      # Draws the given box onto the canvas at the frame's current position. Returns +true+ if
-      # drawing was possible, +false+ otherwise.
-      #
-      # When positioning the box, the style properties "position", "position_hint" and "margin" are
-      # taken into account. Note that the margin is ignored if a box's side coincides with the
-      # frame's original boundary.
-      #
-      # After a box is successfully drawn, the frame's shape and contour line are adjusted to remove
-      # the occupied area.
-      def draw(canvas, box)
+      # Fits the given box into the current region of available space.
+      def fit(box)
         aw = available_width
         ah = available_height
-        used_margin_left = used_margin_right = used_margin_top = 0
+        @fit_data.reset(box, aw, ah)
 
-        if box.style.position != :absolute
+        if full?
+          false
+        elsif box.style.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 -= used_margin_top = margin.top unless float_equal(@y, @bottom + @height)
-            aw -= used_margin_right = margin.right unless float_equal(@x + aw, @left + @width)
-            aw -= used_margin_left = margin.left unless float_equal(@x, @left)
+            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
 
-          return false unless box.fit(aw, ah, self)
+          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
+
+      # 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
@@ -160,18 +244,17 @@ module HexaPDF
           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)
                       else
                         create_rectangle(x, y, x + width, y + height)
                       end
         when :float
-          x = @x + used_margin_left
-          x += aw - width if box.style.position_hint == :right
-          y = @y - height - used_margin_top
-          # We can use the real margins from the box because they either have the desired effect or
-          # just extend the rectangle outside the frame.
+          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
@@ -181,24 +264,25 @@ module HexaPDF
         else
           x = case box.style.position_hint
               when :right
-                @x + used_margin_left + aw - width
+                @x + @fit_data.margin_left + @fit_data.available_width - width
               when :center
-                max_margin = [used_margin_left, used_margin_right].max
+                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 + used_margin_left + (aw - width) / 2.0
+                  @x + @fit_data.margin_left + (@fit_data.available_width - width) / 2.0
                 end
               else
-                @x + used_margin_left
+                @x + @fit_data.margin_left
               end
-          y = @y - height - used_margin_top
+          y = @y - height - @fit_data.margin_top
           rectangle = create_rectangle(left, y - (margin&.bottom || 0), left + self.width, @y)
         end
 
         box.draw(canvas, x, y)
         remove_area(rectangle)
+        @fit_data.reset
 
         true
       end
@@ -229,6 +313,7 @@ module HexaPDF
           trim_shape
         end
 
+        @fit_data.reset
         available_width != 0
       end
 
@@ -236,12 +321,24 @@ module HexaPDF
       # line.
       def remove_area(polygon)
         @shape = Geom2D::Algorithms::PolygonOperation.run(@shape, polygon, :difference)
-        @contour_line = Geom2D::Algorithms::PolygonOperation.run(@contour_line, polygon,
-                                                                 :difference)
+        if @contour_line
+          @contour_line = Geom2D::Algorithms::PolygonOperation.run(@contour_line, polygon,
+                                                                   :difference)
+        end
         @region_selection = :max_width
         find_next_region
       end
 
+      # Returns +true+ if the frame has no more space left.
+      def full?
+        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.
       #
@@ -255,7 +352,7 @@ module HexaPDF
       # 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(contour_line, offset)
       end
 
       private