pdf-wrapper 0.0.1 → 0.0.2

data/CHANGELOG

@@ -1,2 +1,7 @@
+v0.0.2 (11th January 2008)
+- Added support for a range of extra image formats (jpg, pdf, gif, etc)
+- Various documentation improvements 
+- improved the text functions a little, but still lots more to go
+
 v0.0.1 (9th January 2008)
 - Initial, pre-alpha, eats small children for breakfast release

data/DESIGN

@@ -13,6 +13,7 @@
   - image boxes
   - lists
   - tables (port simple table?)
+  - add pages from existing PDFs
 
 *************************************
 * Thoughts on the table API

data/README

@@ -47,14 +47,16 @@ James Healy <jimmy@deefa.com>
  
 = Dependencies
 
-* ruby/cairo
-* ruby/pango (optional, required to add text)
-* ruby/rsvg2 (optional, required for SVG support)
+* ruby/cairo[http://cairographics.org/rcairo/]
+* 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)
 
 These are all ruby bindings to C libraries. On Debian/Ubuntu based systems
 (which I develop on) you can get them by running:
 
-    aptitude install libcairo-ruby libpango1-ruby librsvg2-ruby
+    aptitude install libcairo-ruby libpango1-ruby librsvg2-ruby libpoppler-glib-ruby
 
 For users of other systems, I'd love to receive info on how you set these bindings up.
 

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/testtask'
 require "rake/gempackagetask"
 require 'spec/rake/spectask'
 
