prawn 0.2.3 → 0.3.0

data/lib/prawn/document/annotations.rb

@@ -0,0 +1,63 @@
+# encoding: utf-8
+
+# annotations.rb : Implements low-level annotation support for PDF
+#
+# Copyright November 2008, Jamis Buck. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'prawn/literal_string'
+
+module Prawn
+  class Document
+    
+    # Provides very low-level support for annotations.  Those who are 
+    # interested should check out the text-format branch of sandal/prawn, 
+    # which includes much higher level interfaces to this code currently
+    # being developed by Jamis Buck to be included in a Prawn release soon.
+    #
+    # Feedback is welcome!
+    #
+    module Annotations
+      # Adds a new annotation (section 8.4 in PDF spec) to the current page.
+      # +options+ must be a Hash describing the annotation.
+      def annotate(options)
+        @current_page.data[:Annots] ||= []
+        options = sanitize_annotation_hash(options)
+        @current_page.data[:Annots] << ref(options)
+        return options
+      end
+
+      # A convenience method for creating Text annotations. +rect+ must be an array
+      # of four numbers, describing the bounds of the annotation. +contents+ should
+      # be a string, to be shown when the annotation is activated.
+      def text_annotation(rect, contents, options={})
+        options = options.merge(:Subtype => :Text, :Rect => rect, :Contents => contents)
+        annotate(options)
+      end
+
+      # A convenience method for creating Link annotations. +rect+ must be an array
+      # of four numbers, describing the bounds of the annotation. The +options+ hash
+      # should include either :Dest (describing the target destination, usually as a
+      # string that has been recorded in the document's Dests tree), or :A (describing
+      # an action to perform on clicking the link), or :PA (for describing a URL to
+      # link to).
+      def link_annotation(rect, options={})
+        options = options.merge(:Subtype => :Link, :Rect => rect)
+        annotate(options)
+      end
+
+      private
+
+        def sanitize_annotation_hash(options)
+          options = options.merge(:Type => :Annot)
+
+          if options[:Dest].is_a?(String)
+            options[:Dest] = Prawn::LiteralString.new(options[:Dest])
+          end
+
+          options
+        end
+    end
+  end
+end

data/lib/prawn/document/bounding_box.rb

@@ -1,5 +1,11 @@
 # encoding: utf-8
 
+# bounding_box.rb : Implements a mechanism for shifting the coordinate space
+#
+# Copyright May 2008, Gregory Brown. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
 module Prawn
   class Document
     
@@ -10,7 +16,7 @@ module Prawn
     #
     # 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
+    # After the block exits, the cursor position will be moved to
     # the bottom of the bounding box (y - height). If flowing text exceeds
     # the height of the bounding box, the text will be continued on the next
     # page, starting again at the top-left corner of the bounding box.
@@ -135,12 +141,21 @@ module Prawn
         ) 
       end
     end  
+    
+    # A bounding box with the same dimensions of its parents, minus a margin
+    # on all sides
+    #
+    def padded_box(margin, &block)
+      bounding_box [bounds.left + margin, bounds.top - margin],
+        :width  => bounds.width - (margin * 2), 
+        :height => bounds.height - (margin * 2), &block 
+    end
        
     # A header is a LazyBoundingBox drawn relative to the margins that can be
     # repeated on every page of the document.
     #
     # Unless <tt>:width</tt> or <tt>:height</tt> are specified, the margin_box
-    # width and height   
+    # width and height are used.   
     #
     #   header margin_box.top_left do 
     #    text "Here's My Fancy Header", :size => 25, :align => :center   
@@ -155,7 +170,7 @@ module Prawn
     # repeated on every page of the document.
     #
     # Unless <tt>:width</tt> or <tt>:height</tt> are specified, the margin_box
-    # width and height
+    # width and height are used.
     #
     #   footer [margin_box.left, margin_box.bottom + 25] do
     #     stroke_horizontal_rule

data/lib/prawn/document/destinations.rb

