pdf-wrapper 0.0.7 → 0.1.0

data/CHANGELOG

@@ -1,3 +1,14 @@
+v0.1.0 (28th May 2008)
+- added PDF::Wrapper#translate and PDF::Wrapper#scale
+- fixed a bug that caused some text to be rendered off the page when wrapping onto 3rd and 
+  subsequent pages
+- Improved table support using a new class PDF::Wrapper::Table
+- Added a :center option to Wrapper#image
+- Added a :markup option to text related functions. Pango markup can be used to tweak 
+  text style (bold, italics, super script, etc)
+- Replaced PDF::Wrapper#rounded_rectangle with the :radius option to PDF::Wrapper#rectangle
+- Allow cells to have a border with rounded corners
+
 v0.0.7 (30th April 2008)
 - Added support for creating new pages from a template file (pdf/png/jpg/gif/svg/probably more)
 - Convert the params to start_new_page to be an options hash

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/testtask'
 require "rake/gempackagetask"
 require 'spec/rake/spectask'
 
-PKG_VERSION = "0.0.7"
+PKG_VERSION = "0.1.0"
 PKG_NAME = "pdf-wrapper"
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 
@@ -16,11 +16,11 @@ task :default => [ :spec ]
 # run all rspecs
 desc "Run all rspec files"
 Spec::Rake::SpecTask.new("spec") do |t|
-  #t.spec_files = FileList['specs/**/*_spec.rb']
-  t.spec_files = ['specs/load_spec.rb','specs/image_spec.rb','specs/shapes_spec.rb','specs/text_spec.rb','specs/wrapper_spec.rb']
+  # spec files listed explicitly so that load_spec is the first one run
+  t.spec_files = ['specs/load_spec.rb','specs/image_spec.rb','specs/graphics_spec.rb','specs/tables_spec.rb','specs/text_spec.rb','specs/wrapper_spec.rb']
   t.rcov = true
   t.rcov_dir = (ENV['CC_BUILD_ARTIFACTS'] || 'doc') + "/rcov"
-  t.rcov_opts = ["--exclude","spec.*\.rb","--exclude",".*cairo.*","--exclude",".*rcov.*","--exclude",".*rspec.*","--exclude",".*pdf-reader.*"]
+  t.rcov_opts = ["--exclude","spec.*\.rb","--exclude",".*cairo.*","--exclude",".*rcov.*","--exclude",".*rspec.*","--exclude",".*pdf-reader.*", "--exclude",".*gems.*"]
 end
 
 # generate specdocs

data/examples/cell.rb

@@ -6,5 +6,5 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 require 'pdf/wrapper'
 
 pdf = PDF::Wrapper.new(:paper => :A4)
-pdf.cell("Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction of the layout are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the layout are inserted.", 100, 100, 100, 200, {:border => "", :color => :white, :bgcolor => :black})
+pdf.cell("Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction of the layout are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the layout are inserted.", 100, 100, 100, 200, {:border => "", :color => :black, :radius => 10})
 pdf.render_to_file("wrapper-cell.pdf")

data/examples/image.rb

@@ -6,8 +6,8 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 require 'pdf/wrapper'
 
 pdf = PDF::Wrapper.new(:paper => :A4)
-pdf.default_font("Sans Serif")
-pdf.default_color(:black)
+pdf.font("Sans Serif")
+pdf.color(:black)
 pdf.text("PDF::Wrapper Supports Images", :alignment => :center)
 pdf.image(File.dirname(__FILE__) + "/../specs/data/zits.gif")
 pdf.image(File.dirname(__FILE__) + "/../specs/data/google.png", :left => 100, :top => 350)
@@ -16,6 +16,6 @@ pdf.start_new_page
 pdf.image(File.dirname(__FILE__) + "/../specs/data/orc.svg", :left => pdf.margin_left, :top => pdf.margin_top, :width => pdf.body_width, :height => pdf.body_height)
 pdf.start_new_page
 pdf.image(File.dirname(__FILE__) + "/../specs/data/utf8-long.pdf", :left => pdf.margin_left, :top => pdf.margin_top, :width => pdf.body_width/2, :height => pdf.body_height/2)
-pdf.default_color(:red)
+pdf.color(:red)
 
 pdf.render_to_file("image.pdf")

data/examples/markup.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new(:paper => :A4)
+pdf.font("Sans Serif")
+pdf.color(:black)
+pdf.text "<i>James Healy</i>", :font => "Monospace", :font_size => 16, :alignment => :center, :markup => :pango
+pdf.render_to_file("markup.pdf")

data/examples/repeating.rb

@@ -20,7 +20,7 @@ pdf.repeating_element(:odd) do
 end
 
 pdf.repeating_element([1,2]) do
-  pdf.rounded_rectangle(100, 100, 100, 100, 10)
+  pdf.rectangle(pdf.absolute_x_middle, pdf.absolute_y_middle, 100, 100, :radius => 5)
 end
 
 pdf.repeating_element(3) do

data/examples/scaled.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.line_width = 2
+
+# grid lines
+pdf.line(50, 0, 50, pdf.page_height)
+pdf.line(100, 0, 100, pdf.page_height)
+pdf.line(150, 0, 150, pdf.page_height)
+pdf.line(200, 0, 200, pdf.page_height)
+pdf.line(0, 50, pdf.page_width, 50)
+pdf.line(0, 100, pdf.page_width, 100)
+pdf.line(0, 150, pdf.page_width, 150)
+pdf.line(0, 200, pdf.page_width, 200)
+
+# non scaled
+pdf.rectangle(100,100,100,100, :fill_color => :green)
+
+# scaled
+pdf.scale(pdf.page_width.to_f, pdf.page_height.to_f) do
+  # top left corner 10% of the page width from the left and top of the page. 
+  # width 10% of the page width
+  # height 10% of the page height
+  # - obviously will not be square on a A4 page
+  pdf.rectangle(0.1,0.1,0.1,0.1, :fill_color => :red)
+  pdf.text("boo!", :top => 0.5, :left => 0.2, :width => 0.6)
+end
+
+#pdf.text("boo2!", :top => 500, :left => 100)
+
+
+# show results
+pdf.render_to_file("scaled.pdf")

