prawn 0.11.1.pre → 0.11.1

data/lib/prawn/document/bounding_box.rb

@@ -8,34 +8,34 @@
 
 module Prawn
   class Document
-    
-    # :call-seq: 
-    #   bounding_box(point, options={}, &block) 
+
+    # :call-seq:
+    #   bounding_box(point, options={}, &block)
     #
     # A bounding box serves two important purposes:
     # * Provide bounds for flowing text, starting at a given point
     # * Translate the origin (0,0) for graphics primitives
     #
-    # A point and :width must be provided. :height is optional. 
+    # A point and :width must be provided. :height is optional.
     # (See stretchyness below)
-    # 
+    #
     # ==Positioning
-    # 
+    #
     # Bounding boxes are positioned relative to their top left corner and
     # the width measurement is towards the right and height measurement is
     # downwards.
-    # 
+    #
     # Usage:
-    # 
-    # * Bounding box 100pt x 100pt in the absolute bottom left of the 
+    #
+    # * Bounding box 100pt x 100pt in the absolute bottom left of the
     #   containing box:
-    # 
+    #
     #   pdf.bounding_box([0,100], :width => 100, :height => 100)
     #     stroke_bounds
     #   end
-    # 
+    #
     # * Bounding box 200pt x 400pt high in the center of the page:
-    # 
+    #
     #   x_pos = ((bounds.width / 2) - 150)
     #   y_pos = ((bounds.height / 2) + 200)
     #   pdf.bounding_box([x_pos, y_pos], :width => 300, :height => 400) do
@@ -64,7 +64,7 @@ module Prawn
     # will want to look at span() and text_box() instead
     #
     # ==Translating Coordinates
-    # 
+    #
     # When translating coordinates, the idea is to allow the user to draw
     # relative to the origin, and then translate their drawing to a specified
     # area of the document, rather than adjust all their drawing coordinates
@@ -104,30 +104,30 @@ module Prawn
     # move this drawing around the document, we simply need to recalculate the
     # top-left corner of the rectangular bounding-box, and all of our graphics
     # calls remain unmodified.
-    # 
+    #
     # ==Nesting Bounding Boxes
-    # 
-    # At the top level, bounding boxes are specified relative to the document's 
+    #
+    # At the top level, bounding boxes are specified relative to the document's
     # margin_box (which is itself a bounding box).  You can also nest bounding
     # boxes, allowing you to build components which are relative to each other
     #
     # Usage:
-    # 
+    #
     #  pdf.bounding_box([200,450], :width => 200, :height => 250) do
-    #    pdf.stroke_bounds   # Show the containing bounding box 
+    #    pdf.stroke_bounds   # Show the containing bounding box
     #    pdf.bounding_box([50,200], :width => 50, :height => 50) do
-    #      # a 50x50 bounding box that starts 50 pixels left and 50 pixels down 
+    #      # a 50x50 bounding box that starts 50 pixels left and 50 pixels down
     #      # the parent bounding box.
     #      pdf.stroke_bounds
     #    end
     #  end
-    # 
+    #
     # ==Stretchyness
-    # 
+    #
     # If you do not specify a height to a bounding box, it will become stretchy
     # and its height will be calculated automatically as you stretch the box
     # downwards.
-    # 
+    #
     #  pdf.bounding_box([100,400], :width => 400) do
     #    pdf.text("The height of this box is #{pdf.bounds.height}")
     #    pdf.text('this is some text')
@@ -135,9 +135,9 @@ module Prawn
     #    pdf.text('and finally a bit more')
     #    pdf.text("Now the height of this box is #{pdf.bounds.height}")
     #  end
-    # 
+    #
     # ==Absolute Positioning
-    # 
+    #
     # If you wish to position the bounding boxes at absolute coordinates rather
     # than relative to the margins or other bounding boxes, you can use canvas()
     #