-PKG_VERSION = "0.0.1"
+PKG_VERSION = "0.0.2"
 PKG_NAME = "pdf-wrapper"
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 
@@ -19,7 +19,7 @@ Spec::Rake::SpecTask.new("spec") do |t|
   t.spec_files = FileList['specs/**/*.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",".*df-reader.*"]
+  t.rcov_opts = ["--exclude","spec.*\.rb","--exclude",".*cairo.*","--exclude",".*rcov.*","--exclude",".*rspec.*","--exclude",".*pdf-reader.*"]
 end
 
 # generate specdocs
@@ -51,26 +51,33 @@ Rake::RDocTask.new("doc") do |rdoc|
   rdoc.options << "--inline-source"
 end
 
+desc "Publish rdocs to rubyforge"
+task :publish_rdoc => [ :doc ] do
+  rdoc_dir = File.dirname(__FILE__) + "/doc/rdoc/"
+  `scp -r #{rdoc_dir} yob@rubyforge.org:/var/www/gforge-projects/pdf-wrapper/`
+end
+
 # a gemspec for packaging this library 
 spec = Gem::Specification.new do |spec|
-	spec.name = PKG_NAME
-	spec.version = PKG_VERSION
-	spec.platform = Gem::Platform::RUBY
-	spec.summary = "A PDF generating library built on top of cairo"
-	spec.files =  Dir.glob("{examples,lib}/**/**/*") + ["Rakefile"]
+  spec.name = PKG_NAME
+  spec.version = PKG_VERSION
+  spec.platform = Gem::Platform::RUBY
+  spec.summary = "A PDF generating library built on top of cairo"
+  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.rdoc_options << '--title' << 'PDF::Wrapper Documentation' << '--main'  << 'README' << '-q'
+  spec.has_rdoc = true
+  spec.extra_rdoc_files = %w{README DESIGN CHANGELOG}
+  spec.rdoc_options << '--title' << 'PDF::Wrapper Documentation' << '--main'  << 'README' << '-q'
   spec.author = "James Healy"
-	spec.email = "jimmy@deefa.com"
-	spec.rubyforge_project = "pdf-wrapper"
-	spec.description = "A PDF writing library that uses the cairo and pango libraries to do the heavy lifting."
+  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."
 end
 
 # package the library into a gem
 desc "Generate a gem for pdf-wrapper"
 Rake::GemPackageTask.new(spec) do |pkg|
-	pkg.need_zip = true
-	pkg.need_tar = true
+  pkg.need_zip = true
+  pkg.need_tar = true
 end

data/examples/image.rb

@@ -8,5 +8,13 @@ pdf = PDF::Wrapper.new(:paper => :A4)
 pdf.default_font("Sans Serif")
 pdf.default_color(:black)
 pdf.text("PDF::Wrapper Supports Images", :alignment => :center)
-pdf.image(File.dirname(__FILE__) + "/google.png", :left => 100, :top => 250)
+pdf.image(File.dirname(__FILE__) + "/../specs/data/zits.gif")
+pdf.image(File.dirname(__FILE__) + "/../specs/data/google.png", :left => 100, :top => 350)
+pdf.image(File.dirname(__FILE__) + "/../specs/data/stef.jpg", :left => 200, :top => 500)
+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.render_to_file("image.pdf")

data/examples/utf8-long.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new(:paper => :A4)
+pdf.default_font("Sans Serif")
+pdf.default_color(:black)
+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/lib/pdf/wrapper.rb

@@ -24,21 +24,21 @@ module PDF
   #
   # Rendering to a file:
   #   
-  #   require 'pdfwrapper'
+  #   require 'pdf/wrapper'
   #   pdf = PDF::Wrapper.new(:paper => :A4)
   #   pdf.text "Hello World"
   #   pdf.render_to_file("wrapper.pdf")
   #
   # Rendering to a string:
   #
-  #   require 'pdfwrapper'
+  #   require 'pdf/wrapper'
   #   pdf = PDF::Wrapper.new(:paper => :A4)
   #   pdf.text "Hello World", :font_size => 16
   #   puts pdf.render
   #
   # Changing the default font:
   #
-  #   require 'pdfwrapper'
+  #   require 'pdf/wrapper'
   #   pdf = PDF::Wrapper.new(:paper => :A4)
   #   pdf.default_font("Monospace")
   #   pdf.text "Hello World", :font => "Sans Serif", :font_size => 18
@@ -234,6 +234,7 @@ module PDF
     #               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
     end
@@ -506,8 +507,11 @@ module PDF
     # Functions relating to working with images
     #####################################################
 
-    # add an image to the page
-    # at this stage the file must be a PNG or SVG
+    # 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.
@@ -516,42 +520,24 @@ module PDF
     #
     # 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: maybe split this up into separate functions for each image type
       # TODO: add some options for things like justification, scaling and padding
-      # TODO: png images currently can't be resized
       # TODO: raise an error if any unrecognised options were supplied 
+      # TODO: add support for pdf/eps/ps images
       raise ArgumentError, "file #{filename} not found" unless File.file?(filename)
 
-      filetype = detect_image_type(filename)
-
-      if filetype.eql?(:png)
-        img_surface = Cairo::ImageSurface.from_png(filename)
-        x, y = current_point
-        @context.set_source(img_surface, opts[:left] || x, opts[:top] || y)
-        @context.paint
-      elsif filetype.eql?(:svg)
-        # thanks to Nathan Stitt for help with this section
-        load_librsvg
-        @context.save
-
-        # import it
-        handle = RSVG::Handle.new_from_file(filename)
-
-        # size the SVG
-        if opts[:height] && opts[:width]
-          handle.set_size_callback do |h,w|
-            [ opts[:width], opts[:height] ]
-          end
-        end
-
-        # place the image on our main context
-        x, y = current_point
-        @context.translate( opts[:left] || x, opts[:top] || y )
-        @context.render_rsvg_handle(handle)
-        @context.restore
+      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
-        raise ArgumentError, "Unrecognised image format"
+        begin
+          draw_pixbuf filename, opts
+        rescue Gdk::PixbufError
+          raise ArgumentError, "Unrecognised image format (#{filename})"
+        end
       end
     end
 
@@ -676,7 +662,6 @@ module PDF
     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)
@@ -684,13 +669,78 @@ module PDF
       # 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")
+        return :jpg
       else
         return nil
       end
     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