data/examples/scaled_cells.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new(:paper => :A4)
+pdf.font("Sans Serif")
+pdf.line_width(0.1)
+# naglowek
+pdf.translate(pdf.absolute_left_margin, pdf.absolute_top_margin) do
+  pdf.scale(pdf.body_width, pdf.body_width) do
+    pdf.cell("Exorigo", 0, 0, 0.2, 0.05, :alignment => :center, :font_size => 15)
+    pdf.cell("Zamówienie nr PO/0000/01/01/2008", 0.2, 0, 0.8, 0.05, :fill_color => :gray, :alignment => :center)
+    pdf.cell("imię i naziwsko osoby zamawiającej. NALEŻY PODAĆ NA FAKTURZE", 0, 0.05, 0.55, 0.025, :font_size => 6)
+    pdf.cell("data zamówienia", 0.55, 0.05, 0.15, 0.025, :font_size => 6)
+    pdf.cell("POWYŻSZY NUMER ZAMÓWIENIA NALEŻY PODAĆ NA FAKTURZE", 0.7, 0.05, 0.3, 0.05, :font_size => 6, :alignment => :center, :spacing => 4)
+    pdf.cell("Jan Kowalski", 0, 0.075, 0.55, 0.025, :font => "Sans Serif bold", :font_size => 8)
+    pdf.cell("22.01.2008", 0.55, 0.075, 0.15, 0.025, :font => "Sans Serif bold", :font_size => 8)
+  end
+end
+# dane dostawcy
+
+# szczegoly zamowienia
+
+# autoryzacja
+
+# adres
+pdf.render_to_file("scaled-cells.pdf")

data/examples/scaled_image.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new(:paper => :A4)
+pdf.image(File.dirname(__FILE__) + "/../specs/data/zits.gif",     :top => 100, :height => 200, :width => 200, :proportional => true, :center => true)
+pdf.rectangle(pdf.margin_left, 100, 200, 200)
+pdf.image(File.dirname(__FILE__) + "/../specs/data/windmill.jpg", :top => 400, :height => 200, :width => 200, :proportional => true, :center => true)
+pdf.rectangle(pdf.margin_left, 400, 200, 200)
+
+pdf.render_to_file("scaled_image.pdf")

data/examples/shapes.rb

@@ -9,5 +9,5 @@ pdf = PDF::Wrapper.new(:paper => :A4)
 pdf.rectangle(30,30,100,100, :fill_color => :red)
 pdf.circle(100,300,30)
 pdf.line(100, 350, 400, 150)
-pdf.rounded_rectangle(300,300, 200, 200, 10, :fill_color => :green)
+pdf.rectangle(300,300, 200, 200, :fill_color => :green, :radius => 10)
 pdf.render_to_file("shapes.pdf")

data/examples/table.rb

@@ -6,13 +6,34 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 require 'pdf/wrapper'
 
 pdf = PDF::Wrapper.new(:paper => :A4)
-pdf.text "Chunky Bacon!!"
-data = [%w{one two three four}]
+pdf.text File.read(File.dirname(__FILE__) + "/../specs/data/utf8.txt").strip, :alignment => :centre
+pdf.pad 5
+headers = %w{one two three four}
 
-data << ["This is some longer text to ensure that the cell wraps",2,3,4]
+data = []
+data << ["This is some longer text to ensure that the cell wraps","oh noes! the cols can't get the width they desire",3,4]
+data << ["This is some longer text to ensure that the cell wraps","oh noes! the cols can't get the width they desire",3,4]
+
+data << [[], "j", "a", "m"]
 
 (1..100).each do
   data << %w{1 2 3 4}
 end
-pdf.table(data, :font_size => 10)
+
+table = PDF::Wrapper::Table.new do |t|
+  t.data = data
+  t.headers = headers
+  t.table_options :font_size => 10
+  t.header_options :color => :white, :fill_color => :black
+  t.row_options 6, {:border => "t"}
+  t.row_options :even, {:fill_color => :gray}
+  t.col_options 0, {:border => "tb"}
+  t.col_options 1, {:alignment => :centre}
+  t.col_options 2, {:alignment => :centre}
+  t.col_options 3, {:alignment => :centre, :border => "tb"}
+  t.col_options :even, {:fill_color => :blue}
+  t.cell_options 3, 3, {:fill_color => :green}
+end
+
+pdf.table(table)
 pdf.render_to_file("table.pdf")

data/examples/translate.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+@pdf = PDF::Wrapper.new(:paper => :A4)
+
+def captioned_image(filename, caption, x, y)
+  @pdf.translate(x, y) do
+    @pdf.image(filename, :top => 0, :left => 0, :height => 100, :width => 100, :proportional => true)
+    @pdf.text("Image Caption", :top => 110, :left => 0)
+  end
+end
+
+captioned_image(File.dirname(__FILE__) + "/../specs/data/orc.svg", "One", 100, 100)
+captioned_image(File.dirname(__FILE__) + "/../specs/data/orc.svg", "Two", 250, 300)
+captioned_image(File.dirname(__FILE__) + "/../specs/data/orc.svg", "Three", 400, 500)
+
+@pdf.render_to_file("translate.pdf")

