page_style.rb in hexapdf-0.46.0

- old
+ new

@@ -39,11 +39,14 @@
 require 'hexapdf/layout/frame'
 
 module HexaPDF
   module Layout
 
-    # A PageStyle defines the initial look of a page and the placement of one or more frames.
+    # A PageStyle defines the dimensions of a page, its initial look, the Frame for object placement
+    # and which page style should be used next.
+    #
+    # This class is used by HexaPDF::Composer to style the individual pages.
     class PageStyle
 
       # The page size.
       #
       # Can be any valid predefined page size (see HexaPDF::Type::Page::PAPER_SIZE) or an array
@@ -63,42 +66,45 @@
       # A callable object that defines the initial content of a page created with #create_page.
       #
       # The callable object is given a canvas and the page style as arguments. It needs to draw the
       # initial content of the page. Note that the graphics state of the canvas is *not* saved
       # before executing the template code and restored afterwards. If this is needed, the object
-      # needs to do it itself.
+      # needs to do it itself. The #next_style attribute can optionally be set.
       #
-      # Furthermore it should set the #frame and #next_style attributes appropriately, if not done
-      # beforehand. The #create_frame method can be used for easily creating a rectangular frame.
+      # Furthermore, the callable object should set the #frame that defines the area on the page
+      # where content should be placed. The #create_frame method can be used for easily creating a
+      # rectangular frame.
       #
       # Example:
       #
-      #   page_style.template = lambda do |canvas, style
+      #   page_style.template = lambda do |canvas, style|
       #     box = canvas.context.box
       #     canvas.fill_color("fd0") do
       #       canvas.rectangle(0, 0, box.width, box.height).fill
       #     end
       #     style.frame = style.create_frame(canvas.context, 72)
       #   end
       attr_accessor :template
 
-      # The HexaPDF::Layout::Frame object that defines the area on the page where content should be
-      # placed.
+      # The Frame object that defines the area for the last page created with #create_page where
+      # content should be placed.
       #
-      # This can either be set beforehand or during execution of the #template.
-      #
-      # If no frame has been set, a frame covering the page except for a default margin on all sides
-      # is set during #create_page.
+      # This value is usually updated during execution of the #template. If the value is not
+      # updated, a frame covering the page except for a default margin on all sides is set during
+      # #create_page.
       attr_accessor :frame
 
       # Defines the name of the page style that should be used for the next page.
       #
+      # Note that this value can be different each time a new page is created via #create_page.
+      #
       # If this attribute is +nil+ (the default), it means that this style should be used again.
       attr_accessor :next_style
 
       # Creates a new page style instance for the given page size, orientation and next style
-      # values. If a block is given, it is used as template for defining the initial content.
+      # values. If a block is given, it is used as #template for defining the initial content of a
+      # page.
       #
       # Example:
       #
       #   PageStyle.new(page_size: :Letter) do |canvas, style|
       #     style.frame = style.create_frame(canvas.context, 72)
@@ -111,17 +117,18 @@
         @template = block
         @frame = nil
         @next_style = next_style
       end
 
-      # Creates a new page in the given document with this page style and returns it.
+      # Creates a new page in the given document using this page style and returns it.
       #
-      # If #frame has not been set beforehand or during execution of the #template, a default frame
-      # covering the whole page except a margin of 36 is created.
+      # If the #frame has not changed during execution of the #template, a default frame covering
+      # the whole page except a margin of 36 is assigned.
       def create_page(document)
+        frame_before = @frame
         page = document.pages.create(media_box: page_size, orientation: orientation)
         template&.call(page.canvas, self)
-        self.frame ||= create_frame(page, 36)
+        self.frame = create_frame(page, 36) if @frame.equal?(frame_before)
         page
       end
 
       # Creates a frame based on the given page's box and margin.
       #