@@ -0,0 +1,81 @@
+# encoding: utf-8
+
+# annotations.rb : Implements destination support for PDF
+#
+# Copyright November 2008, Jamis Buck. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+require 'prawn/name_tree'
+
+module Prawn
+  class Document
+    module Destinations
+      # The maximum number of children to fit into a single node in the Dests tree.
+      NAME_TREE_CHILDREN_LIMIT = 20 #:nodoc:
+      
+      # The Dests name tree in the Name dictionary (see Prawn::Document::Internal#names).
+      # This name tree is used to store named destinations (PDF spec 8.2.1).
+      # (For more on name trees, see section 3.8.4 in the PDF spec.)
+      def dests
+        names.data[:Dests] ||= ref(Prawn::NameTree::Node.new(self, NAME_TREE_CHILDREN_LIMIT))
+      end
+
+      # Adds a new destination to the dests name tree (see #dests). The
+      # +reference+ parameter will be converted into a Prawn::Reference if
+      # it is not already one.
+      def add_dest(name, reference)
+        reference = ref(reference) unless reference.is_a?(Prawn::Reference)
+        dests.data.add(name, reference)
+      end
+
+      # Return a Dest specification for a specific location (and optional zoom
+      # level).
+      def dest_xyz(left, top, zoom=nil, page=@current_page)
+        [page, :XYZ, left, top, zoom]
+      end
+
+      # Return a Dest specification that will fit the given page into the
+      # viewport.
+      def dest_fit(page=@current_page)
+        [page, :Fit]
+      end
+
+      # Return a Dest specification that will fit the given page horizontally
+      # into the viewport, aligned vertically at the given top coordinate.
+      def dest_fit_horizontally(top, page=@current_page)
+        [page, :FitH, top]
+      end
+
+      # Return a Dest specification that will fit the given page vertically
+      # into the viewport, aligned horizontally at the given left coordinate.
+      def dest_fit_vertically(left, page=@current_page)
+        [page, :FitV, left]
+      end
+
+      # Return a Dest specification that will fit the given rectangle into the
+      # viewport, for the given page.
+      def dest_fit_rect(left, bottom, right, top, page=@current_page)
+        [page, :FitR, left, bottom, right, top]
+      end
+
+      # Return a Dest specfication that will fit the given page's bounding box
+      # into the viewport.
+      def dest_fit_bounds(page=@current_page)
+        [page, :FitB]
+      end
+
+      # Same as #dest_fit_horizontally, but works on the page's bounding box
+      # instead of the entire page.
+      def dest_fit_bounds_horizontally(top, page=@current_page)
+        [page, :FitBH, top]
+      end
+
+      # Same as #dest_fit_vertically, but works on the page's bounding box
+      # instead of the entire page.
+      def dest_fit_bounds_vertically(left, page=@current_page)
+        [page, :FitBV, left]
+      end
+    end
+  end
+end

data/lib/prawn/document/internals.rb

@@ -1,3 +1,11 @@
+# encoding: utf-8
+#
+# internals.rb : Implements document internals for Prawn
+#
+# Copyright August 2008, Gregory Brown. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
 module Prawn
   class Document     
     
@@ -7,7 +15,6 @@ module Prawn
     # are you won't need anything you find here.  
     #
     module Internals    
-      
       # Creates a new Prawn::Reference and adds it to the Document's object
       # list.  The +data+ argument is anything that Prawn::PdfObject() can convert.    
       def ref(data)
@@ -50,6 +57,13 @@ module Prawn
         page_resources[:XObject] ||= {}
       end  
       
+      # The Name dictionary (PDF spec 3.6.3) for this document. It is
+      # lazily initialized, so that documents that do not need a name
+      # dictionary do not incur the additional overhead.
+      def names
+        @root.data[:Names] ||= ref(:Type => :Names)
+      end
+
       private      
       
       def finish_page_content     
@@ -104,4 +118,4 @@ module Prawn
                  
     end
   end
-end
+end

data/lib/prawn/document/page_geometry.rb

@@ -9,70 +9,71 @@
 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] }