data/examples/utf8-long.rb

@@ -6,7 +6,6 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 require 'pdf/wrapper'
 
 pdf = PDF::Wrapper.new(:paper => :A4)
-pdf.default_font("Sans Serif")
-pdf.default_color(:black)
+pdf.font("Sans Serif")
 pdf.text File.read(File.dirname(__FILE__) + "/../specs/data/utf8-long.txt"), :font => "Monospace", :font_size => 8
 pdf.render_to_file("utf8-long.pdf")

data/examples/utf8.rb

@@ -6,7 +6,6 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 require 'pdf/wrapper'
 
 pdf = PDF::Wrapper.new(:paper => :A4)
-pdf.default_font("Sans Serif")
-pdf.default_color(:black)
+pdf.font("Sans Serif")
 pdf.text File.read(File.dirname(__FILE__) + "/../specs/data/utf8.txt"), :font => "Monospace", :font_size => 8, :alignment => :center
 pdf.render_to_file("wrapper.pdf")

data/lib/pdf/core.rb

@@ -7,4 +7,27 @@ class Hash
     unknown_keys = keys - [valid_keys].flatten
     raise(ArgumentError, "Unknown key(s): #{unknown_keys.join(", ")}") unless unknown_keys.empty?
   end
+
+  def only(*keys)
+    keys.flatten!
+    self.dup.reject { |k,v|
+      !keys.include? k.to_sym
+    }
+  end
+end
+
+unless [].respond_to?(:sum)
+
+  module Enumerable
+    # borrowed from active support. No need to pull that entire beast in as a dependency
+    def sum(identity = 0, &block)
+      return identity unless size > 0
+
+      if block_given?
+        map(&block).sum
+      else
+        inject { |sum, element| sum + element }
+      end
+    end
+  end
 end

data/lib/pdf/wrapper.rb

@@ -3,6 +3,12 @@
 require 'stringio'
 require 'pdf/core'
 
+require File.dirname(__FILE__) + "/wrapper/graphics"
+require File.dirname(__FILE__) + "/wrapper/images"
+require File.dirname(__FILE__) + "/wrapper/loading"
+require File.dirname(__FILE__) + "/wrapper/table"
+require File.dirname(__FILE__) + "/wrapper/text"
+
 # try to load cairo from the standard places, but don't worry if it fails,
 # we'll try to find it via rubygems
 begin
@@ -40,14 +46,13 @@ module PDF
   #
   #   require 'pdf/wrapper'
   #   pdf = PDF::Wrapper.new(:paper => :A4)
-  #   pdf.default_font("Monospace")
+  #   pdf.font("Monospace")
   #   pdf.text "Hello World", :font => "Sans Serif", :font_size => 18
   #   pdf.text "Pretend this is a code sample"
   #   puts pdf.render
   class Wrapper
 
