jerryvos-prawn-layout 0.2.0.3 → 0.2.0.4

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake/testtask'
 require "rake/rdoctask"
 require "rake/gempackagetask"  
 
-PRAWN_LAYOUT_VERSION = "0.2.0.3"
+PRAWN_LAYOUT_VERSION = "0.2.0.4"
 
 task :default => [:test]
        

data/lib/prawn/layout/grid.rb

@@ -0,0 +1,238 @@
+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 keys :rows, :columns, :gutter
+    #
+    def define_grid(options = {})
+      @grid = Grid.new(self, options)
+    end
+  
+    # A method that can either be used to access a particular grid on the page or interogate the grid 
+    # system directly.
+    #
+    #   @pdf.grid                 # Get the Grid directly
+    #   @pdf.grid([0,1])          # Get the box at [0,1]
+    #   @pdf.grid([0,1], [1,2])   # Get a multi-box spanning from [0,1] to [1,2]
+    def grid(*args)
+      @boxes ||= {}
+      @boxes[args] ||= if args.empty?
+        @grid
+      else
+        g1, g2 = args
+        if(g1.class == Array && g2.class == Array && 
+          g1.length == 2 && g2.length == 2)
+          multi_box(single_box(*g1), single_box(*g2))
+        else
+          single_box(g1, g2)
+        end
+      end
+    end
+  
+    # A Grid represents the entire grid system of a Page and calculates the column width and row height
+    # of the base box.
+    class Grid
+      attr_reader :pdf, :columns, :rows, :gutter
+      # :nodoc
+      def initialize(pdf, options = {})
+        Prawn.verify_options([:columns, :rows, :gutter], options)
+      
+        @pdf = pdf
+        @columns = options[:columns]
+        @rows = options[:rows]
+        @gutter = options[:gutter].to_f
+      end
+
+      # Calculates the base width of boxes.
+      def column_width
+        @column_width ||= subdivide(pdf.bounds.width, columns)
+      end
+    
+      # Calculates the base height of boxes.
+      def row_height
+       @row_height ||= subdivide(pdf.bounds.height, rows)
+      end
+
+      # Diagnostic tool to show all of the grids.  Defaults to gray.
+      def show_all(color = "CCCCCC")
+        self.rows.times do |i|
+          self.columns.times do |j|
+            pdf.grid(i,j).show(color)
+          end
+        end
+      end
+
+      private
+      def subdivide(total, num)
+        (total.to_f - (gutter * (num - 1).to_f)) / num.to_f
+      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 its corners, which can be plugged into most existing prawn 
+    # methods.
+    #
+    class Box
+      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 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 + gutter) * @j.to_f
+      end
+    
+      # x-coordinate of right side 
+      def right
+        @right ||= left + width
+      end
+    
+      # y-coordinate of the top
+      def top
+        @top ||= total_height - ((height + 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    
+      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
+          pdf.stroke_color = grid_color
+          pdf.text self.name
+          pdf.stroke_bounds
+        end
+      end
+    
+      private
+      def grid
+        pdf.grid
+      end
+    end
+  
+    # A MultiBox is specified by 2 Boxes and spans the areas between.
+    class MultiBox < Box
+      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
+
+      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)
+    end
+  
+    def multi_box(b1, b2)
+      MultiBox.new(self, b1, b2)
+    end
+  end
+end

data/lib/prawn/layout/page.rb

@@ -0,0 +1,116 @@
+# encoding: utf-8
+
+# layout/page.rb : Provides helpers for page layout
+#
+# Copyright January 2009, Gregory Brown. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Document
+    # A LazyBoundingBox is simply a BoundingBox with an action tied to it to be 
+    # executed later.  The lazy_bounding_box method takes the same arguments as
+    # bounding_box, but returns a LazyBoundingBox object instead of executing
+    # the code block directly.
+    #
+    # You can then call LazyBoundingBox#draw at any time (or multiple times if 
+    # you wish), and the contents of the block will then be run. This can be
+    # useful for assembling repeating page elements or reusable components.
+    #
+    #  file = "lazy_bounding_boxes.pdf"
+    #  Prawn::Document.generate(file, :skip_page_creation => true) do                    
+    #    point = [bounds.right-50, bounds.bottom + 25]
+    #    page_counter = lazy_bounding_box(point, :width => 50) do   
+    #      text "Page: #{page_count}"
+    #    end 
+    #
+    #    10.times do         
+    #     start_new_page
+    #      text "Some text"  
+    #      page_counter.draw
+    #    end
+    #  end
+    #
+    def lazy_bounding_box(*args,&block)
+      translate!(args[0])  
+      box = LazyBoundingBox.new(self,*args)
+      box.action(&block)
+      return box 
+    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 are used.   
+    #
+    #   header margin_box.top_left do 
+    #    text "Here's My Fancy Header", :size => 25, :align => :center   
+    #    stroke_horizontal_rule
+    #  end
+    #
+    def header(top_left,options={},&block)   
+      @header = repeating_page_element(top_left,options,&block)
+    end
+        
+    # A footer 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 are used.
+    #
+    #   footer [margin_box.left, margin_box.bottom + 25] do
+    #     stroke_horizontal_rule
+    #     text "And here's a sexy footer", :size => 16
+    #   end    
+    #
+    def footer(top_left,options={},&block)       
+      @footer = repeating_page_element(top_left,options,&block)
+    end
+
+    private
+
+    def repeating_page_element(top_left,options={},&block)   
+      r = LazyBoundingBox.new(self, translate(top_left),
+        :width  => options[:width]  || margin_box.width, 
+        :height => options[:height] || margin_box.height )
+      r.action(&block)
+      return r
+    end  
+
+    class LazyBoundingBox < BoundingBox
+       
+      # Defines the block to be executed by LazyBoundingBox#draw. 
+      # Usually, this will be used via a higher level interface.  
+      # See the documentation for Document#lazy_bounding_box, Document#header,
+      # and Document#footer
+      #
+      def action(&block)
+        @action = block
+      end
+      
+      # Sets Document#bounds to use the LazyBoundingBox for its bounds,
+      # runs the block specified by LazyBoundingBox#action,
+      # and then restores the original bounds of the document.
+      #
+      def draw
+        @parent.mask(:y) do  
+          parent_box = @parent.bounds  
+          @parent.bounds = self    
+          @parent.y = absolute_top
+          @action.call   
+          @parent.bounds = parent_box
+        end
+      end
+    end
+  end
+end

data/lib/prawn/layout.rb

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

data/lib/prawn/table/cell.rb

@@ -0,0 +1,287 @@
+# encoding: utf-8   
+
+# cell.rb : Table support functions
+#
+# Copyright June 2008, Gregory Brown.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+module Prawn
+
+  class Document
+    # Builds and renders a Table::Cell.  A cell is essentially a
+    # special-purpose bounding box designed for flowing text within a bordered
+    # area.  For available options, see Table::Cell#new.
+    #
+    #    Prawn::Document.generate("cell.pdf") do
+    #       cell [100,500], 
+    #         :width => 200,
+    #         :text  => "The rain in Spain falls mainly on the plains"
+    #    end
+    #
+    def cell(point, options={})
+      Prawn::Table::Cell.new(
+        options.merge(:document => self, :point => point)).draw
+    end
+  end
+
+  class Table
+    # A cell is a special-purpose bounding box designed to flow text within a
+    # bordered area. This is used by Prawn's Document::Table implementation but
+    # can also be used standalone for drawing text boxes via Document#cell
+    #
+    class Cell
+
+      # Creates a new cell object.  Generally used indirectly via Document#cell
+      #
+      # Of the available options listed below, <tt>:point</tt>, <tt>:width</tt>,
+      # and <tt>:text</tt> must be provided. If you are not using the
+      # Document#cell shortcut, the <tt>:document</tt> must also be provided.
+      #
+      # <tt>:point</tt>:: Absolute [x,y] coordinate of the top-left corner of the cell.
+      # <tt>:document</tt>:: The Prawn::Document object to render on. 
+      # <tt>:text</tt>:: The text to be flowed within the cell
+      # <tt>:text_color</tt>:: The color of the text to be displayed
+      # <tt>:width</tt>:: The width in PDF points of the cell.
+      # <tt>:height</tt>:: The height in PDF points of the cell.
+      # <tt>:horizontal_padding</tt>:: The horizontal padding in PDF points
+      # <tt>:vertical_padding</tt>:: The vertical padding in PDF points
+      # <tt>:padding</tt>:: Overrides both horizontal and vertical padding
+      # <tt>:align</tt>:: One of <tt>:left</tt>, <tt>:right</tt>, <tt>:center</tt>
+      # <tt>:borders</tt>:: An array of sides which should have a border. Any of <tt>:top</tt>, <tt>:left</tt>, <tt>:right</tt>, <tt>:bottom</tt>
+      # <tt>:border_width</tt>:: The border line width. Defaults to 1.
+      # <tt>:border_style</tt>:: One of <tt>:all</tt>, <tt>:no_top</tt>, <tt>:no_bottom</tt>, <tt>:sides</tt>, <tt>:none</tt>, <tt>:bottom_only</tt>. Defaults to :all.
+      # <tt>:border_color</tt>:: The color of the cell border.
+      # <tt>:font_size</tt>:: The font size for the cell text.
+      # <tt>:font_style</tt>:: The font style for the cell text.
+      #
+      def initialize(options={})
+        @point        = options[:point]
+        @document     = options[:document]
+        @text         = options[:text].to_s
+        @text_color   = options[:text_color]
+        @width        = options[:width]
+        @height       = options[:height]
+        @borders      = options[:borders]
+        @border_width = options[:border_width] || 1
+        @border_style = options[:border_style] || :all               
+        @border_color = options[:border_color]
+        @background_color = options[:background_color] 
+        @align            = options[:align] || :left
+        @font_size        = options[:font_size]
+        @font_style       = options[:font_style]
+
+        @horizontal_padding = options[:horizontal_padding] || 0
+        @vertical_padding   = options[:vertical_padding]   || 0
+
+        if options[:padding]
+          @horizontal_padding = @vertical_padding = options[:padding]
+        end
+
+        @rowspan = options[:rowspan] || 1
+        @colspan = options[:colspan] || 1
+      end
+
+      attr_accessor :point, :border_style, :border_width, :background_color,
+                    :document, :horizontal_padding, :vertical_padding, :align,
+                    :borders, :text_color, :border_color, :font_size, :font_style,
+                    :rowspan, :colspan
+
+      attr_writer   :height, :width #:nodoc:   
+           
+      # Returns the cell's text as a string.
+      #
+      def to_s
+        @text
+      end
+
+      # The width of the text area excluding the horizonal padding
+      #
+      def text_area_width
+        width - 2*@horizontal_padding
+      end
+
+      # The width of the cell in PDF points
+      #
+      def width
+        @width || (@document.width_of(@text, :size => @font_size)) + 2*@horizontal_padding
+      end
+
+      # The height of the cell in PDF points
+      #
+      def height  
+        @height || text_area_height + 2*@vertical_padding
+      end
+
+      # The height of the text area excluding the vertical padding
+      #
+      def text_area_height
+        text_height = 0
+        if @font_size
+          @document.font_size(@font_size) do
+            text_height = @document.height_of(@text, text_area_width)
+          end
+        else
+          text_height = @document.height_of(@text, text_area_width)
+        end
+        text_height
+      end
+
+      # Draws the cell onto the PDF document
+      # 
+      def draw
+        rel_point = @point                
+        
+        if @background_color    
+          @document.mask(:fill_color) do
+            @document.fill_color @background_color  
+            h  = borders.include?(:bottom) ? 
+              height - border_width : height + border_width / 2.0
+            @document.fill_rectangle [rel_point[0] + border_width / 2.0, 
+                                      rel_point[1] - border_width / 2.0 ], 
+                width - border_width, h  
+          end
+        end
+
+        if @border_width > 0
+          @document.mask(:line_width) do
+            @document.line_width = @border_width
+
+            @document.mask(:stroke_color) do
+              @document.stroke_color @border_color if @border_color
+
+              if borders.include?(:left)
+                @document.stroke_line [rel_point[0], rel_point[1] + (@border_width / 2.0)], 
+                  [rel_point[0], rel_point[1] - height - @border_width / 2.0 ]
+              end
+
+              if borders.include?(:right)
+                @document.stroke_line( 
+                  [rel_point[0] + width, rel_point[1] + (@border_width / 2.0)],
+                  [rel_point[0] + width, rel_point[1] - height - @border_width / 2.0] )
+              end
+
+              if borders.include?(:top)
+                @document.stroke_line(
+                  [ rel_point[0] + @border_width / 2.0, rel_point[1] ], 
+                  [ rel_point[0] - @border_width / 2.0 + width, rel_point[1] ])
+              end
+
+              if borders.include?(:bottom)
+                @document.stroke_line [rel_point[0], rel_point[1] - height ],
+                                    [rel_point[0] + width, rel_point[1] - height]
+              end
+            end
+
+          end
+          
+          borders
+
+        end
+
+        @document.bounding_box( [@point[0] + @horizontal_padding, 
+                                 @point[1] - @vertical_padding], 
+                                :width   => text_area_width,
+                                :height  => height - @vertical_padding) do
+          @document.move_down((@document.font.line_gap - @document.font.descender)/2)
+
+          options = {:align => @align, :final_gap => false}
+
+          options[:size] = @font_size if @font_size
+          options[:style] = @font_style if @font_style
+
+          @document.mask(:fill_color) do
+            @document.fill_color @text_color if @text_color                        
+            @document.text @text, options
+          end
+        end
+      end
+
+      private
+
+      def borders
+        @borders ||= case @border_style
+        when :all
+          [:top,:left,:right,:bottom]
+        when :sides
+          [:left,:right]
+        when :no_top
+          [:left,:right,:bottom]
+        when :no_bottom
+          [:left,:right,:top]
+        when :bottom_only
+          [:bottom]
+        when :none
+          []
+        end
+      end
+
+    end
+
+    class CellFake < Cell #:nodoc:
+      def height
+        0
+      end
+
+      def draw
+      end
+    end
+
+    class CellBlock #:nodoc:
+
+      # Not sure if this class is something I want to expose in the public API.
+
+      def initialize(document)
+        @document = document
+        @cells    = []
+        @width    = 0
+        @height   = 0
+      end
+
+      attr_reader :width, :height, :cells
+      attr_accessor :background_color, :text_color, :border_color
+
+      def <<(cell)
+        @cells << cell
+        @height = cell.height if cell.height > @height 
+        @width += cell.width
+        self
+      end
+
+      def draw
+        y = @document.y
+        x = @document.bounds.absolute_left
+
+        @cells.each do |e|
+          e.point  = [x - @document.bounds.absolute_left, 
+                      y - @document.bounds.absolute_bottom]
+          e.height ||= @height
+          e.background_color ||= @background_color
+          e.text_color ||= @text_color
+          e.border_color ||= @border_color
+          e.draw
+          x += e.width
+        end
+        
+        @document.y = y - @height
+      end
+
+      def border_width
+        @cells[0].border_width
+      end
+
+      def border_style=(s)
+        @cells.each { |e| e.border_style = s }
+      end    
+      
+      def align=(align) 
+        @cells.each { |e| e.align = align } 
+      end           
+      
+      def border_style
+        @cells[0].border_style
+      end
+
+    end
+  end
+ 
+end