-     
+      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],
+          "EXECUTIVE" => [521.86, 756.00],
+              "FOLIO" => [612.00, 936.00],
+              "LEGAL" => [612.00, 1008.00],
+             "LETTER" => [612.00, 792.00],
+            "TABLOID" => [792.00, 1224.00] }
+
       def page_dimensions #:nodoc:
         coords = SIZES[page_size] || page_size
-        [0,0] + case(page_layout)   
+        [0,0] + case(page_layout)
         when :portrait
           coords
         when :landscape
-          coords.reverse 
-        else 
-          raise Prawn::Errors::InvalidPageLayout, 
+          coords.reverse
+        else
+          raise Prawn::Errors::InvalidPageLayout,
             "Layout must be either :portrait or :landscape"
         end
-      end 
-    end     
+      end
+    end
   end
 end

data/lib/prawn/document/span.rb

@@ -1,3 +1,11 @@
+# encoding: utf-8
+
+# span.rb : Implements text columns
+#
+# Copyright September 2008, Gregory Brown. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
 module Prawn
   class Document
     # A span is a special purpose bounding box that allows a column of 

data/lib/prawn/document/table.rb

@@ -37,7 +37,14 @@ module Prawn
     #
     #   end
     #
+    #   Will raise <tt>Prawn::Errors::EmptyTable</tt> given 
+    #   a nil or empty <tt>data</tt> paramater.
+    #
     def table(data,options={})           
+      if data.nil? || data.empty?
+        raise Prawn::Errors::EmptyTable,
+          "data must be a non-empty, non-nil, two dimensional array of Prawn::Cells or strings"
+      end
       Prawn::Document::Table.new(data,self,options).draw
     end
 
@@ -80,17 +87,22 @@ module Prawn
       # The following options are available for customizing your tables, with
       # defaults shown in [] at the end of each description.
       #
+      # <tt>:headers</tt>:: An array of table headers, either strings or Cells. [Empty]
+      # <tt>:align_headers</tt>:: Alignment of header text.  Specify for entire header (<tt>:left</tt>) or by column (<tt>{ 0 => :right, 1 => :left}</tt>). If omitted, the header alignment is the same as the column alignment.
+      # <tt>:header_text_color</tt>:: Sets the text color of the headers
+      # <tt>:header_color</tt>:: Manually sets the header color
       # <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_width</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>:border_style</tt>:: If set to :grid, fills in all borders. If set to :underline_header, underline header only. Otherwise, borders are drawn on columns only, not rows
+      # <tt>:border_color</tt>:: Sets the color of the borders.
       # <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, for entire table (<tt>:center</tt>) or by column (<tt>{ 0 => :left, 1 => :center}</tt>)
-      # <tt>:align_headers</tt>:: Alignment of header text.
+      # <tt>:minimum_rows</tt>:: The minimum rows to display on a page, including header.
       #
       # Row colors are specified as html encoded values, e.g.
       # ["ffffff","aaaaaa","ccaaff"].  You can also specify 
@@ -110,8 +122,9 @@ module Prawn
         @document = document
         
         Prawn.verify_options [:font_size,:border_style, :border_width,
-         :position, :headers, :row_colors, :align, :align_headers, 
-         :horizontal_padding, :vertical_padding, :padding, :widths ], options     
+         :position, :headers, :row_colors, :align, :align_headers, :header_text_color, :border_color,
+         :horizontal_padding, :vertical_padding, :padding, :widths, 
+         :header_color ], options     
                                             
         configuration.update(options)  
 
@@ -193,10 +206,12 @@ module Prawn
         @document.font.size C(:font_size) do
           renderable_data.each_with_index do |row,index|
             c = Prawn::Graphics::CellBlock.new(@document)
-            row.each_with_index do |e,i|     
+            
+            col_index = 0
+            row.each do |e|
               case C(:align)
               when Hash
-                align            = C(:align)[i]
+                align            = C(:align)[col_index]
               else
                 align            = C(:align)
               end   