-    attr_reader :margin_left, :margin_right, :margin_top, :margin_bottom
-    attr_reader :page_width, :page_height, :page
+    attr_reader :page
 
     # borrowed from PDF::Writer
     PAGE_SIZES = { # :value {...}:
@@ -87,10 +92,20 @@ module PDF
     # <tt>:margin_bottom</tt>::   The size of the default bottom margin (default 5% of page)
     # <tt>:margin_left</tt>::   The size of the default left margin (default 5% of page)
     # <tt>:margin_right</tt>::   The size of the default right margin (default 5% of page)
-    # <tt>:template</tt>::  The path to an image file. If specified, the first page of the document will use the specified image as a template. 
+    # <tt>:template</tt>::  The path to an image file. If specified, the first page of the document will use the specified image as a template.
     #                       The page will be sized to match the template size. The use templates on subsequent pages, see the options for
     #                       start_new_page.
     def initialize(opts={})
+      # TODO: Investigate ways of using the cairo transform/translate/scale functionality to
+      #       reduce the amount of irritating co-ordinate maths the user of PDF::Wrapper (ie. me!)
+      #       is required to do.
+      #       - translate the pdf body width so that it's 1.0 wide and 1.0 high?
+      # TODO: find a way to add metadata (title, author, subject, etc) to the output file
+      #       currently no way to specify this in cairo.
+      #       tentatively scheduled for cairo 1.8 - see:
+      #       - http://cairographics.org/roadmap/
+      #       - http://lists.cairographics.org/archives/cairo/2007-September/011441.html
+      #       - http://lists.freedesktop.org/archives/cairo/2006-April/006809.html
 
       # ensure we have recentish cairo bindings
       raise "Ruby Cairo bindings version #{Cairo::BINDINGS_VERSION.join(".")} is too low. At least 1.5 is required" if Cairo::BINDINGS_VERSION.to_s < "150"
@@ -129,14 +144,14 @@ module PDF
       @context = Cairo::Context.new(@surface)
 
       # set the background colour
-      set_color(options[:background_color])
+      color(options[:background_color])
       @context.paint
 
       # set a default drawing colour and font style
-      default_color(:black)
-      default_line_width(2.0)
-      default_font("Sans Serif")
-      default_font_size(16)
+      color(:black)
+      line_width(0.5)
+      font("Sans Serif")
+      font_size(16)
 
       # maintain a count of pages and array of repeating elements to add to each page
       @page = 1
@@ -160,499 +175,165 @@ module PDF
     # Returns the x value of the left margin
     # The top left corner of the page is (0,0)
     def absolute_left_margin
-      @margin_left
+      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
-      @page_width - @margin_right
+      page_width - margin_right
     end
 
     # Returns the y value of the top margin
     # The top left corner of the page is (0,0)
     def absolute_top_margin
-      @margin_top
+      margin_top
     end
 
     # Returns the y value of the bottom margin
     # The top left corner of the page is (0,0)
     def absolute_bottom_margin
-      @page_height - @margin_bottom
+      page_height - margin_bottom
     end
 
     # Returns the x at the middle of the page
     def absolute_x_middle
-      @page_width / 2
+      page_width / 2
     end
 
     # Returns the y at the middle of the page
     def absolute_y_middle
-      @page_height / 2
+      page_height / 2
     end
 
     # Returns the width of the usable part of the page (between the side margins)
     def body_width
-      @page_width - @margin_left - @margin_right
+      device_x_to_user_x(@page_width - @margin_left - @margin_right)
     end
 
     # Returns the height of the usable part of the page (between the top and bottom margins)
     def body_height
-      @page_height - @margin_top - @margin_bottom
+      #@context.device_to_user(@page_width - @margin_left - @margin_right, @page_height - @margin_top - @margin_bottom).last
+      device_y_to_user_y(@page_height - @margin_top - @margin_bottom)
     end
 
     # Returns the x coordinate of the middle part of the usable space between the margins
-    def margin_x_middle
-      @margin_left + (body_width / 2)
+    def body_x_middle
+      margin_left + (body_width / 2)
     end
 
     # Returns the y coordinate of the middle part of the usable space between the margins
-    def margin_y_middle
-      @margin_top + (body_height / 2)
+    def body_y_middle
+      margin_top + (body_height / 2)
+    end
+
+    def page_height
+      device_y_to_user_y(@page_height)
+    end
+
+    def page_width
+      device_x_to_user_x(@page_width)
     end
 
     # return the current position of the cursor
     # returns 2 values - x,y
     def current_point
-      return @context.current_point
+      @context.current_point
     end
 
-    # return the number of points from  starty to the bottom border
-    def points_to_bottom_margin(starty)
-      absolute_bottom_margin - starty
+    def margin_bottom
+      device_y_to_user_y(@margin_bottom).to_i
     end
 
-    # return the number of points from  startx to the right border
-    def points_to_right_margin(startx)
-      absolute_right_margin - startx
+    def margin_left
+      device_x_to_user_x(@margin_left).to_i
     end
 
-    #####################################################
-    # Functions relating to working with text
-    #####################################################
-
-    # change the default font size
-    def default_font_size(size)
-      #@context.set_font_size(size.to_i)
-      @default_font_size = size.to_i unless size.nil?
+    def margin_right
+      device_x_to_user_x(@margin_right).to_i
     end
-    alias default_font_size= default_font_size
-    alias font_size default_font_size          # PDF::Writer compatibility
-
-    # change the default font to write with
-    def default_font(fontname, style = nil, weight = nil)
-      #@context.select_font_face(fontname, slant, bold)
-      @default_font = fontname
-      @default_font_style = style unless style.nil?
-      @default_font_weight = weight unless weight.nil?
-    end
-    alias default_font= default_font
-    alias select_font default_font   # PDF::Writer compatibility
 
-    # change the default colour used to draw on the canvas
-    #
-    # 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
-    #               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)
-      validate_color(c)
-      @default_color = c
+    def margin_top
+      device_y_to_user_y(@margin_top).to_i
     end
-    alias default_color= default_color
-    alias stroke_color default_color    # PDF::Writer compatibility
 
-    # change the default line width used to draw stroke on the canvas
-    #
-    # Parameters:
-    # <tt>f</tt>:: float value of stroke width from 0.01 to 255
-    def default_line_width(f)
-      @default_line_width = f
+    # return the number of points from  starty to the bottom border
+    def points_to_bottom_margin(starty)
+      absolute_bottom_margin - starty
     end
-    alias default_line_width= default_line_width
 
-    # add text to the page, bounded by a box with dimensions HxW, with it's top left corner
-    # at x,y. Any text that doesn't fit it the box will be silently dropped.
-    #
-    # In addition to the standard text style options (see the documentation for text()), cell() supports
-    # 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_color</tt>::  What color should the border be?
-    # <tt>:fill_color</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: 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 => @default_line_width, :border_color => :black,  :fill_color => nil, :padding => 3})
-      options.merge!(opts)
-      options.assert_valid_keys(default_text_options.keys + [:width, :border, :border_width, :border_color, :fill_color, :padding])
-
-      # apply padding
-      textw = w - (options[:padding] * 2)
-      texth = h - (options[:padding] * 2)
-      textx = x + options[:padding]
-      texty = y + options[:padding]
-
-      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[:fill_color], :fill_color => options[:fill_color]) if options[:fill_color]
-      layout = build_pango_layout(str.to_s, textw, options)
-
-      set_color(options[:color])
-
-      # draw the context on our cairo layout
-      render_layout(layout, textx, texty, texth, :auto_new_page => false)
-
-      # draw a border around the cell
-      line(x,y,x+w,y, :color => options[:border_color], :line_width => options[:border_width])     if options[:border].include?("t")
-      line(x,y+h,x+w,y+h, :color => options[:border_color], :line_width => options[:border_width]) if options[:border].include?("b")
-      line(x,y,x,y+h, :color => options[:border_color], :line_width => options[:border_width])     if options[:border].include?("l")
-      line(x+w,y,x+w,y+h, :color => options[:border_color], :line_width => options[:border_width]) if options[:border].include?("r")
-
-      # restore the cursor position
-      move_to(origx, origy)
+    # return the number of points from  startx to the right border
+    def points_to_right_margin(startx)
+      absolute_right_margin - startx
     end
 
