davebenvenuti-prawn 0.11.1.pre

data/lib/prawn/layout/grid.rb

@@ -0,0 +1,259 @@
+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, :row_gutter, :column_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 work with 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, :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]
+        set_gutter(options)
+      end
+
+      # Calculates the base width of boxes.
+      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)
+      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, 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
+          @row_gutter, @column_gutter = @gutter, @gutter
+        else
+          @row_gutter    = options[:row_gutter].to_f
+          @column_gutter = options[:column_gutter].to_f
+          @gutter = 0
+        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 
+    # its corners, which can be plugged into most existing prawnmethods.
+    #
+    class Box #:nodoc:
+      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 + grid.column_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 + 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    
+      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
+          original_stroke_color = pdf.stroke_color
+
+          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:
+      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/measurement_extensions.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+# measurement_extensions.rb: Core extensions for Prawn::Measurements
+#
+# Copyright December 2008, Florian Witteler.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'prawn/measurements'
+
+class Numeric
+  include Prawn::Measurements        
+  # prawns' basic unit is PostScript-Point        
+  # 72 points per inch
+
+  def mm
+    return mm2pt(self)
+  end
+
+  def cm
+    return cm2pt(self)
+  end
+
+  def dm
+    return dm2pt(self)
+  end
+
+  def m
+    return m2pt(self)
+  end
+
+  def in
+    return in2pt(self)
+  end
+
+  def yd
+    return yd2pt(self)
+  end
+
+  def ft
+    return ft2pt(self)
+  end
+  
+  def pt
+    return self
+  end
+end        

data/lib/prawn/measurements.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+# measurements.rb: Conversions from other measurements to PDF points
+#
+# Copyright December 2008, Florian Witteler.  All Rights Reserved.
+#
+module Prawn  
+  module Measurements
+  
+    # ============================================================================
+    #metric conversions
+    def cm2mm(cm)
+      return cm*10
+    end
+  
+    def dm2mm(dm)
+      return dm*100  
+    end
+  
+    def m2mm(m)
+      return m*1000
+    end
+  
+    # ============================================================================
+    # imperial conversions    
+    # from http://en.wikipedia.org/wiki/Imperial_units
+  
+    def ft2in(ft)
+      return ft * 12
+    end  
+
+    def yd2in(yd)
+      return yd*36
+    end
+
+  
+    # ============================================================================
+    # PostscriptPoint-converisons
+  
+    def in2pt(inch)
+      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)    
+      return pt * 1 / mm2pt(1)# (25.4 / 72)
+    end
+  end
+end

data/lib/prawn/outline.rb

