prawn 0.1.0

data/lib/prawn/document/bounding_box.rb

@@ -0,0 +1,253 @@
+# encoding: utf-8
+
+module Prawn
+  class Document
+    
+    # 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, for the purposes
+    # of simplifying coordinate math.
+    #
+    # When flowing text, the usage of a bounding box is simple. Text will
+    # begin at the point specified, flowing the width of the bounding box.
+    # After the block exits, the text drawing position will be moved to
+    # the bottom of the bounding box (y - height). Currently, Prawn allows
+    # text to overflow the bottom border of the bounding box, so it is up to
+    # the user to ensure the text provided will fit within the height of the
+    # bounding box.
+    #
+    # pdf.bounding_box([100,500], :width => 100, :height => 300) do
+    # pdf.text "This text will flow in a very narrow box starting" +
+    # "from [100,500]. The pointer will then be moved to [100,200]" +
+    # "and return to the margin_box"
+    # end
+    #
+    # 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
+    # to match this new region.
+    #
+    # Take for example two triangles which share one point, drawn from the
+    # origin:
+    #
+    #   pdf.polygon [0,250], [0,0], [150,100]
+    #   pdf.polygon [100,0], [150,100], [200,0]
+    #
+    # It would be easy enough to translate these triangles to another point,
+    # e.g [200,200]
+    #
+    #   pdf.polygon [200,450], [200,200], [350,300]
+    #   pdf.polygon [300,200], [350,300], [400,200]
+    #
+    # However, each time you want to move the drawing, you'd need to alter
+    # every point in the drawing calls, which as you might imagine, can become
+    # tedious.
+    #
+    # If instead, we think of the drawing as being bounded by a box, we can
+    # see that the image is 200 points wide by 250 points tall.
+    #
+    # To translate it to a new origin, we simply select a point at (x,y+height)
+    #
+    # Using the [200,200] example:
+    #
+    #   pdf.bounding_box([200,450], :width => 200, :height => 250) do
+    #     pdf.polygon [0,250], [0,0], [150,100]
+    #     pdf.polygon [100,0], [150,100], [200,0]
+    #   end
+    #
+    # Notice that the drawing is still relative to the origin. If we want to
+    # 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.
+    # 
+    # By default, 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
+    #
+    # pdf.bouding_box([200,450], :width => 200, :height => 250) do
+    #   pdf.bounding_box([50,200], :width => 50, :height => 50) do
+    #     # a 50x50 bounding box that starts 50 pixels left and 50 pixels down 
+    #     # the parent bounding box.
+    #   end
+    # end
+    #
+    # 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()
+    #
+    #   pdf.canvas do
+    #     pdf.bounding_box([200,450], :width => 200, :height => 250) do
+    #       # positioned at 'real' (200,450)
+    #     end
+    #   end
+    #
+    # 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 |parent_box|
+        # Offset to relative positions
+        top_left = args[0]
+        top_left[0] += parent_box.absolute_left
+        top_left[1] += parent_box.absolute_bottom
+
+        @bounding_box = BoundingBox.new(self, *args)   
+      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.
+    #
+    #   pdf.canvas do
+    #     pdf.line pdf.bounds.bottom_left, pdf.bounds.top_right
+    #   end
+    #
+    def canvas(&block)     
+      init_bounding_box(block) do |_|
+        @bounding_box = BoundingBox.new(self, [0,page_dimensions[3]], 
+          :width => page_dimensions[2], 
+          :height => page_dimensions[3] 
+        ) 
+      end
+    end      
+    
+    private
+    
+    def init_bounding_box(user_block, &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 
+
+      @bounding_box = parent_box 
+    end
+       
+    class BoundingBox
+      
+      def initialize(parent, point, options={}) #:nodoc:
+        @parent = parent
+        @x, @y = point
+        @width, @height = options[:width], options[:height]
+      end
+       
+      # 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)
+      #
+      def left
+        0
+      end
+      
+      # Relative right x-coordinate of the bounding box. (Equal to the box width)
+      #
+      def right
+        @width
+      end
+      
+      # Relative top y-coordinate of the bounding box. (Equal to the box height)
+      #
+      def top
+        height
+      end
+      
+      # Relative bottom y-coordinate of the bounding box (Always 0)
+      #
+      def bottom
+        0
+      end
+
+      # Relative top-left point of the bounding_box
+      #
+      def top_left
+        [left,top]
+      end
+
+      # Relative top-right point of the bounding box
+      #
+      def top_right
+        [right,top]
+      end
+
+      # Relative bottom-right point of the bounding box
+      #
+      def bottom_right
+        [right,bottom]
+      end
+
+      # Relative bottom-left point of the bounding box
+      #
+      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
+        @y - height
+      end
+
+      # Absolute top-left point of the bounding box
+      #
+      def absolute_top_left
+        [absolute_left, absolute_top]
+      end
+
+      # Absolute top-right point of the bounding box
+      #
+      def absolute_top_right
+        [absolute_right, absolute_top]
+      end
+
+      # Absolute bottom-left point of the bounding box
+      #
+      def absolute_bottom_left
+        [absolute_left, absolute_bottom]
+      end
+
+      # Absolute bottom-left point of the bounding box
+      #
+      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
+        @height || absolute_top - @parent.y
+      end
+    end
+  end
+end

data/lib/prawn/document/page_geometry.rb

@@ -0,0 +1,78 @@
+# encoding: utf-8
+
+# page_geometry.rb : Describes PDF page geometries
+#
+# Copyright April 2008, Gregory Brown.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Document
+    module PageGeometry
+          
+      # Dimensions pulled from PDF::Writer, rubyforge.org/projects/ruby-pdf
+      SIZES = { "4A0" => [4767.87, 6740.79], 
+                "2A0" => [3370.39, 4767.87], 
+                 "A0" => [2383.94, 3370.39], 
+                 "A1" => [1683.78, 2383.94], 
+                 "A2" => [1190.55, 1683.78], 
+                 "A3" => [841.89, 1190.55], 
+                 "A4" => [595.28, 841.89], 
+                 "A5" => [419.53, 595.28], 
+                 "A6" => [297.64, 419.53], 
+                 "A7" => [209.76, 297.64], 
+                 "A8" => [147.40, 209.76], 
+                 "A9" => [104.88, 147.40], 
+                "A10" => [73.70, 104.88], 
+                 "B0" => [2834.65, 4008.19], 
+                 "B1" => [2004.09, 2834.65], 
+                 "B2" => [1417.32, 2004.09], 
+                 "B3" => [1000.63, 1417.32], 
+                 "B4" => [708.66, 1000.63], 
+                 "B5" => [498.90, 708.66], 
+                 "B6" => [354.33, 498.90], 
+                 "B7" => [249.45, 354.33], 
+                 "B8" => [175.75, 249.45], 
+                 "B9" => [124.72, 175.75], 
+                "B10" => [87.87, 124.72], 
+                 "C0" => [2599.37, 3676.54], 
+                 "C1" => [1836.85, 2599.37], 
+                 "C2" => [1298.27, 1836.85], 
+                 "C3" => [918.43, 1298.27], 
+                 "C4" => [649.13, 918.43], 
+                 "C5" => [459.21, 649.13], 
+                 "C6" => [323.15, 459.21], 
+                 "C7" => [229.61, 323.15], 
+                 "C8" => [161.57, 229.61], 
+                 "C9" => [113.39, 161.57], 
+                "C10" => [79.37, 113.39], 
+                "RA0" => [2437.80, 3458.27], 
+                "RA1" => [1729.13, 2437.80], 
+                "RA2" => [1218.90, 1729.13], 
+                "RA3" => [864.57, 1218.90], 
+                "RA4" => [609.45, 864.57], 
+               "SRA0" => [2551.18, 3628.35], 
+               "SRA1" => [1814.17, 2551.18], 
+               "SRA2" => [1275.59, 1814.17], 
+               "SRA3" => [907.09, 1275.59], 
+               "SRA4" => [637.80, 907.09], 
+             "LETTER" => [612.00, 792.00], 
+              "LEGAL" => [612.00, 1008.00], 
+              "FOLIO" => [612.00, 936.00], 
+          "EXECUTIVE" => [521.86, 756.00] }
+     
+      def page_dimensions #:nodoc:
+        coords = SIZES[page_size] || page_size
+        [0,0] + case(page_layout)   
+        when :portrait
+          coords
+        when :landscape
+          coords.reverse 
+        else 
+          raise Prawn::Errors::InvalidPageLayout, 
+            "Layout must be either :portrait or :landscape"
+        end
+      end 
+    end     
+  end
+end

data/lib/prawn/document/table.rb

@@ -0,0 +1,253 @@
+# encoding: utf-8
+
+module Prawn
+  class Document
+
+    # Builds and renders a Document::Table object from raw data.
+    # For details on the options that can be passed, see
+    # Document::Table.new
+    #
+    #   data = [["Gregory","Brown"],["James","Healy"],["Jia","Wu"]]
+    #
+    #   Prawn::Document.generate("table.pdf") do
+    #     
+    #     # Default table, without headers
+    #     table(data)
+    #
+    #     # Default table with headers
+    #     table data, :headers => ["First Name", "Last Name"]
+    #
+    #     # Very close to PDF::Writer's default SimpleTable output
+    #     table data, :headers            => ["First Name", "Last Name"],
+    #                 :font_size          => 10,
+    #                 :vertical_padding   => 2,
+    #                 :horizontal_padding => 5,
+    #                 :position           => :center,
+    #                 :row_colors         => :pdf_writer,
+    #
+    #     # Grid border style with explicit column widths.
+    #     table data, :border_style => :grid,
+    #                 :widths       => { 0 => 100, 1 => 150 }
+    #
+    #   end
+    #
+    def table(data,options={})
+      Prawn::Document::Table.new(data,self,options).draw
+    end
+
+    # This class implements simple PDF table generation.
+    # 
+    # Prawn tables have the following features:
+    #
+    #   * Can be generated with or without headers
+    #   * Can tweak horizontal and vertical padding of text
+    #   * Minimal styling support (borders / row background colors)
+    #   * Can be positioned by bounding boxes (left/center aligned) or an
+    #     absolute x position
+    #   * Automated page-breaking as needed
+    #   * Column widths can be calculated automatically or defined explictly on a 
+    #     column by column basis
+    #
+    # The current implementation is a bit barebones, but covers most of the
+    # basic needs for PDF table generation.  If you have feature requests,
+    # please share them at: http://groups.google.com/group/prawn-ruby
+    #
+    # Tables will be revisited before the end of the Ruby Mendicant project and
+    # the most commonly needed functionality will likely be added.
+    # 
+    class Table
+
+      attr_reader :col_widths # :nodoc:
+
+      # Creates a new Document::Table object. This is generally called 
+      # indirectly through Document#table but can also be used explictly.
+      #
+      # The <tt>data</tt> argument is a two dimensional array of strings,
+      # organized by row, e.g. [["r1-col1","r1-col2"],["r2-col2","r2-col2"]].
+      # As with all Prawn text drawing operations, strings must be UTF-8 encoded.
+      #
+      # The following options are available for customizing your tables, with
+      # defaults shown in [] at the end of each description.
+      #
+      # <tt>:font_size</tt>:: The font size for the text cells . [12]
+      # <tt>:horizontal_padding</tt>:: The horizontal cell padding in PDF points [5]
+      # <tt>:vertical_padding</tt>:: The vertical cell padding in PDF points [5]
+      # <tt>:padding</tt>:: Horizontal and vertical cell padding (overrides both)
+      # <tt>:border</tt>:: With of border lines in PDF points [1]
+      # <tt>:border_style</tt>:: If set to :grid, fills in all borders.  Otherwise, borders are drawn on columns only, not rows
+      # <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
+      # <tt>:widths:</tt> A hash of indices and widths in PDF points.  E.g. <tt>{ 0 => 50, 1 => 100 }</tt>
+      # <tt>:row_colors</tt>:: An array of row background colors which are used cyclicly.   
+      # <tt>:align</tt>:: Alignment of text in columns [:left]
+      #
+      # Row colors are specified as html encoded values, e.g.
+      # ["ffffff","aaaaaa","ccaaff"].  You can also specify 
+      # <tt>:row_colors => :pdf_writer</tt> if you wish to use the default color
+      # scheme from the PDF::Writer library.
+      #
+      # See Document#table for typical usage, as directly using this class is
+      # not recommended unless you know why you want to do it.
+      #
+      def initialize(data, document,options={})
+        @data                = data
+        @document            = document
+        @font_size           = options[:font_size] || 12
+        @border_style        = options[:border_style]
+        @border              = options[:border]    || 1
+        @position            = options[:position]  || :left
+        @headers             = options[:headers]
+        @row_colors          = options[:row_colors]   
+        @align               = options[:align]
+
+        @horizontal_padding  = options[:horizontal_padding] || 5
+        @vertical_padding    = options[:vertical_padding]   || 5
+
+        if options[:padding]
+          @horizontal_padding = @vertical_padding = options[:padding]
+        end
+
+        
+        @row_colors = ["ffffff","cccccc"] if @row_colors == :pdf_writer
+
+        @original_row_colors = @row_colors.dup if @row_colors  
+        
+        calculate_column_widths(options[:widths])
+      end
+      
+      # Width of the table in PDF points
+      #
+      def width
+         @col_widths.inject(0) { |s,r| s + r }
+      end
+      
+      # Draws the table onto the PDF document
+      #
+      def draw
+        case(@position) 
+        when :center
+          x = (@document.bounds.width - width) / 2.0
+          y = @document.y - @document.bounds.absolute_bottom
+          @document.bounding_box [x, y], :width => width do
+            generate_table
+          end
+        when Numeric     
+          x = @position
+          y = @document.y - @document.bounds.absolute_bottom
+          @document.bounding_box [x,y], :width => width do
+            generate_table
+          end
+        else
+          generate_table
+        end
+      end
+
+      private
+
+      def calculate_column_widths(manual_widths=nil)
+        @col_widths = [0] * @data[0].length    
+        renderable_data.each do |row|
+          row.each_with_index do |cell,i|
+            length = cell.to_s.lines.map { |e| 
+              @document.font_metrics.string_width(e,@font_size) }.max.to_f +
+                2*@horizontal_padding
+            @col_widths[i] = length if length > @col_widths[i]
+          end
+        end  
+        
+        # TODO: Could optimize here
+        manual_widths.each { |k,v| @col_widths[k] = v } if manual_widths           
+      end
+
+      def renderable_data
+        if @headers
+          [@headers] + @data
+        else
+          @data
+        end
+      end
+
+      def generate_table
+        page_contents = []
+        y_pos = @document.y
+
+        @document.font_size(@font_size) do
+          renderable_data.each_with_index do |row,index|
+            c = Prawn::Graphics::CellBlock.new(@document)
+            row.each_with_index do |e,i| 
+              case(e)
+              when Prawn::Graphics::Cell
+                e.document = @document
+                e.width    = @col_widths[i]
+                e.horizontal_padding = @horizontal_padding
+                e.vertical_padding   = @vertical_padding    
+                e.border             = @border
+                e.border_style       = :sides
+                e.align              = @align
+                c << e
+              else
+                c << Prawn::Graphics::Cell.new(
+                  :document => @document, 
+                  :text     => e.to_s, 
+                  :width    => @col_widths[i],
+                  :horizontal_padding => @horizontal_padding,
+                  :vertical_padding => @vertical_padding,
+                  :border   => @border,
+                  :border_style => :sides,
+                  :align    => @align ) 
+              end   
+            end
+
+            if c.height > y_pos - @document.margin_box.absolute_bottom
+              draw_page(page_contents)
+              @document.start_new_page
+              if @headers
+                page_contents = [page_contents[0]]
+                y_pos = @document.y - page_contents[0].height
+              else
+                page_contents = []
+                y_pos = @document.y
+              end
+            end
+
+            page_contents << c
+
+            y_pos -= c.height
+
+            if index == renderable_data.length - 1
+              draw_page(page_contents)
+            end
+
+          end
+          @document.y -= @vertical_padding
+        end
+      end
+
+      def draw_page(contents)
+        return if contents.empty?
+
+        if @border_style == :grid || contents.length == 1
+          contents.each { |e| e.border_style = :all }
+        else
+          contents.first.border_style = @headers ? :all : :no_bottom
+          contents.last.border_style  = :no_top
+        end
+
+        contents.each do |x| 
+          x.background_color = next_row_color if @row_colors
+          x.draw 
+        end
+
+        reset_row_colors
+      end
+
+      def next_row_color
+        @row_colors.unshift(@row_colors.pop).last
+      end
+
+      def reset_row_colors
+        @row_colors = @original_row_colors.dup if @row_colors
+      end
+
+    end
+  end
+end