-    # draws a basic table onto the page
+    # Set a new location to be the origin (0,0). This is useful for repetitive tasks
+    # where objects need to be added to the canvas at regular offsets, and can save
+    # a significant amount of irritating co-ordinate maths.
     #
-    # <tt>data</tt>:: a 2d array with the data for the columns. The first row will be treated as the headings
+    # As an example, consider the following code fragment. If you have a series of images
+    # to arrange on a page with identical sizes, translate can help keep the code clean
+    # and readable by reducing (or removing completely) the need to perform a series of
+    # basic sums to calculate the correct offsets, etc.
     #
-    # In addition to the standard text style options (see the documentation for text), table supports
-    # the following options:
+    #   def captioned_image(filename, caption, x, y)
+    #     @pdf.translate(x, y) do
+    #       @pdf.image(filename, :top => 0, :left => 0, :height => 100, :width => 100, :proportional => true)
+    #       @pdf.text(caption, :top => 110, :left => 0, :width => 100)
+    #     end
+    #   end
     #
-    # <tt>:left</tt>::   The x co-ordinate of the left-hand side of the table. Defaults to the left margin
-    # <tt>:top</tt>::   The y co-ordinate of the top of the text. Defaults to the top margin
-    # <tt>:width</tt>::   The width of the table. Defaults to the width of the page body
-    def table(data, opts = {})
-      # 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
-
-      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)
-      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]
-      move_to(x,y)
-
-      # draw the data cells
-      data.each do |row|
-        y = draw_table_row(row, cell_width, options)
-        x = options[:left]
-        move_to(x,y)
+    #   captioned_image("orc.svg", "Orc", 100, 100)
+    #   captioned_image("hobbit.svg", "Hobbit", 100, 400)
+    #   captioned_image("elf.svg", "Elf", 100, 400)
+    def translate(x, y, &block)
+      @context.save do
+        @context.translate(x, y)
+        yield
       end
     end
 
-    # Write text to the page
-    #
-    # By default the text will be rendered using all the space within the margins and using
-    # 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
-    # cell method.
-    #
-    # To override all these defaults, use the options hash
+    # all code wrapped in the block passed to this function will have co-ordinates
+    # and distances (width/height) multiplied by these values before being used
     #
-    # Positioning Options:
+    # Divide everything by 2
     #
-    # <tt>:left</tt>::   The x co-ordinate of the left-hand side of the text.
-    # <tt>:top</tt>::   The y co-ordinate of the top of the text.
-    # <tt>:width</tt>::   The width of the text to wrap at
+    #   pdf.scale(0.5, 0.5) do
+    #     ...
+    #   end
     #
-    # Text Style Options:
+    # Make the page 1.0 wide and 1.0 tall, so co-ordinates and distances
+    # can be specified as percentages (0.5 == 50%, etc)
     #
-    # <tt>:font</tt>::   The font family to use as a string
-    # <tt>:font_size</tt>::   The size of the font in points
-    # <tt>:alignment</tt>::   Align the text along the left, right or centre. Use :left, :right, :center
-    # <tt>:justify</tt>::   Justify the text so it exapnds to fill the entire width of each line. Note that this only works in pango >= 1.17
-    # <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
-      #
-      # 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
-      # and I really don't feel like re-implementing all that
-      # @context.show_text(str)
-
-      # the "pango way"
-      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[:width], options)
-
-      set_color(options[:color])
-
-      # draw the context on our cairo layout
-      y = render_layout(layout, options[:left], options[:top], points_to_bottom_margin(options[:top]), :auto_new_page => true)
-
-      move_to(options[:left], y + 5)
-    end
-
-    # 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.
-    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[:width], options)
-      width, height = layout.size
-
-      return height / Pango::SCALE
-    end
-
-    # Returns the amount of horizontal space needed to display the supplied text with the requested options
-    # opts is an options hash that specifies various attributes of the text. See the text function for more information.
-    # The text is assumed to not wrap.
-    def text_width(str, opts = {})
-      options = default_text_options.merge!(opts)
-      options.assert_valid_keys(default_text_options.keys)
-
-      layout = build_pango_layout(str.to_s, -1, options)
-      width, height = layout.size
-
-      return width / Pango::SCALE
-    end
-
-    #####################################################
-    # Functions relating to working with graphics
-    #####################################################
-
-    # draw a circle with radius r and a centre point at (x,y).
-    # Parameters:
-    # <tt>:x</tt>::   The x co-ordinate of the circle centre.
-    # <tt>:y</tt>::   The y co-ordinate of the circle centre.
-    # <tt>:r</tt>::   The radius of the circle
+    #   pdf.scale(pdf.page_width.to_f, pdf.page_height.to_f) do
+    #     ...
+    #   end
     #
-    # Options:
-    # <tt>:color</tt>::   The colour of the circle outline
-    # <tt>:line_width</tt>::   The width of outline. Defaults to 2.0
-    # <tt>:fill_color</tt>::   The colour to fill the circle with. Defaults to nil (no fill)
-    def circle(x, y, r, opts = {})
-      options = {:color => @default_color,
-                 :line_width => @default_line_width,
-                 :fill_color => nil
-                 }
-      options.merge!(opts)
-      options.assert_valid_keys(:color, :line_width, :fill_color)
-
-      # save the cursor position so we can restore it at the end
-      origx, origy = current_point
-
-      move_to(x + r, y)
+    def scale(w, h, &block)
+      @context.save do
+        @context.scale(w, h)
 
-      # if the circle should be filled in
-      if options[:fill_color]
-        set_color(options[:fill_color])
-        @context.circle(x, y, r).fill
+        # set the line width again so that it's set relative to the current
+        # scale factor
+        line_width @line_width
+        yield
       end
