pdf-wrapper 0.0.2 → 0.0.3

data/CHANGELOG

@@ -1,3 +1,14 @@
+v0.0.3 (xxx)
+- added support for repeating elements (like page numbers) via repeating_element
+- Ensured consistent behaviour WRT functions moving the internal cursor 
+  - functions that require positioning info (cell, shapes, etc) will not move the cursor at all
+  - functions where positioning info in optional (text, image, etc), the cursor will be moved to the bottom left
+    corner of the object
+- Ensure no unrecognised options are provided to various functions
+- Add support for padding between a cell border and its text
+- added support for scaling images proportionally
+- expanded spec coverage
+
 v0.0.2 (11th January 2008)
 - Added support for a range of extra image formats (jpg, pdf, gif, etc)
 - Various documentation improvements 

data/README

@@ -8,12 +8,12 @@ use for making PDFs. The idea is to lever the low level tools in those libraries
 higher level tools - tables, text boxes, borders, lists, repeating elements
 (headers/footers), etc.
 
-At this stage the API is *roughly* following that of PDF::Writer, but i've made 
-tweaks in some places and added some new methods. This is a work in progress so
-many features of PDF::Writer aren't available yet.
+The API started off *roughly* following that of PDF::Writer, but i've made 
+tweaks and changes along the way and it's diverging. This is a work in progress
+so many features of PDF::Writer aren't available yet.
 
 A key motivation for writing this library is cairo's support for Unicode in PDFs.
-All text functions in this library support UTF8 input, although as a native 
+All text functions in this library support UTF-8 input, although as a native 
 English speaker I've only tested this a little, so any feedback is welcome. 
 
 There also seems to be a lack of English documentation available for the ruby 
