0
@@ -8,29 +8,101 @@ module Prawn
0
     #   data = [["Gregory","Brown"],["James","Healy"],["Jia","Wu"]]
0
     #
0
     #   Prawn::Document.generate("table.pdf") do
0
+    #     
0
+    #     # Default table, without headers
0
+    #     table(data)
0
+    #
0
+    #     # Default table with headers
0
     #     table data, :headers => ["First Name", "Last Name"]
0
+    #
0
+    #     # Very close to PDF::Writer's default SimpleTable output
0
+    #     table data, :headers            => ["First Name", "Last Name"],
0
+    #                 :font_size          => 10,
0
+    #                 :vertical_padding   => 2,
0
+    #                 :horizontal_padding => 5,
0
+    #                 :position           => :center,
0
+    #                 :row_colors         => :pdf_writer,
0
+    #
0
+    #     # Grid border style with explicit column widths.
0
+    #     table data, :border_style => :grid,
0
+    #                 :widths       => { 0 => 100, 1 => 150 }
0
+    #
0
     #   end
0
     #
0
     def table(data,options={})
0
       Prawn::Document::Table.new(data,self,options).draw
0
     end
0
 
0
+    # This class implements simple PDF table generation.
0
+    # 
0
+    # Prawn tables have the following features:
0
+    #
0
+    #   * Can be generated with or without headers
0
+    #   * Can tweak horizontal and vertical padding of text
0
+    #   * Minimal styling support (borders / row background colors)
0
+    #   * Can be positioned by bounding boxes (left/center aligned) or an
0
+    #     absolute x position
0
+    #   * Automated page-breaking as needed
0
+    #   * Column widths can be calculated automatically or defined explictly on a 
0
+    #     column by column basis
0
+    #
0
+    # The current implementation is a bit barebones, but covers most of the
0
+    # basic needs for PDF table generation.  If you have feature requests,
0
+    # please share them at: http://groups.google.com/group/prawn-ruby
0
+    #
0
+    # Tables will be revisited before the end of the Ruby Mendicant project and
0
+    # the most commonly needed functionality will likely be added.
0
+    # 
0
     class Table
0
 
0
       attr_reader :col_widths # :nodoc:
0
 
0
+      # Creates a new Document::Table object. This is generally called 
0
+      # indirectly through Document#table but can also be used explictly.
0
+      #
0
+      # The <tt>data</tt> argument is a two dimensional array of strings,
0
+      # organized by row, e.g. [["r1-col1","r1-col2"],["r2-col2","r2-col2"]].
0
+      # As with all Prawn text drawing operations, strings must be UTF-8 encoded.
0
+      #
0
+      # The following options are available for customizing your tables, with
0
+      # defaults shown in [] at the end of each description.
0
+      #
0
+      # <tt>:font_size</tt>:: The font size for the text cells . [12]
0
+      # <tt>:horizontal_padding</tt>:: The horizontal cell padding in PDF points [5]
0
+      # <tt>:vertical_padding</tt>:: The vertical cell padding in PDF points [5]
0
+      # <tt>:padding</tt>:: Horizontal and vertical cell padding (overrides both)
0
+      # <tt>:border</tt>:: With of border lines in PDF points [1]
0
+      # <tt>:border_style</tt>:: If set to :grid, fills in all borders.  Otherwise, borders are drawn on columns only, not rows
0
+      # <tt>:position</tt>:: One of <tt>:left</tt>, <tt>:center</tt> or <tt>n</tt>, where <tt>n</tt> is an x-offset from the left edge of the current bounding box
0
+      # <tt>:widths:</tt> A hash of indices and widths in PDF points.  E.g. <tt>{ 0 => 50, 1 => 100 }</tt>
0
+      # <tt>:row_colors</tt>:: An array of row background colors which are used cyclicly.  
0
+      #
0
+      # Row colors are specified as html encoded values, e.g.
0
+      # ["ffffff","aaaaaa","ccaaff"].  You can also specify 
0
+      # <tt>:row_colors => :pdf_writer</tt> if you wish to use the default color
0
+      # scheme from the PDF::Writer library.
0
+      #
0
+      # See Document#table for typical usage, as directly using this class is
0
+      # not recommended unless you know why you want to do it.
0
+      #
0
       def initialize(data, document,options={})
0
         @data                = data
0
         @document            = document
0
         @font_size           = options[:font_size] || 12
0
-        @horizontal_padding  = options[:horizontal_padding] || 5
0
-        @vertical_padding    = options[:vertical_padding]   || 5
0
-        @border              = options[:border]    || 1
0
         @border_style        = options[:border_style]
0
+        @border              = options[:border]    || 1
0
         @position            = options[:position]  || :left
0
         @headers             = options[:headers]
0
         @row_colors          = options[:row_colors]
0
 
0
+        @horizontal_padding  = options[:horizontal_padding] || 5
0
+        @vertical_padding    = options[:vertical_padding]   || 5
0
+
0
+        if options[:padding]
0
+          @horizontal_padding = @vertical_padding = options[:padding]
0
+        end
0
+
0
+        
0
         @row_colors = ["ffffff","cccccc"] if @row_colors == :pdf_writer
0
 
0
         @original_row_colors = @row_colors.dup if @row_colors
0
@@ -40,22 +112,14 @@ module Prawn
0
         end
0
       end
0
       
0
-      def calculate_column_widths
0
-        @col_widths = [0] * @data[0].length
0
-        renderable_data.each do |row|
0
-          row.each_with_index do |cell,i|
0
-            length = cell.lines.map { |e| 
0
-              @document.font_metrics.string_width(e,@font_size) }.max +
0
-                2*@horizontal_padding
0
-            @col_widths[i] = length if length > @col_widths[i]
0
-          end
0
-        end
0
-      end
0
-
0
+      # Width of the table in PDF points
0
+      #
0
       def width
0
          @col_widths.inject(0) { |s,r| s + r }
0
       end
0
-
0
+      
0
+      # Draws the table onto the PDF document
0
+      #
0
       def draw
0
         case(@position) 
0
         when :center
0
@@ -77,6 +141,18 @@ module Prawn
0
 
0
       private
0
 
0
+      def calculate_column_widths
0
+        @col_widths = [0] * @data[0].length
0
+        renderable_data.each do |row|
0
+          row.each_with_index do |cell,i|
0
+            length = cell.lines.map { |e| 
0
+              @document.font_metrics.string_width(e,@font_size) }.max +
0
+                2*@horizontal_padding
0
+            @col_widths[i] = length if length > @col_widths[i]
0
+          end
0
+        end
0
+      end
0
+
0
       def renderable_data
0
         if @headers
0
           [@headers] + @data