-
-      set_color(options[:color])
-      @context.set_line_width(options[:line_width])
-      @context.circle(x, y, r).stroke
-
-      # restore the cursor position
-      move_to(origx, origy)
     end
 
-    # draw a line from x1,y1 to x2,y2
-    #
-    # Options:
-    # <tt>:color</tt>::   The colour of the line
-    # <tt>:line_width</tt>::   The width of line. Defaults its 2.0
-    def line(x0, y0, x1, y1, opts = {})
-      options = {:color => @default_color, :line_width => @default_line_width }
-      options.merge!(opts)
-      options.assert_valid_keys(:color, :line_width)
-
-      # save the cursor position so we can restore it at the end
-      origx, origy = current_point
-
-      set_color(options[:color])
-      @context.set_line_width(options[:line_width])
-      move_to(x0,y0)
-      @context.line_to(x1,y1).stroke
-
-      # restore the cursor position
-      move_to(origx, origy)
-    end
-
-    # Adds a cubic Bezier spline to the path from the  (x0, y0) to position (x3, y3)
-    # in user-space coordinates, using (x1, y1) and (x2, y2) as the control points.
-    # Options:
-    # <tt>:color</tt>::   The colour of the line
-    # <tt>:line_width</tt>::   The width of line. Defaults to 2.0
-    def curve(x0, y0, x1, y1, x2, y2, x3, y3, opts = {})
-      options = {:color => @default_color, :line_width => @default_line_width }
-      options.merge!(opts)
-      options.assert_valid_keys(:color, :line_width)
-      origx, origy = current_point
-
-      set_color(options[:color])
-      @context.set_line_width(options[:line_width])
-      move_to(x0,y0)
-      @context.curve_to(x1, y1, x2, y2, x3, y3).stroke
-
-      # restore the cursor position
-      move_to(origx, origy)
-    end
-
-
-    # draw a rectangle starting at x,y with w,h dimensions.
-    # Parameters:
-    # <tt>:x</tt>::   The x co-ordinate of the top left of the rectangle.
-    # <tt>:y</tt>::   The y co-ordinate of the top left of the rectangle.
-    # <tt>:w</tt>::   The width of the rectangle
-    # <tt>:h</tt>::   The height of the rectangle
+    # change the default colour used to draw on the canvas
     #
-    # Options:
-    # <tt>:color</tt>::   The colour of the rectangle outline
-    # <tt>:line_width</tt>::   The width of outline. Defaults to 2.0
-    # <tt>:fill_color</tt>::   The colour to fill the rectangle with. Defaults to nil (no fill)
-    def rectangle(x, y, w, h, opts = {})
-      options = {:color => @default_color,
-                 :line_width => @default_line_width,
-                 :fill_color => nil
-                 }
-      options.merge!(opts)
-      options.assert_valid_keys(:color, :line_width, :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
-      end
-
-      set_color(options[:color])
-      @context.set_line_width(options[:line_width])
-      @context.rectangle(x, y, w, h).stroke
-
-      # restore the cursor position
-      move_to(origx, origy)
-    end
-
-    # draw a rounded rectangle starting at x,y with w,h dimensions.
     # Parameters:
-    # <tt>:x</tt>::   The x co-ordinate of the top left of the rectangle.
-    # <tt>:y</tt>::   The y co-ordinate of the top left of the rectangle.
-    # <tt>:w</tt>::   The width of the rectangle
-    # <tt>:h</tt>::   The height of the rectangle
-    # <tt>:r</tt>::   The size of the rounded corners
-    #
-    # Options:
-    # <tt>:color</tt>::   The colour of the rectangle outline
-    # <tt>:line_width</tt>::   The width of outline. Defaults to 2.0
-    # <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 = {})
-      options = {:color => @default_color,
-                 :line_width => @default_line_width,
-                 :fill_color => nil
-                 }
-      options.merge!(opts)
-      options.assert_valid_keys(:color, :fill_color, :line_width)
-
-      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
-      end
-
-      set_color(options[:color])
-      @context.set_line_width(options[:line_width])
-      @context.rounded_rectangle(x, y, w, h, r).stroke
-
-      # restore the cursor position
-      move_to(origx, origy)
-    end
-
-    #####################################################
-    # Functions relating to working with images
-    #####################################################
-
-    # add an image to the page - a wide range of image formats are supported,
-    # including svg, jpg, png and gif. PDF images are also supported - an attempt
-    # to add a multipage PDF will result in only the first page appearing in the
-    # new document.
-    #
-    # supported options:
-    # <tt>:left</tt>::     The x co-ordinate of the left-hand side of the image.
-    # <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.
-    # <tt>:padding</tt>::    Add some padding between the image and the specified box.
-    #
-    # left and top default to the current cursor location
-    # width and height default to the size of the imported image
-    # padding defaults to 0
-    def image(filename, opts = {})
-      # TODO: add some options for justification and padding
-      raise ArgumentError, "file #{filename} not found" unless File.file?(filename)
-      opts.assert_valid_keys(default_positioning_options.keys + [:padding, :proportional])
-
-      if opts[:padding]
-        opts[:left]   += opts[:padding].to_i if opts[:left]
-        opts[:top]    += opts[:padding].to_i if opts[:top]
-        opts[:width]  -= opts[:padding].to_i * 2 if opts[:width]
-        opts[:height] -= opts[:padding].to_i * 2 if opts[:height]
-      end
-
-      case detect_image_type(filename)
-      when :pdf   then draw_pdf filename, opts
-      when :png   then draw_png filename, opts
-      when :svg   then draw_svg filename, opts
-      else
-        begin
-          draw_pixbuf filename, opts
-        rescue Gdk::PixbufError
-          raise ArgumentError, "Unrecognised image format (#{filename})"
-        end
-      end
+    # <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
+    #               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 color(c)
+      c = translate_color(c)
+      validate_color(c)
+      @context.set_source_rgba(*c)
     end
+    alias color= color
 
     #####################################################
     # Functions relating to generating the final document
@@ -693,8 +374,6 @@ module PDF
 
     # move the cursor to an arbitary position on the current page
     def move_to(x,y)
-      raise ArgumentError, 'x cannot be larger than the width of the page' if x > page_width
-      raise ArgumentError, 'y cannot be larger than the height of the page' if y > page_height
       @context.move_to(x,y)
     end
 
@@ -761,61 +440,6 @@ module PDF
 
     private
 
-    def build_pango_layout(str, w, opts = {})
-      options = default_text_options.merge!(opts)
-
-      # 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 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
-
-      # 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
-      if w == -1
-        layout.width = -1
-      else
-        layout.width = w * Pango::SCALE
-      end
-      layout.spacing = options[:spacing] * Pango::SCALE
-
-      # set the alignment of the text in the layout
-      if options[:alignment].eql?(:left)
-        layout.alignment = Pango::Layout::ALIGN_LEFT
-      elsif options[:alignment].eql?(:right)
-        layout.alignment = Pango::Layout::ALIGN_RIGHT
-      elsif options[:alignment].eql?(:center) || options[:alignment].eql?(:centre)
-        layout.alignment = Pango::Layout::ALIGN_CENTER
-      else
-        raise ArgumentError, "Invalid alignment requested"
-      end
-
-      # justify the text if need be - only works in pango >= 1.17
-      layout.justify = true if options[:justify]
-
-      # setup the font that will be used to render the text
-      fdesc = Pango::FontDescription.new(options[:font])
-      fdesc.set_size(options[:font_size] * Pango::SCALE)
-      layout.font_description = fdesc
-      @context.update_pango_layout(layout)
-      return layout
-    end
-
     # runs the code in block, passing it a hash of options that might be
     # required
     def call_repeating_element(spec, block)
@@ -844,299 +468,51 @@ module PDF
       }
     end
 