@@ -154,13 +154,13 @@ module Prawn
     # Of course, if you use canvas, you will be responsible for ensuring that
     # you remain within the printable area of your document.
     #
-    def bounding_box(*args, &block)    
-      init_bounding_box(block) do |_|
-        map_to_absolute!(args[0])     
-        @bounding_box = BoundingBox.new(self, *args)   
+    def bounding_box(*args, &block)
+      init_bounding_box(block) do |parent_box|
+        map_to_absolute!(args[0])
+        @bounding_box = BoundingBox.new(self, parent_box, *args)
       end
-    end 
-        
+    end
+
     # A shortcut to produce a bounding box which is mapped to the document's
     # absolute coordinates, regardless of how things are nested or margin sizes.
     #
@@ -168,30 +168,31 @@ module Prawn
     #     pdf.line pdf.bounds.bottom_left, pdf.bounds.top_right
     #   end
     #
-    def canvas(&block)     
+    def canvas(&block)
       init_bounding_box(block, :hold_position => true) do |_|
-        @bounding_box = BoundingBox.new(self, [0,page.dimensions[3]], 
-          :width => page.dimensions[2], 
-          :height => page.dimensions[3] 
-        ) 
+        # Canvas bbox acts like margin_box in that its parent bounds are unset.
+        @bounding_box = BoundingBox.new(self, nil, [0,page.dimensions[3]],
+          :width => page.dimensions[2],
+          :height => page.dimensions[3]
+        )
       end
-    end  
-        
+    end
+
     private
-    
+
     def init_bounding_box(user_block, options={}, &init_block)
-      parent_box = @bounding_box       
+      parent_box = @bounding_box
 
-      init_block.call(parent_box)     
+      init_block.call(parent_box)
 
-      self.y = @bounding_box.absolute_top       
-      user_block.call   
+      self.y = @bounding_box.absolute_top
+      user_block.call
       self.y = @bounding_box.absolute_bottom unless options[:hold_position]
 
       created_box, @bounding_box = @bounding_box, parent_box
 
       return created_box
-    end   
+    end
 
     # Low level layout helper that simplifies coordinate math.
     #
@@ -199,38 +200,45 @@ module Prawn
     # is used for.
     #
     class BoundingBox
-      
-      def initialize(parent, point, options={}) #:nodoc:   
+
+      def initialize(document, parent, point, options={}) #:nodoc:
         unless options[:width]
           raise ArgumentError, "BoundingBox needs the :width option to be set"
         end
 
+        @document = document
         @parent = parent
         @x, @y = point
         @width, @height = options[:width], options[:height]
-	      @stretched_height = nil
+        @total_left_padding = 0
+        @total_right_padding = 0
+        @stretched_height = nil
       end
 
-      attr_reader :parent
-      
+      attr_reader :document, :parent
+      # The current indentation of the left side of the bounding box.
+      attr_reader :total_left_padding
+      # The current indentation of the right side of the bounding box.
+      attr_reader :total_right_padding
+
       # The translated origin (x,y-height) which describes the location
       # of the bottom left corner of the bounding box
       #
       def anchor
         [@x, @y - height]
       end
-      
+
       # Relative left x-coordinate of the bounding box. (Always 0)
-      # 
+      #
       # Example, position some text 3 pts from the left of the containing box:
-      # 
+      #
       #  draw_text('hello', :at => [(bounds.left + 3), 0])
       #
       def left
         0
       end
-      
-      
+
+
       # Temporarily adjust the @x coordinate to allow for left_padding
       #
       # Example:
@@ -242,39 +250,69 @@ module Prawn
       #     end
       #   end
       #
-      def indent(left_padding, &block)
-        @x += left_padding
-        @width -= left_padding
+      #  indent 20, 20 do
+      #    text "indented on both sides"
+      #  end
+      #
+      def indent(left_padding, right_padding = 0, &block)
+        add_left_padding(left_padding)
+        add_right_padding(right_padding)
         yield
       ensure