@@ -0,0 +1,326 @@
+# encoding: utf-8
+#
+# generates outline dictionary and items for document
+#
+# Author Jonathan Greenberg
+
+require 'forwardable'
+
+module Prawn
+  
+  class Document
+
+    # Lazily instantiates an Outline object for document. This is used as point of entry
+    # to methods to build the outline tree.
+    def outline
+      @outline ||= Outline.new(self)
+    end 
+
+  end
+  
+  # The Outline class organizes the outline tree items for the document.
+  # Note that the prev and parent instance variables are adjusted while navigating 
+  # through the nested blocks. These variables along with the presence or absense 
+  # of blocks are the primary means by which the relations for the various
+  # OutlineItems and the OutlineRoot are set. Unfortunately, the best way to
+  # understand how this works is to follow the method calls through a real example.
+  #
+  # Some ideas for the organization of this class were gleaned from name_tree. In 
+  # particular the way in which the OutlineItems are finally rendered into document 
+  # objects in PdfObject through a hash.
+  #
+  class Outline
+    
+    extend Forwardable
+    def_delegator :@document, :page_number
+    
+    attr_accessor :parent
+    attr_accessor :prev
+    attr_accessor :document
+    attr_accessor :items
+    
+    def initialize(document)
+      @document = document
+      @parent = root
+      @prev = nil
+      @items = {}
+    end 
+    
+    # Defines/Updates an outline for the document.
+    # The outline is an optional nested index that appears on the side of a PDF 
+    # document usually with direct links to pages. The outline DSL is defined by nested 
+    # blocks involving two methods: section and page; see the documentation on those methods 
+    # for their arguments and options. Note that one can also use outline#update 
+    # to add more sections to the end of the outline tree using the same syntax and scope. 
+    #
+    # The syntax is best illustrated with an example:
+    #
+    # Prawn::Document.generate(outlined_document.pdf) do
+    #   text "Page 1. This is the first Chapter. "
+    #   start_new_page
+    #   text "Page 2. More in the first Chapter. "
+    #   start_new_page
+    #   outline.define do
+    #     section 'Chapter 1', :destination => 1, :closed => true do 
+    #       page :destination => 1, :title => 'Page 1'
+    #       page :destination => 2, :title => 'Page 2'
+    #     end
+    #   end 
+    #   start_new_page do
+    #   outline.update do 
+    #     section 'Chapter 2', :destination =>  2, do
+    #       page :destination => 3, :title => 'Page 3'
+    #     end
+    #   end
+    # end 
+    #
+    def define(&block)
+      instance_eval(&block)  if block
+    end
+    
+    alias :update :define 
+         
+    # Inserts an outline section to the outline tree (see outline#define).
+    # Although you will probably choose to exclusively use outline#define so 
+    # that your outline tree is contained and easy to manage, this method
+    # gives you the option to insert sections to the outline tree at any point
+    # during document generation. This method allows you to add a child subsection 
+    # to any other item at any level in the outline tree. 
+    # Currently the only way to locate the place of entry is with the title for the 
+    # item. If your title names are not unique consider using define_outline.
+    # The method takes the following arguments:
+    #   title: a string that must match an outline title to add the subsection to
+    #   position: either :first or :last(the default) where the subsection will be placed relative 
+    #      to other child elements. If you need to position your subsection in between 
+    #      other elements then consider using #insert_section_after   
+    #   block: uses the same DSL syntax as outline#define, for example: 
+    #
+    # Consider using this method inside of outline.update if you want to have the outline object
+    # to be scoped as self (see #insert_section_after example).
+    # 
+    #   go_to_page 2
+    #   start_new_page
+    #   text "Inserted Page"
+    #   outline.add_subsection_to :title => 'Page 2', :first do 
+    #     outline.page :destination => page_number, :title => "Inserted Page"
+    #   end
+    # 
+    def add_subsection_to(title, position = :last, &block)
+      @parent = items[title]
+      raise Prawn::Errors::UnknownOutlineTitle, 
+        "\n No outline item with title: '#{title}' exists in the outline tree" unless @parent
+      @prev = position == :first ? nil : @parent.data.last
+      nxt = position == :first ? @parent.data.first : nil
+      insert_section(nxt, &block)  
+    end
+      
+    # Inserts an outline section to the outline tree (see outline#define).
+    # Although you will probably choose to exclusively use outline#define so 
+    # that your outline tree is contained and easy to manage, this method
+    # gives you the option to insert sections to the outline tree at any point
+    # during document generation. Unlike outline.add_section, this method allows 
+    # you to enter a section after any other item at any level in the outline tree. 
+    # Currently the only way to locate the place of entry is with the title for the 
+    # item. If your title names are not unique consider using define_outline.
+    # The method takes the following arguments:
+    #   title: the title of other section or page to insert new section after
+    #   block: uses the same DSL syntax as outline#define, for example: 
+    # 
+    #   go_to_page 2
+    #   start_new_page
+    #   text "Inserted Page"
+    #   update_outline do
+    #     insert_section_after :title => 'Page 2' do 
+    #       page :destination => page_number, :title => "Inserted Page" 
+    #     end
+    #   end
+    #
+    def insert_section_after(title, &block)
+      @prev = items[title]
+      raise Prawn::Errors::UnknownOutlineTitle, 
+        "\n No outline item with title: '#{title}' exists in the outline tree" unless @prev
+      @parent = @prev.data.parent
+      nxt = @prev.data.next
+      insert_section(nxt, &block)   
+    end
+     
+    # See outline#define above for documentation on how this is used in that context
+    #
+    # Adds an outine section to the outline tree.
+    # Although you will probably choose to exclusively use outline#define so 
+    # that your outline tree is contained and easy to manage, this method
+    # gives you the option to add sections to the outline tree at any point
+    # during document generation. When not being called from within another #section block 
+    # the section will be added at the top level after the other root elements of the outline. 
+    # For more flexible placement try using outline#insert_section_after and/or      
+    # outline#add_subsection_to 
+    # Takes the following arguments:
+    #   title: the outline text that appears for the section.
+    #   options: destination - optional integer defining the page number for a destination link.
+    #                 - currently only :FIT destination supported with link to top of page.
+    #            closed - whether the section should show its nested outline elements.
+    #                   - defaults to false. 
+    #            block: more nested subsections and/or page blocks 
+    #   
+    # example usage:
+    #
+    #   outline.section 'Added Section', :destination => 3 do
+    #     outline.page :destionation => 3, :title => 'Page 3'
+    #   end
+    def section(title, options = {}, &block)
+      add_outline_item(title, options, &block)
+    end 
+    
+    # See Outline#define above for more documentation on how it is used in that context
+    #
+    # Adds a page to the outline.
+    # Although you will probably choose to exclusively use outline#define so 
+    # that your outline tree is contained and easy to manage, this method also
+    # gives you the option to add pages to the root of outline tree at any point
+    # during document generation. Note that the page will be added at the 
+    # top level after the other root outline elements. For more flexible placement try
+    # using outline#insert_section_after and/or outline#add_subsection_to.
+    # 
+    # Takes the following arguments:
+    #     options:
+    #            title - REQUIRED. The outline text that appears for the page. 
+    #            destination - integer defining the page number for the destination link.
+    #              currently only :FIT destination supported with link to top of page.
+    #            closed - whether the section should show its nested outline elements.
+    #                   - defaults to false.
+    # example usage:
+    #
+    #   outline.page :title => "Very Last Page" 
+    # Note: this method is almost identical to section except that it does not accept a block 
+    # thereby defining the outline item as a leaf on the outline tree structure. 
+    def page(options = {})
+      if options[:title]
+        title = options[:title] 
+      else
+        raise Prawn::Errors::RequiredOption, 
+          "\nTitle is a required option for page"
+      end
+      add_outline_item(title, options)
+    end
+      
+  private 
+  
+    # The Outline dictionary (12.3.3) for this document.  It is
+    # lazily initialized, so that documents that do not have an outline
+    # do not incur the additional overhead.
+    def root
+      document.state.store.root.data[:Outlines] ||= document.ref!(OutlineRoot.new)
+    end
+     
+    def add_outline_item(title, options, &block)
+      outline_item = create_outline_item(title, options)
+      set_relations(outline_item)
+      increase_count
+      set_variables_for_block(outline_item, block)
+      block.call if block
+      reset_parent(outline_item)
+    end
+    
+    def create_outline_item(title, options)
+      outline_item = OutlineItem.new(title, parent, options)
+
+      if options[:destination]
+        page_index = options[:destination] - 1
+        outline_item.dest = [document.state.pages[page_index].dictionary, :Fit] 
+      end
+
+      outline_item.prev = prev if @prev
+      items[title] = document.ref!(outline_item)
+    end
+    
+    def set_relations(outline_item)
+      prev.data.next = outline_item if prev
+      parent.data.first = outline_item unless prev
+      parent.data.last = outline_item
+    end
+    
+    def increase_count
+      counting_parent = parent
+      while counting_parent
+        counting_parent.data.count += 1
+        if counting_parent == root
+          counting_parent = nil
+        else
+          counting_parent = counting_parent.data.parent
+        end
+      end
+    end
+    
+    def set_variables_for_block(outline_item, block)
+      self.prev = block ? nil : outline_item
+      self.parent = outline_item if block
+    end
+    
+    def reset_parent(outline_item)
+      if parent == outline_item
+        self.prev = outline_item
+        self.parent = outline_item.data.parent
+      end
+    end 
+    
+    def insert_section(nxt, &block)
+      last = @parent.data.last
+      if block
+        block.call
+      end
+      adjust_relations(nxt, last)
+      reset_root_positioning
+    end
+    
+    def adjust_relations(nxt, last)
+      if nxt 
+        nxt.data.prev = @prev
+        @prev.data.next = nxt
+        @parent.data.last = last
+      end
+    end 
+    
+    def reset_root_positioning
+      @parent = root
+      @prev = root.data.last
+    end
+    
+  end
+  
+  class OutlineRoot #:nodoc:
+    attr_accessor :count, :first, :last
+    
+    def initialize
+      @count = 0
+    end
+        
+    def to_hash
+      {:Type => :Outlines, :Count => count, :First => first, :Last => last}
+    end
+  end
+  
+  class OutlineItem #:nodoc:
+    attr_accessor :count, :first, :last, :next, :prev, :parent, :title, :dest, :closed
+  
+    def initialize(title, parent, options)
+      @closed = options[:closed]
+      @title = title
+      @parent = parent
+      @count = 0
+    end
+  
+    def to_hash
+      hash = { :Title => title,
+               :Parent => parent,
+               :Count => closed ? -count : count }
+      [{:First => first}, {:Last => last}, {:Next => @next}, 
+       {:Prev => prev}, {:Dest => dest}].each do |h|
+        unless h.values.first.nil?
+          hash.merge!(h)
+        end
+      end
+      hash 
+    end
+  end    
+end
+