prawn 0.2.3 → 0.3.0

data/examples/table/table_header_underline.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+#
+# Demonstrates the :underline_header border style for Document#table.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+
+Prawn::Document.generate "table_header_underline.pdf" do
+  table [ ['01/01/2008', 'John Doe', '4.2', '125.00', '525.00'], 
+          ['01/12/2008', 'Jane Doe', '3.2', '75.50', '241.60'] ] * 5,
+  :position => :center,
+  :headers => ['Date', 'Employee', 'Hours', 'Rate', 'Total'],
+  :widths => { 0 => 75, 1 => 100, 2 => 50, 3 => 50, 4 => 50},
+  :border_style => :underline_header
+end

data/examples/{alignment.rb → text/alignment.rb}

@@ -1,6 +1,9 @@
 # encoding: utf-8
-
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+#
+# This example demonstrates usage of Document#text with the :align option.
+# Available options are :left, :right, and :center, with :left as default.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require "prawn"
 
 Prawn::Document.generate("alignment.pdf") do

data/examples/text/family_based_styling.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+#
+# This example demonstrates using the :style option for Document#text.
+# If you are working with TTF fonts, you'll want to check out the 
+# documentation for Document#font_families and register your fonts with it.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+
+Prawn::Document.generate("family_style.pdf") do
+  ["Courier","Helvetica","Times-Roman"].each do |f|
+    [:bold,:bold_italic,:italic,:normal].each do |s|
+      font f, :style => s
+      text "I'm writing in #{f} (#{s})"
+    end
+  end
+  
+  font "Helvetica"
+  
+  text "Normal"
+  text "Bold",        :style => :bold
+  text "Bold Italic", :style => :bold_italic
+  text "Italic",      :style => :italic
+  text "Normal"
+end

data/examples/{flowing_text_with_header_and_footer.rb → text/flowing_text_with_header_and_footer.rb}

@@ -1,18 +1,30 @@
 # encoding: utf-8       
-
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+# 
+# Multi-faceted example that demonstrates a document flowing between header
+# and footer regions.  At the moment, headers and footers in Prawn are run
+# using the current font settings (among other things), for each page.  THhis
+# means that it is important to non-destructively set your desired styling 
+# within your headers and footers, as shown below.  
+#
+# Future versions of Prawn may make this more convenient somehow.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require "prawn"                                           
 
 Prawn::Document.generate("flow_with_headers_and_footers.pdf")  do
 
   header margin_box.top_left do 
-    text "Here's My Fancy Header", :size => 25, :align => :center   
-    stroke_horizontal_rule
+    font "Helvetica" do
+      text "Here's My Fancy Header", :size => 25, :align => :center   
+      stroke_horizontal_rule
+    end
   end   
                 
   footer [margin_box.left, margin_box.bottom + 25] do
