Add option to ColumnBox to support resetting to parents top margin on new page.

lib/prawn/document/column_box.rb

@@ -14,9 +14,12 @@ class Document
     # filled.
     #
     # column_box accepts the same parameters as bounding_box, as well as the
-    # number of :columns and a :spacer (in points) between columns.
+    # number of :columns and a :spacer (in points) between columns. If resetting
+    # the top margin is desired on a new page (e.g. to allow for initial page 
+    # wide column titles) the option :reflow_margins => true can be set.
     #
-    # Defaults are :columns = 3 and :spacer = font_size
+    # Defaults are :columns = 3, :spacer = font_size, and 
+    # :reflow_margins => false
     # 
     # Under PDF::Writer, "spacer" was known as "gutter"
     # 
@@ -51,6 +54,7 @@ def initialize(document, parent, point, options={}) #:nodoc:
         @columns = options[:columns] || 3
         @spacer  = options[:spacer]  || @document.font_size
         @current_column = 0
+        @reflow_margins = options[:reflow_margins]
       end
 
       # The column width, not the width of the whole box,
@@ -103,6 +107,9 @@ def move_past_bottom
         @current_column = (@current_column + 1) % @columns
         @document.y = @y
         if 0 == @current_column
+          if @reflow_margins
+            @y = @parent.top
+          end
           @document.start_new_page
         end
       end

spec/column_box_spec.rb

@@ -30,4 +30,36 @@
         @pdf.bounds.right.should == 500
       end
   end
+
+  it "does not reset the top margin on a new page by default" do
+    create_pdf
+    page_top = @pdf.cursor
+    @pdf.move_down 50
+    init_column_top = @pdf.cursor
+    @pdf.column_box [0, @pdf.cursor], :width => 500,
+      :height => 200, :columns => 2 do
+
+        @pdf.bounds.move_past_bottom
+        @pdf.bounds.move_past_bottom
+
+        @pdf.bounds.absolute_top.should == init_column_top
+        @pdf.bounds.absolute_top.should_not == page_top
+      end
+  end
+
+  it "does reset the top margin when reflow_margins is set" do
+    create_pdf
+    page_top = @pdf.cursor
+    @pdf.move_down 50
+    init_column_top = @pdf.cursor
+    @pdf.column_box [0, @pdf.cursor], :width => 500, :reflow_margins => true,
+      :height => 200, :columns => 2 do
+
+        @pdf.bounds.move_past_bottom
+        @pdf.bounds.move_past_bottom
+
+        @pdf.bounds.absolute_top.should == page_top 
+        @pdf.bounds.absolute_top.should_not == init_column_top
+      end
+  end
 end