+        @document.bounds.subtract_left_padding(left_padding)
+        @document.bounds.subtract_right_padding(right_padding)
+      end
+
+      # Increase the left padding of the bounding box.
+      def add_left_padding(left_padding)
+        @total_left_padding += left_padding
+        @x += left_padding
+        @width -= left_padding
+      end
+
+      # Decrease the left padding of the bounding box.
+      def subtract_left_padding(left_padding)
+        @total_left_padding -= left_padding
         @x -= left_padding
         @width += left_padding
       end
-      
+
+      # Increase the right padding of the bounding box.
+      def add_right_padding(right_padding)
+        @total_right_padding += right_padding
+        @width -= right_padding
+      end
+
+      # Decrease the right padding of the bounding box.
+      def subtract_right_padding(right_padding)
+        @total_right_padding -= right_padding
+        @width += right_padding
+      end
+
       # Relative right x-coordinate of the bounding box. (Equal to the box width)
-      # 
+      #
       # Example, position some text 3 pts from the right of the containing box:
-      # 
+      #
       #  draw_text('hello', :at => [(bounds.right - 3), 0])
       #
       def right
         @width
       end
-      
+
       # Relative top y-coordinate of the bounding box. (Equal to the box height)
       #
       # Example, position some text 3 pts from the top of the containing box:
-      # 
+      #
       #  draw_text('hello', :at => [0, (bounds.top - 3)])
       #
       def top
         height
       end
-      
+
       # Relative bottom y-coordinate of the bounding box (Always 0)
       #
       # Example, position some text 3 pts from the bottom of the containing box:
-      # 
+      #
       #  draw_text('hello', :at => [0, (bounds.bottom + 3)])
       #
       def bottom
@@ -283,9 +321,9 @@ module Prawn
 
       # Relative top-left point of the bounding_box
       #
-      # Example, draw a line from the top left of the box diagonally to the 
+      # Example, draw a line from the top left of the box diagonally to the
       # bottom right:
-      # 
+      #
       #  stroke do
       #    line(bounds.top_left, bounds.bottom_right)
       #  end
@@ -296,9 +334,9 @@ module Prawn
 
       # Relative top-right point of the bounding box
       #
-      # Example, draw a line from the top_right of the box diagonally to the 
+      # Example, draw a line from the top_right of the box diagonally to the
       # bottom left:
-      # 
+      #
       #  stroke do
       #    line(bounds.top_right, bounds.bottom_left)
       #  end
@@ -310,7 +348,7 @@ module Prawn
       # Relative bottom-right point of the bounding box
       #
       # Example, draw a line along the right hand side of the page:
-      # 
+      #
       #  stroke do
       #    line(bounds.bottom_right, bounds.top_right)
       #  end
@@ -322,7 +360,7 @@ module Prawn
       # Relative bottom-left point of the bounding box
       #
       # Example, draw a line along the left hand side of the page:
-      # 
+      #
       #  stroke do
       #    line(bounds.bottom_left, bounds.top_left)
       #  end
@@ -330,25 +368,25 @@ module Prawn
       def bottom_left
         [left,bottom]
       end
-      
+
       # Absolute left x-coordinate of the bounding box
       #
       def absolute_left
         @x
       end
-      
+
       # Absolute right x-coordinate of the bounding box
       #
       def absolute_right
         @x + width
       end
-      
+
       # Absolute top y-coordinate of the bounding box
       #
       def absolute_top
         @y
       end
-      
+
       # Absolute bottom y-coordinate of the bottom box
       #
       def absolute_bottom
@@ -378,21 +416,22 @@ module Prawn
       def absolute_bottom_right
         [absolute_right, absolute_bottom]
       end
-      
+
       # Width of the bounding box
       #
       def width
         @width
       end