-    stroke_horizontal_rule
-    text "And here's a sexy footer", :size => 16
+    font "Helvetica" do
+      stroke_horizontal_rule
+      text "And here's a sexy footer", :size => 16
+    end
   end
                                       
   bounding_box([bounds.left, bounds.top - 50], 
@@ -68,5 +80,4 @@ Prawn::Document.generate("flow_with_headers_and_footers.pdf")  do
           
  end    
  
-end       
-                
+end

data/examples/text/font_calculations.rb

@@ -0,0 +1,91 @@
+# encoding: utf-8
+# 
+# This example is a demonstration of how Prawn does its text positioning,
+# meant to assist those that need to do advanced positioning calculations.
+# Run the example for a clearer picture of how things work
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require 'prawn'
+
+Prawn::Document.generate('font_calculations.pdf') do
+  
+  def demonstration(pos)
+    move_down 10
+
+    stroke_horizontal_rule
+
+    text "When using flowing text, Prawn will position text\n" +
+         "starting font.#{pos} below the baseline, and leave\n" +
+         "the y-cursor at the baseline of the next line of text"
+
+    stroke_horizontal_rule
+
+    move_down 20
+
+    bl = y - bounds.absolute_bottom
+
+    stroke_horizontal_rule
+    text "When using text positioned with :at, the baseline is used", :at => [0, bl]
+
+    text "(and the Y-cursor is not moved)", :at => [350, bl]
+
+    colors = { :ascender    => "ff0000", 
+               :descender   => "00ff00",
+               :line_gap    => "0000ff",
+               :font_height => "005500" }
+
+
+    pad(20) do                    
+      text "Calculations Demo", :size => 16
+    end
+
+    fill_color colors[:ascender]
+    text "ASCENDER"
+
+    fill_color colors[:descender]
+    text "DESCENDER"
+
+    fill_color colors[:line_gap]
+    text "LINEGAP" 
+
+    fill_color colors[:font_height]
+    text "FONT_HEIGHT"
+
+    fill_color "000000"
+    font.size = 20
+
+    move_down 40
+
+    bl = y - bounds.absolute_bottom
+    text "The quick brown fox jumps over the lazy dog.", :at => [0, bl]
+
+    stroke_color colors[:ascender]
+    stroke_line [0, bl], [0, bl + font.ascender]
+    stroke_line [0, bl + font.ascender], [bounds.width, bl + font.ascender]
+
+    stroke_color colors[:descender]
+    stroke_line [0,bl], [0, bl + font.descender]
+    stroke_line [0, bl + font.descender], [bounds.width, bl + font.descender]
+
+    stroke_color colors[:line_gap]
+    stroke_line [0, bl + font.descender], [0,bl + font.descender - font.line_gap]
+    stroke_line [0, bl + font.descender - font.line_gap], 
+                [bounds.width,bl + font.descender - font.line_gap]
+
+    stroke_color colors[:font_height]
+    stroke_line [bounds.width, bl + font.ascender],
+                [bounds.width, bl + font.descender - font.line_gap]
+                
+    stroke_color "000000"
+    fill_color "000000"
+  end
+  
+  text "Using AFM", :size => 20
+  demonstration("height")
+  
+  move_down 75
+  font "#{Prawn::BASEDIR}/data/fonts/DejaVuSans.ttf"
+  text "Using TTF", :size => 20
+  demonstration("ascender")
+  
+end

data/examples/text/font_size.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+#
+# This example shows the many ways of setting font sizes in Prawn
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+
+Prawn::Document.generate "font_size.pdf", :page_size => "A4" do
+
+  # Explicit global changes
+  font 'Helvetica'
+  font.size = 16
+
+  text 'Font at 16 point'
+
+  # Transactional changes rolled back after block exit
+  font.size 9 do
+    text 'Font at 9 point'
+    # single line changes, not persisted.
+    text 'Font at manual override 20 point', :size => 20
+    text 'Font at 9 point'
+  end
+
+  # Transactional changes rolled back after block exit on full fonts.
+  font("Times-Roman", :style => :italic, :size => 12) do
+    text "Font in times at 12"
+    font.size(16) { text "Font in Times at 16" }
+  end
+
+  text 'Font at 16 point'
+
+  font "Courier", :size => 40
+  text "40 pt!"
+end

data/examples/{kerning.rb → text/kerning.rb}

@@ -1,4 +1,8 @@
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+# encoding: utf-8
+#
+# Demonstration of enabling and disabling kerning support
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require "prawn"
 
 Prawn::Document.generate "kerning.pdf" do

data/examples/text/simple_text.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+#
+# An early example of basic text generation at absolute positions.
+# Mostly kept for nostalgia.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+
+Prawn::Document.generate "simple_text.pdf" do       
+  fill_color "0000ff"
+  text "Hello World", :at => [200,420], :size => 32, :rotate => 45
+  font "Times-Roman"     
+  fill_color "ff0000"
+  text "Using Another Font", :at => [5,5]    
+  start_new_page        
+  font "Courier"       
+  text "Goodbye World", :at => [288,50]     
+end

data/examples/text/simple_text_ttf.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+#
+# An early example of TTF font embedding.  Mostly kept for nostalgia's sake.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+
+Prawn::Document.generate "simple_text_ttf.pdf" do       
+  fill_color "0000ff"
+  font "#{Prawn::BASEDIR}/data/fonts/comicsans.ttf" 
+  text "Hello World", :at => [200,720], :size => 32         
+
+  font "#{Prawn::BASEDIR}/data/fonts/Chalkboard.ttf"
+
+  pad(20) do
+    text "This is chalkboard wrapping " * 20
+  end
+end

data/examples/{span.rb → text/span.rb}

@@ -1,6 +1,9 @@
 # encoding: utf-8
-
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+#
+# Demonstration of Document#span, which is used for generating flowing
+# columns of text.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require "prawn"
 
 Prawn::Document.generate("span.pdf") do

data/examples/text/text_box.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+#
+# A text box is positioned by a top-left corner, width, and height and is
+# essentially an invisible rectangle that the text wil lflow within.  If the
+# text exceeds the boundaries, it is either truncated, replaced with some
+# ellipses, or set to expand beyond the bottom boundary.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require 'prawn'
+
+Prawn::Document.generate("text_box.pdf") do
+
+  text_box "Oh hai text box. " * 200, 
+    :width    => 300, :height => font.height * 5,
+    :overflow => :ellipses, 
+    :at       => [100,bounds.top]
+
+  text_box "Oh hai text box. " * 200,
+    :width    => 250, :height => font.height * 10,
+    :overflow => :truncate,
+    :at       => [50, 300]
+
+  move_down 20
+
+  text_box "Oh hai text box. " * 100, :overflow => :expand
+end

data/examples/{text_flow.rb → text/text_flow.rb}

@@ -1,6 +1,9 @@
 # encoding: utf-8
-
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+# 
+# Basic text flowing example including the use of bounding boxes.  A somewhat
+# old example, mostly retained for nostalgia.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require "prawn"
 
 content = <<-EOS

data/lib/prawn.rb

@@ -1,37 +1,41 @@
 # encoding: utf-8
-
+ 
 # prawn.rb : A library for PDF generation in Ruby
 #
-# Copyright April 2008, Gregory Brown.  All Rights Reserved.
+# Copyright April 2008, Gregory Brown. All Rights Reserved.
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
            
-%w[font_ttf].each do |dep|
+%w[ttfunk/lib].each do |dep|
   $LOAD_PATH.unshift(File.dirname(__FILE__) + "/../vendor/#{dep}")
 end
-
-require 'ttf'
-
-module Prawn 
+ 
+require 'ttfunk'
+ 
+module Prawn
   file = __FILE__
   file = File.readlink(file) if File.symlink?(file)
   dir = File.dirname(file)
                           
   # The base source directory for Prawn as installed on the system
-  BASEDIR = File.expand_path(File.join(dir, '..'))  
+  BASEDIR = File.expand_path(File.join(dir, '..'))
   
-  VERSION = "0.2.3"
+  VERSION = "0.3.0"
   
   extend self
   
-  def verify_options(accepted,actual) #:nodoc:                    
+  attr_accessor :debug
+  
+  def verify_options(accepted,actual) #:nodoc:
+    return unless debug || $DEBUG
     require "set"
     unless (act=Set[*actual.keys]).subset?(acc=Set[*accepted])
-      raise Prawn::Errors::UnknownOption, 
+      raise Prawn::Errors::UnknownOption,
         "\nDetected unknown option(s): #{(act - acc).to_a.inspect}\n" <<
         "Accepted options are: #{accepted.inspect}"
-    end    
-  end      
+    end
+    yield if block_given?
+  end
   
   module Configurable #:nodoc:
     def configuration(*args)
@@ -41,16 +45,16 @@ module Prawn
       elsif args.length > 1
         @config.values_at(*args)
       elsif args.length == 1
-        @config[args[0]] 
-      else 
-        @config  
+        @config[args[0]]
+      else
+        @config
       end
-    end     
+    end
     
     alias_method :C, :configuration
   end
-end                                                 
-
+end
+ 
 require "prawn/compatibility"
 require "prawn/errors"
 require "prawn/pdf_object"
@@ -60,4 +64,6 @@ require "prawn/images/jpg"
 require "prawn/images/png"
 require "prawn/document"
 require "prawn/reference"
-require "prawn/font"
+require "prawn/font"
+require "prawn/encoding"
+require "prawn/measurements"

data/lib/prawn/compatibility.rb

@@ -1,3 +1,6 @@
+# Why would we ever use Ruby 1.8.7 when we can backport with something
+# as simple as this?
+#
 # encoding: utf-8
 
 if RUBY_VERSION < "1.9"
@@ -14,7 +17,7 @@ if RUBY_VERSION < "1.9"
   end
   
   class File  #:nodoc:  
-    def self.read_binary(file) 
+    def self.binread(file) 
       File.open(file,"rb") { |f| f.read } 
     end
   end
@@ -27,13 +30,7 @@ if RUBY_VERSION < "1.9"
     false
   end
      
-else
-  
-  class File  #:nodoc:  
-    def self.read_binary(file) 
-      File.open(file,"rb:BINARY") { |f| f.read } 
-    end
-  end  
+else  
  
   def ruby_18  #:nodoc:  
     false  

data/lib/prawn/document.rb

@@ -9,19 +9,23 @@
 require "stringio"
 require "prawn/document/page_geometry" 
 require "prawn/document/bounding_box"
-require "prawn/document/text"      
+require "prawn/document/text"
 require "prawn/document/table"
 require "prawn/document/internals"
 require "prawn/document/span"
+require "prawn/document/annotations"
+require "prawn/document/destinations"
 
 module Prawn
   class Document  
            
     include Prawn::Document::Internals
-    include Prawn::Graphics    
+    include Prawn::Document::Annotations
+    include Prawn::Document::Destinations
+    include Prawn::Graphics
     include Prawn::Images
-    include Text                             
-    include PageGeometry                             
+    include Text
+    include PageGeometry
     
     attr_accessor :y, :margin_box
     attr_reader   :margins, :page_size, :page_layout
@@ -59,14 +63,13 @@ module Prawn
     #
     # <tt>:page_size</tt>:: One of the Document::PageGeometry::SIZES [LETTER]
     # <tt>:page_layout</tt>:: Either <tt>:portrait</tt> or <tt>:landscape</tt>
-    # <tt>:on_page_start</tt>:: Optional proc run at each page start
-    # <tt>:on_page_stop</tt>:: Optional proc  run at each page stop   
     # <tt>:left_margin</tt>:: Sets the left margin in points [ 0.5 inch]
     # <tt>:right_margin</tt>:: Sets the right margin in points [ 0.5 inch]
     # <tt>:top_margin</tt>:: Sets the top margin in points [ 0.5 inch]
     # <tt>:bottom_margin</tt>:: Sets the bottom margin in points [0.5 inch]
     # <tt>:skip_page_creation</tt>:: Creates a document without starting the first page [false]
     # <tt>:compress</tt>:: Compresses content streams before rendering them [false]
+    # <tt>:background</tt>:: An image path to be used as background on all pages [nil]
     # 
     # Usage:
     #                             
@@ -76,19 +79,23 @@ module Prawn
     #   # New document, A4 paper, landscaped
     #   pdf = Prawn::Document.new(:page_size => "A4", :page_layout => :landscape)    
     #
+    #   # New document, with background
+    #   pdf = Prawn::Document.new(:background => "#{Prawn::BASEDIR}/data/images/pigs.jpg")    
+    #
     def initialize(options={},&block)   
-       Prawn.verify_options [:page_size, :page_layout, :on_page_start,
-         :on_page_stop, :left_margin, :right_margin, :top_margin,
-         :bottom_margin, :skip_page_creation, :compress, :skip_encoding, :text_options ], options
+       Prawn.verify_options [:page_size, :page_layout, :left_margin, 
+         :right_margin, :top_margin, :bottom_margin, :skip_page_creation, 
+         :compress, :skip_encoding, :text_options, :background ], options
          
        @objects = []
        @info    = ref(:Creator => "Prawn", :Producer => "Prawn")
-       @pages   = ref(:Type => :Pages, :Count => 0, :Kids => [])  
-       @root    = ref(:Type => :Catalog, :Pages => @pages)        
+       @pages   = ref(:Type => :Pages, :Count => 0, :Kids => [])
+       @root    = ref(:Type => :Catalog, :Pages => @pages)
        @page_size       = options[:page_size]   || "LETTER"    
        @page_layout     = options[:page_layout] || :portrait
        @compress        = options[:compress] || false                
        @skip_encoding   = options[:skip_encoding]
+       @background      = options[:background]
        
        text_options.update(options[:text_options] || {}) 
              
@@ -134,7 +141,9 @@ module Prawn
      
        add_content "q"   
        
-       @y = @bounding_box.absolute_top        
+       @y = @bounding_box.absolute_top
+       
+       image(@background, :at => [0,@y]) if @background
     end             
       
     # Returns the number of pages in the document
@@ -147,6 +156,13 @@ module Prawn
     def page_count
       @pages.data[:Count]
     end
+    
+    # The current y drawing position relative to the innermost bounding box,
+    # or to the page margins at the top level.  
+    #
+    def cursor
+      y - bounds.absolute_bottom
+    end
        
     # Renders the PDF document to string
     #
@@ -270,7 +286,7 @@ module Prawn
                           :Parent    => @pages, 
                           :MediaBox  => page_dimensions, 
                           :Contents  => @page_content)
-      font.add_to_current_page if @font_name  
+      font.add_to_current_page if @font
       update_colors
     end