@@ -51,7 +51,7 @@ James Healy <jimmy@deefa.com>
 * ruby/pango[http://ruby-gnome2.sourceforge.jp/] (optional, required to add text)
 * ruby/rsvg2[http://ruby-gnome2.sourceforge.jp/] (optional, required for SVG support)
 * ruby/gdkpixbuf[http://ruby-gnome2.sourceforge.jp/] (optional, required for GIF/JPG support)
-* ruby/poppler[http://ruby-gnome2.sourceforge.jp/] (optional, required embedding PDF images)
+* ruby/poppler[http://ruby-gnome2.sourceforge.jp/] (optional, required for embedding PDF images)
 
 These are all ruby bindings to C libraries. On Debian/Ubuntu based systems
 (which I develop on) you can get them by running:
@@ -69,7 +69,5 @@ JRuby users, you're probably out of luck.
 
 Rubinius users, I have no idea.
 
-Ruby1.9 users, the current release of ruby/cairo (1.5.0) doesn't work with 1.9,
-but the version in SVN does. Hopefully it will be released soon. The version in
-Debian has been patched to work with 1.9 already. PDF::Wrapper itself is 1.9
-compatible.
+Ruby1.9 users, the current release of ruby/cairo (1.5.1) added support for 1.9. PDF::Wrapper
+itself is 1.9 compatible.

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/testtask'
 require "rake/gempackagetask"
 require 'spec/rake/spectask'
 
-PKG_VERSION = "0.0.2"
+PKG_VERSION = "0.0.3"
 PKG_NAME = "pdf-wrapper"
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 
@@ -46,7 +46,7 @@ Rake::RDocTask.new("doc") do |rdoc|
   rdoc.rdoc_dir = (ENV['CC_BUILD_ARTIFACTS'] || 'doc') + '/rdoc'
   rdoc.rdoc_files.include('README')
   rdoc.rdoc_files.include('CHANGELOG')
-  rdoc.rdoc_files.include('DESIGN')
+  rdoc.rdoc_files.include('TODO')
   rdoc.rdoc_files.include('lib/**/*.rb')
   rdoc.options << "--inline-source"
 end
@@ -66,13 +66,13 @@ spec = Gem::Specification.new do |spec|
   spec.files =  Dir.glob("{examples,lib,specs}/**/**/*") + ["Rakefile"]
   spec.require_path = "lib"
   spec.has_rdoc = true
-  spec.extra_rdoc_files = %w{README DESIGN CHANGELOG}
+  spec.extra_rdoc_files = %w{README CHANGELOG TODO}
   spec.rdoc_options << '--title' << 'PDF::Wrapper Documentation' << '--main'  << 'README' << '-q'
   spec.author = "James Healy"
   spec.homepage = "http://pdf-wrapper.rubyforge.org/"
   spec.email = "jimmy@deefa.com"
   spec.rubyforge_project = "pdf-wrapper"
-  spec.description = "A unicode aware PDF writing library that uses the ruby bindings to various c libraries ( like, cairo, pango, poppler and rsvg ) to do the heavy lifting."
+  spec.description = "A unicode aware PDF writing library that uses the ruby bindings to various c libraries ( like cairo, pango, poppler and rsvg ) to do the heavy lifting."
 end
 
 # package the library into a gem

data/TODO

@@ -0,0 +1 @@
+All TODO's are currently marked inline in the source code

data/examples/cell.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# coding: utf-8
 
 $:.unshift(File.dirname(__FILE__) + "/../lib")
 

data/examples/image.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# coding: utf-8
 
 $:.unshift(File.dirname(__FILE__) + "/../lib")
 

data/examples/repeating.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new(:paper => :A4)
+
+pdf.repeating_element(:all) do
+  pdf.text("Page #{pdf.page}!", :left => pdf.margin_left, :top => pdf.margin_top, :font_size => 18, :alignment => :center)
+end
+
+pdf.repeating_element(:even) do
+  pdf.circle(pdf.absolute_x_middle, pdf.absolute_y_middle, 100)
+end
+
+pdf.repeating_element(:odd) do
+  pdf.rectangle(pdf.absolute_x_middle, pdf.absolute_y_middle, 100, 100)
+end
+
+pdf.repeating_element([1,2]) do
+  pdf.rounded_rectangle(100, 100, 100, 100, 10)
+end
+
+pdf.repeating_element(3) do
+  pdf.line(pdf.absolute_x_middle, pdf.absolute_y_middle, 100, 100)
+end
+
+pdf.repeating_element((3..4)) do
+  pdf.circle(400, 400, 100, :color => :red)
+end
+
+pdf.start_new_page
+pdf.start_new_page
+pdf.start_new_page
+
+pdf.render_to_file("repeating.pdf")

data/examples/shapes.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# coding: utf-8
 
 $:.unshift(File.dirname(__FILE__) + "/../lib")
 

data/examples/table.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# coding: utf-8
 
 $:.unshift(File.dirname(__FILE__) + "/../lib")
 

data/examples/utf8-long.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# coding: utf-8
 
 $:.unshift(File.dirname(__FILE__) + "/../lib")
 

data/examples/utf8.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# coding: utf-8
 
 $:.unshift(File.dirname(__FILE__) + "/../lib")
 

data/lib/pdf/core.rb

@@ -1,3 +1,5 @@
+# coding: utf-8
+
 class Hash
   # raise an error if this hash has any keys that aren't in the supplied list
   # - borrowed from activesupport

data/lib/pdf/wrapper.rb

@@ -1,9 +1,9 @@
-# -* coding: UTF-8 -*-
+# coding: utf-8
 
 require 'stringio'
 require 'pdf/core'
 
-# try to load cairo from the standard places, but don't worry if it fails, 
+# try to load cairo from the standard places, but don't worry if it fails,
 # we'll try to find it via rubygems
 begin
   require 'cairo'
@@ -23,7 +23,7 @@ module PDF
   # Create PDF files by using the cairo and pango libraries.
   #
   # Rendering to a file:
-  #   
+  #
   #   require 'pdf/wrapper'
   #   pdf = PDF::Wrapper.new(:paper => :A4)
   #   pdf.text "Hello World"
@@ -47,7 +47,7 @@ module PDF
   class Wrapper
 
     attr_reader :margin_left, :margin_right, :margin_top, :margin_bottom
-    attr_reader :page_width, :page_height
+    attr_reader :page_width, :page_height, :page
 
     # borrowed from PDF::Writer
     PAGE_SIZES = { # :value {...}:
@@ -82,17 +82,18 @@ module PDF
     # Options:
     # <tt>:paper</tt>::   The paper size to use (default :A4)
     # <tt>:orientation</tt>::   :portrait (default) or :landscape
-    # <tt>:background_colour</tt>::   The background colour to use (default :white)
+    # <tt>:background_color</tt>::   The background colour to use (default :white)
     def initialize(opts={})
       options = {:paper => :A4,
                   :orientation => :portrait,
-                  :background_colour => :white
+                  :background_color => :white
                  }
       options.merge!(opts)
-      
+
       # test for invalid options
+      options.assert_valid_keys(:paper, :orientation, :background_color)
       raise ArgumentError, "Invalid paper option" unless PAGE_SIZES.include?(options[:paper])
-      
+
       # set page dimensions
       if options[:orientation].eql?(:portrait)
         @page_width = PAGE_SIZES[options[:paper]][0]
@@ -117,14 +118,18 @@ module PDF
       @context = Cairo::Context.new(@surface)
 
       # set the background colour
-      set_color(options[:background_colour])
+      set_color(options[:background_color])
       @context.paint
 
       # set a default drawing colour and font style
       default_color(:black)
       default_font("Sans Serif")
       default_font_size(16)
-      
+
+      # maintain a count of pages and array of repeating elements to add to each page
+      @page = 1
+      @repeating = []
+
       # move the cursor to the top left of the usable canvas
       reset_cursor
     end
@@ -132,13 +137,13 @@ module PDF
     #####################################################
     # Functions relating to calculating various page dimensions
     #####################################################
-    
+
     # Returns the x value of the left margin
     # The top left corner of the page is (0,0)
     def absolute_left_margin
       @margin_left
     end
-    
+
     # Returns the x value of the right margin
     # The top left corner of the page is (0,0)
     def absolute_right_margin
@@ -206,7 +211,7 @@ module PDF
     #####################################################
     # Functions relating to working with text
     #####################################################
-    
+
     # change the default font size
     def default_font_size(size)
       #@context.set_font_size(size.to_i)
@@ -229,12 +234,12 @@ module PDF
     #
     # Parameters:
     # <tt>c</tt>::  either a colour symbol recognised by rcairo (:red, :blue, :black, etc) or
-    #               an array with 3-4 integer elements. The first 3 numbers are red, green and 
+    #               an array with 3-4 integer elements. The first 3 numbers are red, green and
     #               blue (0-255). The optional 4th number is the alpha channel and should be
     #               between 0 and 1. See the API docs at http://cairo.rubyforge.org/ for a list
     #               of predefined colours
     def default_color(c)
-      c = translate_color(c) 
+      c = translate_color(c)
       validate_color(c)
       @default_color = c
     end
@@ -248,43 +253,54 @@ module PDF
     # the following options:
     #
     # <tt>:border</tt>::   Which sides of the cell should have a border? A string with any combination the letters tblr (top, bottom, left, right). Nil for no border, defaults to all sides.
-    # <tt>:border_width</tt>::  How wide should the border be? 
+    # <tt>:border_width</tt>::  How wide should the border be?
     # <tt>:border_color</tt>::  What color should the border be?
     # <tt>:bgcolor</tt>::  A background color for the cell. Defaults to none.
+    # <tt>:padding</tt>::  The number of points to leave between the inside of the border and text. Defaults to 3. 
     def cell(str, x, y, w, h, opts={})
       # TODO: add support for pango markup (see http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup)
       # TODO: add a wrap option so wrapping can be disabled
-      # TODO: raise an error if any unrecognised options were supplied 
-      # TODO: add padding between border and text
-      # TODO: how do we handle a single word that is too long for the width?
+      # TODO: handle a single word that is too long for the width
+      # TODO: add an option to draw a border with rounded corners
 
       options = default_text_options
-      options.merge!({:border => "tblr", :border_width => 1, :border_color => :black, :bgcolor => nil})
+      options.merge!({:border => "tblr", :border_width => 1, :border_color => :black, :bgcolor => nil, :padding => 3})
       options.merge!(opts)
+      options.assert_valid_keys(default_text_options.keys + [:width, :border, :border_width, :border_color, :bgcolor, :padding])
+
+      # apply padding
+      textw = x - (options[:padding] * 2)
+      texth = h - (options[:padding] * 2)
+      textx = x + options[:padding]
+      texty = y + options[:padding]
 
-      options[:width]  = w
       options[:border] = "" unless options[:border]
       options[:border].downcase!
 
+      # save the cursor position so we can restore it at the end
+      origx, origy = current_point
+
       # TODO: raise an exception if the box coords or dimensions will place it off the canvas
       rectangle(x,y,w,h, :color => options[:bgcolor], :fill_color => options[:bgcolor]) if options[:bgcolor]
 
-      layout = build_pango_layout(str.to_s, options)
+      layout = build_pango_layout(str.to_s, textw, options)
 
       set_color(options[:color])
 
       # draw the context on our cairo layout
-      render_layout(layout, x, y, h, :auto_new_page => false)
+      render_layout(layout, textx, texty, texth, :auto_new_page => false)
 
       # draw a border around the cell
       # TODO: obey options[:border_width]
-      # TODO: obey options[:border_color]
-      line(x,y,x+w,y)     if options[:border].include?("t")
-      line(x,y+h,x+w,y+h) if options[:border].include?("b")
-      line(x,y,x,y+h)     if options[:border].include?("l")
-      line(x+w,y,x+w,y+h) if options[:border].include?("r")
+      line(x,y,x+w,y, :color => options[:border_color])     if options[:border].include?("t")
+      line(x,y+h,x+w,y+h, :color => options[:border_color]) if options[:border].include?("b")
+      line(x,y,x,y+h, :color => options[:border_color])     if options[:border].include?("l")
+      line(x+w,y,x+w,y+h, :color => options[:border_color]) if options[:border].include?("r")
+
+      # restore the cursor position
+      move_to(origx, origy)
     end
-    
+
     # draws a basic table onto the page
     # data   - a 2d array with the data for the columns. The first row will be treated as the headings
     #
@@ -298,23 +314,23 @@ module PDF
       # TODO: instead of accepting the data, use a XHTML table string?
       # TODO: handle overflowing to a new page
       # TODO: add a way to display borders
-      # TODO: raise an error if any unrecognised options were supplied 
 
       x, y = current_point
       options = default_text_options.merge!({:left => x,
                                              :top => y
                                             })
       options.merge!(opts)
+      options.assert_valid_keys(default_text_options.keys + default_positioning_options.keys)
       options[:width] = body_width - options[:left] unless options[:width]
 
-      # move to the start of our table (the top left) 
+      # move to the start of our table (the top left)
       x = options[:left]
       y = options[:top]
       move_to(x,y)
 
       # all columns will have the same width at this stage
       cell_width = options[:width] / data.first.size
-      
+
       # draw the header cells
       y = draw_table_row(data.shift, cell_width, options)
       x = options[:left]
@@ -334,7 +350,7 @@ module PDF
     # the default font styling set by default_font(), default_font_size, etc
     #
     # There is no way to place a bottom bound (or height) onto the text. Text will wrap as
-    # necessary and take all the room it needs. For finer grained control of text boxes, see the 
+    # necessary and take all the room it needs. For finer grained control of text boxes, see the
     # cell method.
     #
     # To override all these defaults, use the options hash
@@ -354,11 +370,11 @@ module PDF
     # <tt>:spacing</tt>::  Space between lines in PDF points
     def text(str, opts={})
       # TODO: add support for pango markup (see http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup)
+      # TODO: add converters from various markup languages to pango markup. (bluecloth, redcloth, markdown, textile, etc)
       # TODO: add a wrap option so wrapping can be disabled
-      # TODO: raise an error if any unrecognised options were supplied 
       #
       # the non pango way to add text to the cairo context, not particularly useful for
-      # PDF generation as it doesn't support wrapping text or other advanced layout features 
+      # PDF generation as it doesn't support wrapping text or other advanced layout features
       # and I really don't feel like re-implementing all that
       # @context.show_text(str)
 
@@ -366,12 +382,13 @@ module PDF
       x, y = current_point
       options = default_text_options.merge!({:left => x, :top => y})
       options.merge!(opts)
+      options.assert_valid_keys(default_text_options.keys + default_positioning_options.keys)
 
       # if the user hasn't specified a width, make the text wrap on the right margin
       options[:width] = absolute_right_margin - options[:left] if options[:width].nil?
 
-      layout = build_pango_layout(str.to_s, options)
-      
+      layout = build_pango_layout(str.to_s, options[:width], options)
+
       set_color(options[:color])
 
       # draw the context on our cairo layout
@@ -382,12 +399,12 @@ module PDF
 
     # Returns the amount of vertical space needed to display the supplied text at the requested width
     # opts is an options hash that specifies various attributes of the text. See the text function for more information.
-    # TODO: raise an error if any unrecognised options were supplied 
     def text_height(str, width, opts = {})
       options = default_text_options.merge!(opts)
       options[:width] = width || body_width
+      options.assert_valid_keys(default_text_options.keys + default_positioning_options.keys)
 
-      layout = build_pango_layout(str.to_s, options)
+      layout = build_pango_layout(str.to_s, options[:width], options)
       width, height = layout.size
 
       return height / Pango::SCALE
@@ -407,23 +424,28 @@ module PDF
     # <tt>:color</tt>::   The colour of the circle outline
     # <tt>:fill_color</tt>::   The colour to fill the circle with. Defaults to nil (no fill)
     def circle(x, y, r, opts = {})
-      # TODO: raise an error if any unrecognised options were supplied 
       options = {:color => @default_color,
                  :fill_color => nil
                  }
       options.merge!(opts)
+      options.assert_valid_keys(:color, :fill_color)
+
+      # save the cursor position so we can restore it at the end
+      origx, origy = current_point
 
       move_to(x + r, y)
 
-      # if the rectangle should be filled in
+      # if the circle should be filled in
       if options[:fill_color]
         set_color(options[:fill_color])
         @context.circle(x, y, r).fill
       end
-      
+
       set_color(options[:color])
       @context.circle(x, y, r).stroke
-      move_to(x + r, y + r)
+
+      # restore the cursor position
+      move_to(origx, origy)
     end
 
     # draw a line from x1,y1 to x2,y2
@@ -431,15 +453,20 @@ module PDF
     # Options:
     # <tt>:color</tt>::   The colour of the line
     def line(x0, y0, x1, y1, opts = {})
-      # TODO: raise an error if any unrecognised options were supplied 
       options = {:color => @default_color }
       options.merge!(opts)
+      options.assert_valid_keys(:color)
+
+      # save the cursor position so we can restore it at the end
+      origx, origy = current_point
 
       set_color(options[:color])
 
       move_to(x0,y0)
       @context.line_to(x1,y1).stroke
-      move_to(x1,y1)
+
+      # restore the cursor position
+      move_to(origx, origy)
     end
 
     # draw a rectangle starting at x,y with w,h dimensions.
@@ -453,22 +480,26 @@ module PDF
     # <tt>:color</tt>::   The colour of the rectangle outline
     # <tt>:fill_color</tt>::   The colour to fill the rectangle with. Defaults to nil (no fill)
     def rectangle(x, y, w, h, opts = {})
-      # TODO: raise an error if any unrecognised options were supplied 
       options = {:color => @default_color,
                  :fill_color => nil
                  }
       options.merge!(opts)
-      
+      options.assert_valid_keys(:color, :fill_color)
+
+      # save the cursor position so we can restore it at the end
+      origx, origy = current_point
+
       # if the rectangle should be filled in
       if options[:fill_color]
         set_color(options[:fill_color])
-        @context.rectangle(x, y, w, h).fill 
+        @context.rectangle(x, y, w, h).fill
       end
-      
+
       set_color(options[:color])
       @context.rectangle(x, y, w, h).stroke
-      
-      move_to(x+w, y+h)
+
+      # restore the cursor position
+      move_to(origx, origy)
     end
 
     # draw a rounded rectangle starting at x,y with w,h dimensions.
@@ -483,24 +514,28 @@ module PDF
     # <tt>:color</tt>::   The colour of the rectangle outline
     # <tt>:fill_color</tt>::   The colour to fill the rectangle with. Defaults to nil (no fill)
     def rounded_rectangle(x, y, w, h, r, opts = {})
-      # TODO: raise an error if any unrecognised options were supplied 
       options = {:color => @default_color,
                  :fill_color => nil
                  }
       options.merge!(opts)
-      
+      options.assert_valid_keys(:color, :fill_color)
+
       raise ArgumentError, "Argument r must be less than both w and h arguments" if r >= w || r >= h
-      
+
+      # save the cursor position so we can restore it at the end
+      origx, origy = current_point
+
       # if the rectangle should be filled in
       if options[:fill_color]
         set_color(options[:fill_color])
-        @context.rounded_rectangle(x, y, w, h, r).fill 
+        @context.rounded_rectangle(x, y, w, h, r).fill
       end
-      
+
       set_color(options[:color])
       @context.rounded_rectangle(x, y, w, h, r).stroke
-      
-      move_to(x+w, y+h)
+
+      # restore the cursor position
+      move_to(origx, origy)
     end
 
     #####################################################
@@ -517,16 +552,18 @@ module PDF
     # <tt>:top</tt>::      The y co-ordinate of the top of the image.
     # <tt>:height</tt>::   The height of the image
     # <tt>:width</tt>::    The width of the image
+    # <tt>:proportional</tt>::   Boolean. Maintain image proportions when scaling. Defaults to false.
     #
     # left and top default to the current cursor location
     # width and height default to the size of the imported image
-    #
-    # if width or height are specified, the image will *not* be scaled proportionally
     def image(filename, opts = {})
-      # TODO: add some options for things like justification, scaling and padding
-      # TODO: raise an error if any unrecognised options were supplied 
-      # TODO: add support for pdf/eps/ps images
+      # TODO: add some options for justification and padding
+      # TODO: add a seperate method for adding arbitary pages from a PDF file to this one. Good for
+      #       templating, etc. Save a letterhead as a PDF file, then open it and add it to the page
+      #       as a starting point. Until we call start_new_page, we can add stuff over the top of the
+      #       imported content
       raise ArgumentError, "file #{filename} not found" unless File.file?(filename)
+      opts.assert_valid_keys(default_positioning_options.keys + [:proportional])
 
       case detect_image_type(filename)
       when :pdf   then draw_pdf filename, opts
@@ -560,9 +597,9 @@ module PDF
       @context.show_page
       @context.target.finish
 
-      # write each line from the StringIO object it was rendered to into the 
+      # write each line from the StringIO object it was rendered to into the
       # requested file
-      File.open(filename, "w") do |of| 
+      File.open(filename, "w") do |of|
         @output.rewind
         @output.each_line { |line| of.write(line) }
       end
@@ -579,54 +616,85 @@ module PDF
       @context.move_to(x,y)
     end
 
-    # reset the cursor by moving it to the top left of the useable section of the page 
+    # reset the cursor by moving it to the top left of the useable section of the page
     def reset_cursor
       @context.move_to(margin_left,margin_top)
     end
 
+    # add the same elements to multiple pages. Useful for adding items like headers, footers and
+    # watermarks.
+    #
+    # arguments:
+    # <tt>spec</tt>::     Which pages to add the items to. :all, :odd, :even, a range, an Array of numbers or an number
+    #
+    # To add text to every page that mentions the page number
+    #   pdf.repeating_element(:all) do
+    #     pdf.text("Page #{pdf.page}!", :left => pdf.margin_left, :top => pdf.margin_top, :font_size => 18)
+    #   end
+    #
+    # To add a circle to the middle of every page
+    #   pdf.repeating_element(:all) do
+    #     pdf.circle(pdf.absolute_x_middle, pdf.absolute_y_middle, 100)
+    #   end
+    def repeating_element(spec = :all, &block)
+      call_repeating_element(spec, block)
+
+      # store it so we can add it to future pages
+      @repeating << {:spec => spec, :block => block}
+    end
+
     # move to the next page
-    def start_new_page
+    #
+    # arguments:
+    # <tt>pageno</tt>::    If specified, the current page number will be set to that. By default, the page number will just increment.
+    def start_new_page(pageno = nil)
       @context.show_page
+
+      # reset or increment the page counter
+      if pageno
+        @page = pageno.to_i
+      else
+        @page += 1
+      end
+
+      # move the cursor to the top left of our page body
       reset_cursor
+
+      # apply the appropriate repeating elements to the new page
+      @repeating.each do |repeat|
+        call_repeating_element(repeat[:spec], repeat[:block])
+      end
     end
 
     private
 
-    def build_pango_layout(str, opts = {})
-      options = {:left => @margin_left,
-                 :top => @margin_top,
-                 :font => @default_font,
-                 :font_size => @default_font_size,
-                 :color => @default_color,
-                 :alignment => :left,
-                 :justify => false,
-                 :spacing => 0
-                }
-      options.merge!(opts)
+    def build_pango_layout(str, w, opts = {})
+      options = default_text_options.merge!(opts)
 
-      # if the user hasn't specified a width, make the text wrap on the right margin
-      options[:width] = absolute_right_margin - options[:left] if options[:width].nil?
+      # if the user hasn't specified a width, make the layout as wide as the page body
+      w = body_width if w.nil?
 
       # even though this is a private function, raise this error to force calling functions
       # to decide how they want to handle converting non-strings into strings for rendering
       raise ArgumentError, 'build_pango_layout must be passed a string' unless str.kind_of?(String)
 
-      # if we're running under a M17n aware VM, ensure the string provided is UTF-8
+      # if we're running under a M17n aware VM, ensure the string provided is UTF-8 or can be
+      # converted to UTF-8
       if RUBY_VERSION >= "1.9"
         begin
           str = str.encode("UTF-8")
         rescue
           raise ArgumentError, 'Strings must be supplied with a UTF-8 encoding, or an encoding that can be converted to UTF-8'
-        end 
+        end
       end
-      
+
       # The pango way:
       load_libpango
 
       # create a new Pango layout that our text will be added to
       layout = @context.create_pango_layout
       layout.text = str.to_s
-      layout.width = options[:width] * Pango::SCALE
+      layout.width = w * Pango::SCALE
       layout.spacing = options[:spacing] * Pango::SCALE
 
       # set the alignment of the text in the layout
@@ -651,6 +719,34 @@ module PDF
       return layout
     end
 
+    # runs the code in block, passing it a hash of options that might be
+    # required
+    def call_repeating_element(spec, block)
+      # TODO: disallow start_new_page when adding a repeating element
+      if spec == :all ||
+         (spec == :even && (page % 2) == 0) ||
+         (spec == :odd && (page % 2) == 1) ||
+         (spec.class == Range && spec.include?(page)) ||
+         (spec.class == Array && spec.include?(page)) ||
+         (spec.respond_to?(:to_i) && spec.to_i == page)
+
+        @context.save do
+          # add it to the current page
+          block.call
+        end
+      end
+    end
+
+    def default_positioning_options
+      # TODO: use these defaults in appropriate places
+      x, y = current_point
+      { :left   => x,
+        :top    => y,
+        :width  => points_to_right_margin(x),
+        :height => points_to_bottom_margin(y)
+      }
+    end
+
     def default_text_options
       { :font => @default_font,
         :font_size => @default_font_size,
@@ -675,26 +771,45 @@ module PDF
         return :pdf
       elsif bytes.include?("<svg")
         return :svg
-      elsif bytes.include?("Exif")
+      elsif bytes.include?("Exif") || bytes.include?("JFIF")
         return :jpg
       else
         return nil
       end
     end
 
+    def calc_image_dimensions(desired_w, desired_h, actual_w, actual_h, scale = false)
+      if scale
+        wp = desired_w / actual_w.to_f
+        hp = desired_h / actual_h.to_f
+
+        if wp < hp
+          width = actual_w * wp
+          height = actual_h * wp
+        else
+          width = actual_w * hp
+          height = actual_h * hp
+        end
+      else
+        width = desired_w || actual_w
+        height = desired_h || actual_h
+      end
+      return width.to_f, height.to_f
+    end
+
     def draw_pdf(filename, opts = {})
       # based on a similar function in rabbit. Thanks Kou.
       load_libpoppler
       x, y = current_point
       page = Poppler::Document.new(filename).get_page(1)
       w, h = page.size
-      width = (opts[:width] || w).to_f
-      height = (opts[:height] || h).to_f
+      width, height = calc_image_dimensions(opts[:width], opts[:height], w, h, opts[:proportional])
       @context.save do
         @context.translate(opts[:left] || x, opts[:top] || y)
         @context.scale(width / w, height / h)
         @context.render_poppler_page(page)
       end
+      move_to(x, y + height)
     end
 
     def draw_pixbuf(filename, opts = {})
@@ -702,28 +817,28 @@ module PDF
       load_libpixbuf
       x, y = current_point
       pixbuf = Gdk::Pixbuf.new(filename)
-      width = (opts[:width] || pixbuf.width).to_f
-      height = (opts[:height] || pixbuf.height).to_f
+      width, height = calc_image_dimensions(opts[:width], opts[:height], pixbuf.width, pixbuf.height, opts[:proportional])
       @context.save do
         @context.translate(opts[:left] || x, opts[:top] || y)
         @context.scale(width / pixbuf.width, height / pixbuf.height)
         @context.set_source_pixbuf(pixbuf, 0, 0)
         @context.paint
       end
+      move_to(x, y + height)
     end
 
     def draw_png(filename, opts = {})
       # based on a similar function in rabbit. Thanks Kou.
       x, y = current_point
       img_surface = Cairo::ImageSurface.from_png(filename)
-      width = (opts[:width] || img_surface.width).to_f
-      height = (opts[:height] || img_surface.height).to_f
+      width, height = calc_image_dimensions(opts[:width], opts[:height], img_surface.width, img_surface.height, opts[:proportional])
       @context.save do
         @context.translate(opts[:left] || x, opts[:top] || y)
         @context.scale(width / img_surface.width, height / img_surface.height)
         @context.set_source(img_surface, 0, 0)
         @context.paint
       end
+      move_to(x, y + height)
     end
 
     def draw_svg(filename, opts = {})
@@ -731,14 +846,14 @@ module PDF
       load_librsvg
       x, y = current_point
       handle = RSVG::Handle.new_from_file(filename)
-      width = (opts[:width] || handle.width).to_f
-      height = (opts[:height] || handle.height).to_f
+      width, height = calc_image_dimensions(opts[:width], opts[:height], handle.width, handle.height, opts[:proportional])
       @context.save do
         @context.translate(opts[:left] || x, opts[:top] || y)
         @context.scale(width / handle.width, height / handle.height)
         @context.render_rsvg_handle(handle)
         #@context.paint
       end
+      move_to(x, y + height)
     end
 
     # adds a single table row to the canvas. Top left of the row will be at the current x,y
@@ -776,13 +891,13 @@ module PDF
           else
             # start a new page if necesary
             if row_height > (absolute_bottom_margin - y)
-              start_new_page 
+              start_new_page
               y = margin_top
             end
 
             # add our cell, then advance x to the left edge of the next cell
             self.cell(head, x, y, column_widths, row_height, opts)
-            x += column_widths 
+            x += column_widths
           end
 
         end
@@ -839,7 +954,7 @@ module PDF
     end
 
     # renders a pango layout onto our main context
-    # based on a function of the same name found in the text2.rb sample file 
+    # based on a function of the same name found in the text2.rb sample file
     # distributed with rcairo - it's still black magic to me and has a few edge
     # cases where it doesn't work too well. Needs to be improved.
     def render_layout(layout, x, y, h, opts = {})
@@ -880,7 +995,7 @@ module PDF
         end
 
         # move to the start of the next line
-        move_to(x, y) 
+        move_to(x, y)
       end
 
       # return the y co-ord we finished on
@@ -893,9 +1008,10 @@ module PDF
       # Cairo and Poppler are both loaded, it breaks.
       Cairo::Color.parse(c).to_rgb.to_a
     end
+
     # set the current drawing colour
     #
-    # for info on what is valid, see the comments for default_color 
+    # for info on what is valid, see the comments for default_color
     def set_color(c)
       c = translate_color(c)
       validate_color(c)
@@ -904,13 +1020,13 @@ module PDF
 
     # test to see if the specified colour is a a valid cairo color
     #
-    # for info on what is valid, see the comments for default_color 
+    # for info on what is valid, see the comments for default_color
     def validate_color(c)
       c = translate_color(c)
       @context.save
       # catch and reraise an exception to keep stack traces readable and clear
       begin
-        raise ArgumentError unless c.kind_of?(Array) 
+        raise ArgumentError unless c.kind_of?(Array)
         raise ArgumentError if c.size != 3 && c.size != 4
         @context.set_source_rgba(c)
       rescue ArgumentError