-      
+
       # Height of the bounding box.  If the box is 'stretchy' (unspecified
       # height attribute), height is calculated as the distance from the top of
       # the box to the current drawing position.
       #
-      def height  
+      def height
         return @height if @height
-        @stretched_height = [(absolute_top - @parent.y), @stretched_height.to_f].max
-      end    
+        @stretched_height = [(absolute_top - @document.y),
+                             @stretched_height.to_f].max
+      end
 
       # an alias for absolute_left
       def left_side
@@ -406,20 +445,20 @@ module Prawn
 
       # starts a new page
       def move_past_bottom
-         @parent.start_new_page
+        @document.start_new_page
       end
 
 
       alias_method :update_height, :height
-       
+
       # Returns +false+ when the box has a defined height, +true+ when the height
       # is being calculated on the fly based on the current vertical position.
       #
       def stretchy?
-        !@height 
+        !@height
       end
 
-    end    
-    
+    end
+
   end
 end

data/lib/prawn/document/column_box.rb

@@ -0,0 +1,113 @@
+# encoding: utf-8
+#
+# column_box.rb: Extends BoundingBox to allow for columns of text
+#
+# Author Paul Ostazeski.
+
+require "prawn/document/bounding_box"
+module Prawn
+  class Document
+
+    # A column box is a bounding box with the additional property that when
+    # text flows past the bottom, it will wrap first to another column on the
+    # same page, and only flow to the next page when all the columns are
+    # filled.
+    #
+    # column_box accepts the same parameters as bounding_box, as well as the
+    # number of :columns and a :spacer (in points) between columns.
+    #
+    # Defaults are :columns = 3 and :spacer = font_size
+    # 
+    # Under PDF::Writer, "spacer" was known as "gutter"
+    # 
+    def column_box(*args, &block)
+      init_column_box(block) do |parent_box|
+        map_to_absolute!(args[0])
+        @bounding_box = ColumnBox.new(self, parent_box, *args)
+      end
+    end
+
+    private
+
+    def init_column_box(user_block, options={}, &init_block)
+      parent_box = @bounding_box
+
+      init_block.call(parent_box)
+
+      self.y = @bounding_box.absolute_top
+      user_block.call
+      self.y = @bounding_box.absolute_bottom unless options[:hold_position]
+
+      @bounding_box = parent_box
+    end
+    
+    # Template methods to support ColumnBox extensions
+    class BoundingBox
+      
+      # an alias for absolute_left
+      def left_side
+         absolute_left
+      end
+
+      # an alias for absolute_right
+      def right_side
+         absolute_right
+      end
+
+      # starts a new page
+      def move_past_bottom
+         @document.start_new_page
+      end
+    end
+
+    # Implements the necessary functionality to allow Document#column_box to
+    # work.
+    #
+    class ColumnBox < BoundingBox
+
+      def initialize(document, parent, point, options={}) #:nodoc:
+        super
+        @columns = options[:columns] || 3
+        @spacer  = options[:spacer]  || @document.font_size
+        @current_column = 0
+      end
+
+      # The column width, not the width of the whole box.  Used to calculate
+      # how long a line of text can be.
+      #
+      def width
+        super / @columns - @spacer
+      end
+
+      # Column width including the spacer.
+      #
+      def width_of_column
+        width + @spacer
+      end
+
+      # x coordinate of the left edge of the current column
+      #
+      def left_side
+        absolute_left + (width_of_column * @current_column)
+      end
+
+      # x co-orordinate of the right edge of the current column
+      #
+      def right_side
+        columns_from_right = @columns - (1 + @current_column)
+        absolute_right - (width_of_column * columns_from_right)
+      end
+
+      # Moves to the next column or starts a new page if currently positioned at
+      # the rightmost column.
+      def move_past_bottom 
+        @current_column = (@current_column + 1) % @columns
+        @document.y = @y
+        if 0 == @current_column
+          @document.start_new_page
+        end
+      end
+
+    end
+  end
+end