-    def default_text_options
-      { :font => @default_font,
-        :font_size => @default_font_size,
-        :color => @default_color,
-        :alignment => :left,
-        :justify => false,
-        :spacing => 0
-      }
-    end
-
-    def detect_image_type(filename)
-      # read the first Kb from the file to attempt file type detection
-      f = File.new(filename)
-      bytes = f.read(1024)
-
-      # if the file is a PNG
-      if bytes[1,3].eql?("PNG")
-        return :png
-      elsif bytes[0,3].eql?("GIF")
-        return :gif
-      elsif bytes[0,4].eql?("%PDF")
-        return :pdf
-      elsif bytes.include?("<svg")
-        return :svg
-      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, 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(opts[:left] || x, (opts[:top] || y) + height)
-    end
-
-    def draw_pixbuf(filename, opts = {})
-      # based on a similar function in rabbit. Thanks Kou.
-      load_libpixbuf
-      x, y = current_point
-      pixbuf = Gdk::Pixbuf.new(filename)
-      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(opts[:left] || x, (opts[:top] || 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, 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(opts[:left] || x, (opts[:top] || y) + height)
+    # save and restore the cursor position around a block
+    def save_coords(&block)
+      origx, origy = current_point
+      yield
+      move_to(origx, origy)
     end
 
-    def draw_svg(filename, opts = {})
-      # based on a similar function in rabbit. Thanks Kou.
-      load_librsvg
-      x, y = current_point
-      handle = RSVG::Handle.new_from_file(filename)
-      width, height = calc_image_dimensions(opts[:width], opts[:height], handle.width, handle.height, opts[:proportional])
+    # save and restore the cursor position and graphics state around a block
+    def save_coords_and_state(&block)
+      origx, origy = current_point
       @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(opts[:left] || x, (opts[:top] || y) + height)
-    end
-
-    # adds a single table row to the canvas. Top left of the row will be at the current x,y
-    # co-ordinates, so make sure they're set correctly before calling this function
-    #
-    # strings - array of strings. Each element of the array is a cell
-    # column_widths - the width of each column. At this stage it should be an int. All columns are the same width
-    # options - any options relating to text style to use. font, font_size, alignment, etc. See text() for more info.
-    #
-    # Returns the y co-ordinates of the bottom edge of the row, ready for the next row
-    def draw_table_row(strings, column_widths, options)
-      row_height = 0
-      x, y = current_point
-
-      # we run all this code twice. The first time is a dry run to calculate the
-      # height of the largest cell, which determines the overall height of the row.
-      # The second run through we actually draw each cell onto the canvas
-      [:dry, :paint].each do |action|
-
-        strings.each do |head|
-          # TODO: provide a way for these to be overridden on a per cell basis
-          opts = {
-            :font      => options[:font],
-            :font_size => options[:font_size],
-            :color     => options[:color],
-            :alignment => options[:alignment],
-            :justify   => options[:justify],
-            :spacing   => options[:spacing]
-          }
-
-          if action == :dry
-            # calc the cell height, and set row_height if this cell is the biggest in the row
-            cell_height = text_height(head, column_widths, opts)
-            row_height = cell_height if cell_height > row_height
-          else
-            # start a new page if necesary
-            if row_height > (absolute_bottom_margin - y)
-              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
-          end
-
-        end
-      end
-
-      return y + row_height
-    end
-
-    def image_dimensions(filename)
-      raise ArgumentError, "file #{filename} not found" unless File.file?(filename)
-
-      case detect_image_type(filename)
-      when :pdf   then
-        load_libpoppler
-        page = Poppler::Document.new(filename).get_page(1)
-        return page.size
-      when :png   then
-        img_surface = Cairo::ImageSurface.from_png(filename)
-        return img_surface.width, img_surface.height
-      when :svg   then
-        load_librsvg
-        handle = RSVG::Handle.new_from_file(filename)
-        return handle.width, handle.height
-      else
-        load_libpixbuf
-        begin
-          pixbuf = Gdk::Pixbuf.new(filename)
-          return pixbuf.width, pixbuf.height
-        rescue Gdk::PixbufError
-          raise ArgumentError, "Unrecognised image format (#{filename})"
-        end
+        yield
       end
+      move_to(origx, origy)
     end
 
-    # load libpango if it isn't already loaded.
-    # This will add some methods to the cairo Context class in addition to providing
-    # its own classes and constants. A small amount of documentation is available at
-    # http://ruby-gnome2.sourceforge.jp/fr/hiki.cgi?Cairo%3A%3AContext#Pango+related+APIs
-    def load_libpango
-      begin
-        require 'pango' unless @context.respond_to? :create_pango_layout
-      rescue LoadError
-        raise LoadError, 'Ruby/Pango library not found. Visit http://ruby-gnome2.sourceforge.jp/'
-      end
+    def translate_color(c)
+      # the follow line converts a color definition from various formats (hex, symbol, etc)
+      # into a 4 item array. This is normally handled within cairo itself, however when
+      # Cairo and Poppler are both loaded, it breaks.
+      Cairo::Color.parse(c).to_rgb.to_a
     end
 
-    # load lib gdkpixbuf if it isn't already loaded.
-    # This will add some methods to the cairo Context class in addition to providing
-    # its own classes and constants.
-    def load_libpixbuf
-      begin
-        require 'gdk_pixbuf2' unless @context.respond_to? :set_source_pixbuf
-      rescue LoadError
-        raise LoadError, 'Ruby/GdkPixbuf library not found. Visit http://ruby-gnome2.sourceforge.jp/'
-      end
+    def user_to_device_dist(x,y)
+      @context.user_to_device_distance(x, y)
     end
 
-    # load lib poppler if it isn't already loaded.
-    # This will add some methods to the cairo Context class in addition to providing
-    # its own classes and constants.
-    def load_libpoppler
-      begin
-        require 'poppler' unless @context.respond_to? :render_poppler_page
-      rescue LoadError
-        raise LoadError, 'Ruby/Poppler library not found. Visit http://ruby-gnome2.sourceforge.jp/'
-      end
+    def user_x_to_device_x(x)
+      @context.user_to_device(x, 0).first.abs
     end
 
-    # load librsvg if it isn't already loaded
-    # This will add an additional method to the Cairo::Context class
-    # that allows an existing SVG to be drawn directly onto it
-    # There's a *little* bit of documentation at:
-    # http://ruby-gnome2.sourceforge.jp/fr/hiki.cgi?Cairo%3A%3AContext#render_rsvg_handle
-    def load_librsvg
-      begin
-        require 'rsvg2' unless @context.respond_to? :render_svg_handle
-      rescue LoadError
-        raise LoadError, 'Ruby/RSVG library not found. Visit http://ruby-gnome2.sourceforge.jp/'
-      end
+    def user_y_to_device_y(y)
+      @context.user_to_device(0, y).last.abs
     end
 
-    # renders a pango layout onto our main context
-    # 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 = {})
-      # we can't use context.show_pango_layout, as that won't start
-      # a new page if the layout hits the bottom margin. Instead,
-      # we iterate over each line of text in the layout and add it to
-      # the canvas, page breaking as necessary
-      options = {:auto_new_page => true }
-      options.merge!(opts)
-
-      offset = 0
-      baseline = 0
-
-      iter = layout.iter
-      loop do
-        line = iter.line
-        ink_rect, logical_rect = iter.line_extents
-        if y + (baseline - offset) >= (y + h)
-          # our text is using the maximum amount of vertical space we want it to
-          if options[:auto_new_page]
-            # create a new page and we can continue adding text
-            offset += baseline
-            start_new_page
-          else
-            # the user doesn't want us to continue on the next page, so
-            # stop adding lines to the canvas
-            break
-          end
-        end
-
-        # move to the start of the next line
-        #move_to(x, y)
-        baseline = iter.baseline / Pango::SCALE
-        @context.move_to(x + logical_rect.x / Pango::SCALE, y + baseline - offset)
-
-        # draw the line on the canvas
-        @context.show_pango_layout_line(line)
-
-        break unless iter.next_line!
-      end
-
-      # return the y co-ord we finished on
-      return y + baseline - offset
+    def device_to_user_dist(x, y)
+      @context.device_to_user_distance(x, y)
     end
 
-    def translate_color(c)
-      # the follow line converts a color definition from various formats (hex, symbol, etc)
-      # into a 4 item array. This is normally handled within cairo itself, however when
-      # Cairo and Poppler are both loaded, it breaks.
-      Cairo::Color.parse(c).to_rgb.to_a
+    def device_x_to_user_x(x)
+      @context.device_to_user(x, 0).first.abs
     end
 
-    # set the current drawing colour
-    #
-    # for info on what is valid, see the comments for default_color
-    def set_color(c)
-      c = translate_color(c)
-      validate_color(c)
-      @context.set_source_rgba(*c)
+    def device_y_to_user_y(y)
+      @context.device_to_user(0, y).last.abs
     end
 
     # test to see if the specified colour is a a valid cairo color