prawn 0.11.1 → 0.15.0

data/lib/prawn/layout/grid.rb

@@ -1,15 +1,22 @@
 module Prawn
   class Document
-    
-    # Defines the grid system for a particular document.  Takes the number of 
-    # rows and columns and the width to use for the gutter as the 
+    # @group Experimental API
+
+    # Defines the grid system for a particular document.  Takes the number of
+    # rows and columns and the width to use for the gutter as the
     # keys :rows, :columns, :gutter, :row_gutter, :column_gutter
     #
+    # Note that a completely new grid object is built each time define_grid()
+    # is called. This means that all subsequent calls to grid() will use
+    # the newly defined Grid object -- grids are not nestable like 
+    # bounding boxes are.
+
     def define_grid(options = {})
+      @boxes = nil
       @grid = Grid.new(self, options)
     end
-  
-    # A method that can either be used to access a particular grid on the page 
+
+    # A method that can either be used to access a particular grid on the page
     # or work with the grid system directly.
     #
     #   @pdf.grid                 # Get the Grid directly
@@ -22,7 +29,7 @@ module Prawn
         @grid
       else
         g1, g2 = args
-        if(g1.class == Array && g2.class == Array && 
+        if(g1.class == Array && g2.class == Array &&
           g1.length == 2 && g2.length == 2)
           multi_box(single_box(*g1), single_box(*g2))
         else
@@ -30,15 +37,17 @@ module Prawn
         end
       end
     end
-  
-    # A Grid represents the entire grid system of a Page and calculates 
+
+    # A Grid represents the entire grid system of a Page and calculates
     # the column width and row height of the base box.
+    #
+    # @private
     class Grid
       attr_reader :pdf, :columns, :rows, :gutter, :row_gutter, :column_gutter
       def initialize(pdf, options = {}) # :nodoc:
         valid_options = [:columns, :rows, :gutter, :row_gutter, :column_gutter]
         Prawn.verify_options valid_options, options
-      
+
         @pdf = pdf
         @columns = options[:columns]
         @rows = options[:rows]
@@ -49,7 +58,7 @@ module Prawn
       def column_width
         @column_width ||= subdivide(pdf.bounds.width, columns, column_gutter)
       end
-    
+
       # Calculates the base height of boxes.
       def row_height
        @row_height ||= subdivide(pdf.bounds.height, rows, row_gutter)
@@ -65,11 +74,11 @@ module Prawn
       end
 
       private
-      
+
       def subdivide(total, num, gutter)
         (total.to_f - (gutter * (num - 1).to_f)) / num.to_f
       end
-      
+
       def set_gutter(options)
         if options.has_key?(:gutter)
           @gutter = options[:gutter].to_f
@@ -81,92 +90,93 @@ module Prawn
         end
       end
     end
-  
-    # A Box is a class that represents a bounded area of a page.  
-    # A Grid object has methods that allow easy access to the coordinates of 
+
+    # A Box is a class that represents a bounded area of a page.
+    # A Grid object has methods that allow easy access to the coordinates of
     # its corners, which can be plugged into most existing prawnmethods.
     #
-    class Box #:nodoc:
+    # @private
+    class GridBox
       attr_reader :pdf
-    
+
       def initialize(pdf, i, j)
         @pdf = pdf
         @i = i
         @j = j
       end
-    
-      # Mostly diagnostic method that outputs the name of a box as 
+
+      # Mostly diagnostic method that outputs the name of a box as
       # col_num, row_num
       #
       def name
         "#{@i.to_s},#{@j.to_s}"
       end
-      
+
       # :nodoc
       def total_height
         pdf.bounds.height.to_f
       end
-      
+
       # Width of a box
       def width
         grid.column_width.to_f
       end
-    
+
       # Height of a box
       def height
         grid.row_height.to_f
       end
-      
+
       # Width of the gutter
       def gutter
         grid.gutter.to_f
       end
-      
+
       # x-coordinate of left side
       def left
         @left ||= (width + grid.column_gutter) * @j.to_f
       end
-    
-      # x-coordinate of right side 
+
+      # x-coordinate of right side
       def right
         @right ||= left + width
       end
-    
+
       # y-coordinate of the top
       def top
         @top ||= total_height - ((height + grid.row_gutter) * @i.to_f)
       end
-    
+
       # y-coordinate of the bottom
       def bottom
         @bottom ||= top - height
       end
-    
+
       # x,y coordinates of top left corner
       def top_left
         [left, top]
       end
-    
-      # x,y coordinates of top right corner    
+
+      # x,y coordinates of top right corner
       def top_right
         [right, top]
       end
-    
+
       # x,y coordinates of bottom left corner
       def bottom_left
         [left, bottom]
       end
-    
+
       # x,y coordinates of bottom right corner
       def bottom_right
         [right, bottom]
       end
-    
+
       # Creates a standard bounding box based on the grid box.
       def bounding_box(&blk)
         pdf.bounding_box(top_left, :width => width, :height => height, &blk)
       end
-    
+
       # Diagnostic method
       def show(grid_color = "CCCCCC")
         self.bounding_box do
@@ -175,28 +185,30 @@ module Prawn
           pdf.stroke_color = grid_color
           pdf.text self.name
           pdf.stroke_bounds
-          
+
           pdf.stroke_color = original_stroke_color
         end
       end
-    
+
       private
       def grid
         pdf.grid
       end
     end
-  
+
     # A MultiBox is specified by 2 Boxes and spans the areas between.
-    class MultiBox < Box #:nodoc:
+    #
+    # @private
+    class MultiBox < GridBox #:nodoc:
       def initialize(pdf, b1, b2)
         @pdf = pdf
         @bs = [b1, b2]
       end
-    
+
       def name
         @bs.map {|b| b.name}.join(":")
       end
-    
+
       def total_height
         @bs[0].total_height
       end
@@ -204,54 +216,54 @@ module Prawn
       def width
         right_box.right - left_box.left
       end
-    
+
       def height
         top_box.top - bottom_box.bottom
       end
-    
+
       def gutter
         @bs[0].gutter
       end
-    
+
       def left
         left_box.left
       end
-    
+
       def right
         right_box.right
       end
-    
+
       def top
         top_box.top
       end
-    
+
       def bottom
         bottom_box.bottom
       end
-    
+
       private
       def left_box
         @left_box ||= @bs.min {|a,b| a.left <=> b.left}
       end
-    
+
       def right_box
         @right_box ||= @bs.max {|a,b| a.right <=> b.right}
       end
-    
+
       def top_box
         @top_box ||= @bs.max {|a,b| a.top <=> b.top}
       end
-    
+
       def bottom_box
         @bottom_box ||= @bs.min {|a,b| a.bottom <=> b.bottom}
       end
     end
-  
+
     private
     def single_box(i, j)
-      Box.new(self, i, j)
+      GridBox.new(self, i, j)
     end
-  
+
     def multi_box(b1, b2)
       MultiBox.new(self, b1, b2)
     end

data/lib/prawn/layout.rb

@@ -1,20 +1,15 @@
-require "prawn/table"
-require 'prawn/layout/grid'
+require_relative "table"
+require_relative "layout/grid"
 
 module Prawn
-  
- module Errors
-   
-   # This error is raised when table data is malformed
-   #
-   InvalidTableData = Class.new(StandardError)
+  module Errors
 
-   # This error is raised when an empty or nil table is rendered
-   #
-   EmptyTable = Class.new(StandardError)
- end
+    # This error is raised when table data is malformed
+    #
+    InvalidTableData = Class.new(StandardError)
 
- module Layout
-
- end
+    # This error is raised when an empty or nil table is rendered
+    #
+    EmptyTable = Class.new(StandardError)
+  end
 end

data/lib/prawn/measurement_extensions.rb

@@ -5,13 +5,17 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
-require 'prawn/measurements'
+require_relative 'measurements'
+
+# @group Stable API
 
 class Numeric
-  include Prawn::Measurements        
-  # prawns' basic unit is PostScript-Point        
+  include Prawn::Measurements
+  # prawns' basic unit is PostScript-Point
   # 72 points per inch
 
+  # @group Experimental API
+  
   def mm
     return mm2pt(self)
   end
@@ -39,8 +43,8 @@ class Numeric
   def ft
     return ft2pt(self)
   end
-  
+
   def pt
-    return self
+    return pt2pt(self)
   end
-end        
+end

data/lib/prawn/measurements.rb

@@ -3,69 +3,75 @@
 #
 # Copyright December 2008, Florian Witteler.  All Rights Reserved.
 #
-module Prawn  
+module Prawn
+  # @group Stable API
+
   module Measurements
-  
+
     # ============================================================================
     #metric conversions
     def cm2mm(cm)
       return cm*10
     end
-  
+
     def dm2mm(dm)
-      return dm*100  
+      return dm*100
     end
-  
+
     def m2mm(m)
       return m*1000
     end
-  
+
     # ============================================================================
-    # imperial conversions    
+    # imperial conversions
     # from http://en.wikipedia.org/wiki/Imperial_units
-  
+
     def ft2in(ft)
       return ft * 12
-    end  
+    end
 
     def yd2in(yd)
       return yd*36
     end
 
-  
+
     # ============================================================================
     # PostscriptPoint-converisons
-  
+
+    def pt2pt(pt)
+      return pt
+    end
+
     def in2pt(inch)
-      return inch * 72    
+      return inch * 72
     end
-  
+
     def ft2pt(ft)
       return in2pt(ft2in(ft))
     end
-  
+
     def yd2pt(yd)
       return in2pt(yd2in(yd))
     end
-  
+
     def mm2pt(mm)
         return mm*(72 / 25.4)
     end
-  
+
     def cm2pt(cm)
       return mm2pt(cm2mm(cm))
     end
-  
+
     def dm2pt(dm)
       return mm2pt(dm2mm(dm))
     end
-  
+
     def m2pt(m)
       return mm2pt(m2mm(m))
     end
-  
-    def pt2mm(pt)    
+
+    def pt2mm(pt)
       return pt * 1 / mm2pt(1)# (25.4 / 72)
     end
   end
-end
+end