From d60cf4c7afb6bd37079b243dbf9912eee5d3ddd7 Mon Sep 17 00:00:00 2001
From: Patrick Hurley <phurley@gmail.com>
Date: Thu, 4 Jul 2013 00:17:18 -0400
Subject: [PATCH] Added option to ColumnBox to reset the top margin

This allows for page title text on the first page that is not repeated
on every page. The default is off, so it is completely backward
compatible. I also added a spec to verify the existing behavior
(which was not previously tested) and a spec to for the new option.
---
 lib/prawn/document/column_box.rb | 11 +++++++++--
 spec/column_box_spec.rb          | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/lib/prawn/document/column_box.rb b/lib/prawn/document/column_box.rb
index 71495486f..a19befe75 100644
--- a/lib/prawn/document/column_box.rb
+++ b/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
diff --git a/spec/column_box_spec.rb b/spec/column_box_spec.rb
index c35928093..8ac409153 100644
--- a/spec/column_box_spec.rb
+++ b/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