@@ -207,7 +222,7 @@ module Prawn
               case e
               when Prawn::Graphics::Cell
                 e.document = @document
-                e.width    = @col_widths[i]
+                e.width    = @col_widths[col_index]
                 e.horizontal_padding = C(:horizontal_padding)
                 e.vertical_padding   = C(:vertical_padding)    
                 e.border_width       = C(:border_width)
@@ -215,28 +230,42 @@ module Prawn
                 e.align              = align 
                 c << e
               else
+                text = e.is_a?(Hash) ? e[:text] : e.to_s
+                width = if e.is_a?(Hash) && e.has_key?(:colspan)
+                  @col_widths.slice(col_index, e[:colspan]).inject { |sum, width| sum + width }
+                else
+                  @col_widths[col_index]
+                end
+                
                 c << Prawn::Graphics::Cell.new(
                   :document => @document, 
-                  :text     => e.to_s, 
-                  :width    => @col_widths[i],
+                  :text     => text,
+                  :width    => width,
                   :horizontal_padding => C(:horizontal_padding),
                   :vertical_padding   => C(:vertical_padding),
                   :border_width       => C(:border_width),
                   :border_style       => :sides,
                   :align              => align ) 
-              end   
+              end
+              
+              col_index += (e.is_a?(Hash) && e.has_key?(:colspan)) ? e[:colspan] : 1
             end
                                                 
             bbox = @parent_bounds.stretchy? ? @document.margin_box : @parent_bounds
             if c.height > y_pos - bbox.absolute_bottom
-              draw_page(page_contents)
-              @document.start_new_page
-              if C(:headers)
-                page_contents = [page_contents[0]]
-                y_pos = @document.y - page_contents[0].height
-              else
-                page_contents = []
+              if C(:headers) && page_contents.length == 1
+                @document.start_new_page
                 y_pos = @document.y
+              else
+                draw_page(page_contents)
+                @document.start_new_page
+                if C(:headers) && page_contents.any?
+                  page_contents = [page_contents[0]]
+                  y_pos = @document.y - page_contents[0].height
+                else
+                  page_contents = []
+                  y_pos = @document.y
+                end
               end
             end
 
@@ -254,29 +283,50 @@ module Prawn
 
       def draw_page(contents)
         return if contents.empty?
-
-        if C(:border_style) == :grid || contents.length == 1
+ 
+        if C(:border_style) == :underline_header
+          contents.each { |e| e.border_style = :none }
+          contents.first.border_style = :bottom_only if C(:headers)
+        elsif C(:border_style) == :grid || contents.length == 1
           contents.each { |e| e.border_style = :all }
-        else                            
-          if C(:headers)
-            contents.first.border_style = :all 
-            contents.first.align        = C(:align_headers) || :left
-          else
-            contents.first.border_style  = :no_bottom    
+        else
+          contents.first.border_style = C(:headers) ? :all : :no_bottom
+          contents.last.border_style = :no_top
+        end
+        
+        if C(:headers)
+          contents.first.cells.each_with_index do |e,i|
+            if C(:align_headers)
+              case C(:align_headers)
+                when Hash
+                  align = C(:align_headers)[i]
+                else
+                  align = C(:align_headers)
+                end
+            end
+            e.align = align if align
+            e.text_color = C(:header_text_color) if C(:header_text_color)
+            e.background_color = C(:header_color) if C(:header_color)
           end
-          contents.last.border_style  = :no_top
         end
-
-        contents.each do |x| 
-          x.background_color = next_row_color if C(:row_colors)
+        
+        contents.each do |x|
+          unless x.background_color
+            x.background_color = next_row_color if C(:row_colors)
+          end
+          x.border_color = C(:border_color) if C(:border_color)
+          
           x.draw 
         end
-
+ 
         reset_row_colors
       end
 
+
       def next_row_color
-        C(:row_colors).unshift(C(:row_colors).pop).last
+        color = C(:row_colors).shift
+        C(:row_colors).push(color)
+        color
       end
 
       def reset_row_colors