+      @context.save do
+        @context.translate(opts[:left] || x, opts[:top] || y)
+        @context.scale(width / w, height / h)
+        @context.render_poppler_page(page)
+      end
+    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 = (opts[:width] || pixbuf.width).to_f
+      height = (opts[:height] || pixbuf.height).to_f
+      @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
+    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
+      @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
+    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 = (opts[:width] || handle.width).to_f
+      height = (opts[:height] || handle.height).to_f
+      @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
+    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
     #
@@ -747,12 +797,34 @@ module PDF
     # http://ruby-gnome2.sourceforge.jp/fr/hiki.cgi?Cairo%3A%3AContext#Pango+related+APIs
     def load_libpango
       begin
-        require 'pango' unless ::Object.const_defined?(:Pango)
+        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
     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
+    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
+    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
@@ -760,7 +832,7 @@ module PDF
     # http://ruby-gnome2.sourceforge.jp/fr/hiki.cgi?Cairo%3A%3AContext#render_rsvg_handle
     def load_librsvg
       begin
-        require 'rsvg2' unless ::Object.const_defined?(:RSVG)
+        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
@@ -771,62 +843,76 @@ module PDF
     # 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 content.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)
 
-      limit_y = y + h
+      # store the starting x and y co-ords. If we start a new page, we'll continue
+      # adding text at the same co-ords
+      orig_x = x
+      orig_y = y
 
-      iter = layout.iter
-      prev_baseline = iter.baseline / Pango::SCALE
-      begin
-        line = iter.line
-        ink_rect, logical_rect = iter.line_extents
-        y_begin, y_end = iter.line_yrange
-        if limit_y < (y + y_end / Pango::SCALE)
+      # for each line in the layout
+      layout.lines.each do |line|
+
+        # draw the line on the canvas
+        @context.show_pango_layout_line(line)
+
+        #calculate where the next line starts
+        ink_rect, logical_rect = line.extents
+        y = y + (logical_rect.height / Pango::SCALE * (3.0/4.0)) + 1
+
+        if y >= (orig_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
             start_new_page
-            y = margin_top - prev_baseline
+            x = orig_x
+            y = orig_y
           else
+            # the user doesn't want us to continue on the next page, so
+            # stop adding lines to the canvas
             break
           end
         end
-        width, height = layout.size
-        baseline = iter.baseline / Pango::SCALE
-        move_to(x + logical_rect.x / Pango::SCALE, y + baseline)
-        @context.show_pango_layout_line(line)
-        prev_baseline = baseline
-      end while iter.next_line!
-      return y + baseline
+
+        # move to the start of the next line
+        move_to(x, y) 
+      end
+
+      # return the y co-ord we finished on
+      return 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
+    end
     # set the current drawing colour
     #
     # for info on what is valid, see the comments for default_color 
     def set_color(c)
-      # catch and reraise an exception to keep stack traces readable and clear
+      c = translate_color(c)
       validate_color(c)
-
-      if c.kind_of?(Array)
-        @context.set_source_color(*c)
-      else
-        @context.set_source_color(c)
-      end
+      @context.set_source_rgba(*c)
     end
 
     # 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 
     def validate_color(c)
+      c = translate_color(c)
       @context.save
+      # catch and reraise an exception to keep stack traces readable and clear
       begin
-        if c.kind_of?(Array)
-          # if the colour is being specified manually, there must be 3 or 4 elements
-          raise ArgumentError if c.size != 3 && c.size != 4
-          @context.set_source_color(c)
-        else
-          @context.set_source_color(c)
-        end
-        @default_color = c
+        raise ArgumentError unless c.kind_of?(Array) 
+        raise ArgumentError if c.size != 3 && c.size != 4
+        @context.set_source_rgba(c)
       rescue ArgumentError
         c.kind_of?(Array) ? str = "[#{c.join(",")}]" : str = c.to_s
         raise ArgumentError, "#{str} is not a valid color definition"