pdf-wrapper 0.0.7 → 0.1.0

data/lib/pdf/wrapper/text.rb

@@ -0,0 +1,337 @@
+module PDF
+  class Wrapper
+
+    # change the default font size
+    def font_size(size)
+      @default_font_size = size.to_i unless size.nil?
+    end
+    alias font_size= font_size
+
+    # change the default font to write with
+    def font(fontname, style = nil, weight = nil)
+      @default_font = fontname
+      @default_font_style = style unless style.nil?
+      @default_font_weight = weight unless weight.nil?
+    end
+
+    # 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>:radius</tt>:: Give the border around the cell rounded corners. Implies :border => "tblr"
+    def cell(str, x, y, w, h, opts={})
+      # TODO: add a wrap option so wrapping can be disabled
+      # TODO: add an option for vertical alignment
+
+      options = default_text_options
+      options.merge!({:border => "tblr", :border_width => @default_line_width, :border_color => :black,  :fill_color => nil, :padding => device_to_user_dist(3,0).first, :radius => nil})
+      options.merge!(opts)
+      options.assert_valid_keys(default_text_options.keys + [:width, :border, :border_width, :border_color, :fill_color, :padding, :radius])
+
+      # apply padding
+      textw = w - (options[:padding] * 2)
+      texth = h - (options[:padding] * 2)
+
+      # if the user wants a rounded rectangle, we'll draw the border with a rectangle instead
+      # of 4 lines
+      options[:border] = nil if options[:radius]
+
+      # normalise the border
+      options[:border] = "" unless options[:border]
+      options[:border].downcase!
+
+      save_coords do
+        translate(x, y) do
+          # draw a border around the cell
+          if options[:radius]
+            rectangle(0,0,w,h, :radius => options[:radius], :color => options[:border_color], :fill_color => options[:fill_color], :line_width => options[:border_width])
+          else
+            rectangle(0,0,w,h, :color => options[:fill_color], :fill_color => options[:fill_color])     if options[:fill_color]
+            line(0,0,w,0,      :color => options[:border_color], :line_width => options[:border_width]) if options[:border].include?("t")
+            line(0,h,w,h,      :color => options[:border_color], :line_width => options[:border_width]) if options[:border].include?("b")
+            line(0,0,0,h,      :color => options[:border_color], :line_width => options[:border_width]) if options[:border].include?("l")
+            line(w,0,w,h,      :color => options[:border_color], :line_width => options[:border_width]) if options[:border].include?("r")
+          end
+
+          layout = build_pango_layout(str.to_s, textw, options)
+
+          color(options[:color]) if options[:color]
+
+          # draw the context on our cairo layout
+          render_layout(layout, options[:padding], options[:padding], texth, :auto_new_page => false)
+        end
+
+      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
+    #
+    # Positioning Options:
+    #
+    # <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
+    #
+    # Text Style Options:
+    #
+    # <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>:wrap</tt>::  The wrapping technique to use if required. Use :word, :char or :wordchar. Default is :wordchar
+    # <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
+    # <tt>:markup</tt>::  Interpret the text as a markup language. Default is nil (none).
+    #
+    # = Markup
+    #
+    # If the markup option is specified, the text can be modified in various ways. At this stage
+    # the only markup syntax implemented is :pango.
+    #
+    # == Pango Markup
+    #
+    # Full details on the Pango markup language are avaialble at http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup
+    #
+    # The format is vaguely XML-like.
+    #
+    # Bold: "Some of this text is <b>bold</b>."
+    # Italics: "Some of this text is in <b>italics</b>."
+    # Strikethrough: "My name is <s>Bob</s>James."
+    # Monospace Font: "Code:\n<tt>puts 1</tt>."
+    #
+    # For more advanced control, use span tags
+    #
+    # Big and Bold: Some of this text is <span weight="bold" font_desc="20">bold</span>.
+    # Stretched: Some of this text is <span stretch="extraexpanded">funny looking</span>.
+    def text(str, opts={})
+      # TODO: add converters from various markup languages to pango markup. (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)
+
+      color(options[:color]) if 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 + device_y_to_user_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.assert_valid_keys(default_text_options.keys)
+      options[:width] = width || body_width
+
+      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
+
+    private
+
+    # takes a string and a range of options and creates a pango layout for us. Pango
+    # does all the hard work of calculating text layout, wrapping, fonts, sizes, 
+    # direction and more. Thank $diety.
+    #
+    # The string should be encoded using utf-8. If you get unexpected characters in the 
+    # rendered output, check the string encoding. Under Ruby 1.9 compatible VMs, any
+    # non utf-8 strings will be automatically converted if possible.
+    #
+    # The layout will be constrained to the requested width, but has no maximum height. It
+    # is up to some other part of the code to decide how much of the layout should actually
+    # be rendered to the document, when page breaks should be inserted, etc. To specify no
+    # wrapping, set width to nil. This will result in a single line layout that is as wide
+    # as it needs to be to fit the entire string.
+    #
+    # options:
+    # <tt>:markup</tt>::    The markup language of the string. See Wrapper#text for more information
+    # <tt>:spacing</tt>::   The spacing between lines. See Wrapper#text for more information
+    # <tt>:alignment</tt>:: The alignment of the text. See Wrapper#text for more information
+    # <tt>:justify</tt>::   Should spacing between words be tweaked so each edge of the line touches 
+    #                       the edge of the layout. See Wrapper#text for more information
+    # <tt>:font</tt>::      The font to use. See Wrapper#text for more information
+    # <tt>:font_size</tt>:: The font size to use. See Wrapper#text for more information
+    # <tt>:wrap</tt>::      The wrap technique to use. See Wrapper#text for more information
+    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
+      if options[:markup] == :pango
+        layout.markup = str.to_s
+      else
+        layout.text = str.to_s
+      end
+      if w.nil? || w < 0
+        layout.width = -1
+      else
+        # width is specified in user points
+        layout.width = w * Pango::SCALE
+      end
+      # spacing is specified in user points
+      layout.spacing = device_y_to_user_y(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
+
+      # set the wrapping technique text of the layout
+      if options[:wrap].eql?(:word)
+        layout.wrap = Pango::Layout::WRAP_WORD
+      elsif options[:wrap].eql?(:char)
+        layout.wrap = Pango::Layout::WRAP_CHAR
+      elsif options[:wrap].eql?(:wordchar)
+        layout.wrap = Pango::Layout::WRAP_WORD_CHAR
+      else
+        raise ArgumentError, "Invalid wrap technique 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])
+      # font size should be specified in device points for simplicity's sake.
+      fdesc.size = device_y_to_user_y(options[:font_size] * Pango::SCALE)
+      layout.font_description = fdesc
+      @context.update_pango_layout(layout)
+
+      return layout
+    end
+
+    def default_text_options
+      { :font => @default_font,
+        :font_size => @default_font_size,
+        :alignment => :left,
+        :wrap => :wordchar,
+        :justify => false,
+        :spacing => 0,
+        :color => nil,
+        :markup => nil
+      }
+    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
+
+        # calculate the relative starting co-ords of this line
+        baseline = iter.baseline / Pango::SCALE
+        linex = logical_rect.x / Pango::SCALE
+
+        if baseline - offset >= 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 this line
+        @context.move_to(x + linex, 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 device_y_to_user_y(y + baseline - offset)
+    end
+
+
+  end
+end

data/specs/{shapes_spec.rb → graphics_spec.rb}

@@ -101,7 +101,7 @@ context "The PDF::Wrapper class" do
     w = h = 200
     r = 5
     pdf = PDF::Wrapper.new
-    pdf.rounded_rectangle(x,y,w,h,r)
+    pdf.rectangle(x,y,w,h,:radius => r)
 
     receiver = PDF::Reader::RegisterReceiver.new
     reader = PDF::Reader.string(pdf.render, receiver)
@@ -118,7 +118,7 @@ context "The PDF::Wrapper class" do
     r = 5
     w = 5
     pdf = PDF::Wrapper.new
-    pdf.rounded_rectangle(x,y,w,h,r, :line_width => w)
+    pdf.rounded_rectangle(x,y,w,h, :radius => r, :line_width => w)
 
     receiver = PDF::Reader::RegisterReceiver.new
     reader = PDF::Reader.string(pdf.render, receiver)
@@ -134,7 +134,7 @@ context "The PDF::Wrapper class" do
     w = h = 200
     r = 5
     pdf = PDF::Wrapper.new
-    pdf.rounded_rectangle(x,y,w,h,r, :fill_color => :red)
+    pdf.rounded_rectangle(x,y,w,h, :radius => r, :fill_color => :red)
 
     receiver = PDF::Reader::RegisterReceiver.new
     reader = PDF::Reader.string(pdf.render, receiver)

data/specs/spec_helper.rb

@@ -25,6 +25,11 @@ class PDF::Wrapper
   public :load_libpixbuf
   public :load_libpango
   public :load_libpoppler
+  public :user_x_to_device_x
+  public :user_y_to_device_y
+  public :user_to_device_dist
+  public :device_x_to_user_x
+  public :device_y_to_user_y
   public :validate_color
 end
 
@@ -52,7 +57,7 @@ class PageSizeReceiver
 
   # Called when page parsing ends
   def begin_page(args)
-    pages << args["MediaBox"] || args[:MediaBox]
+    pages << (args["MediaBox"] || args[:MediaBox])
   end
 end
 

data/specs/tables_spec.rb

@@ -0,0 +1,111 @@
+# coding: utf-8
+
+require File.dirname(__FILE__) + '/spec_helper'
+
+context "The PDF::Wrapper class" do
+  specify "should be able to draw a table on the canvas using an array of data" do
+    pdf = PDF::Wrapper.new
+    data = [%w{data1 data2}, %w{data3 data4}]
+    pdf.table(data)
+
+    receiver = PageTextReceiver.new
+    reader = PDF::Reader.string(pdf.render, receiver)
+
+    receiver.content.first.include?("data1").should be_true
+    receiver.content.first.include?("data2").should be_true
+    receiver.content.first.include?("data3").should be_true
+    receiver.content.first.include?("data4").should be_true
+  end
+
+  specify "should be able to draw a table on the canvas using a PDF::Wrapper::Table object" do
+    pdf = PDF::Wrapper.new
+    table = PDF::Wrapper::Table.new do |t|
+      t.data = [%w{data1 data2}, %w{data3 data4}]
+    end
+
+    pdf.table(table)
+
+    receiver = PageTextReceiver.new
+    reader = PDF::Reader.string(pdf.render, receiver)
+
+    receiver.content.first.include?("data1").should be_true
+    receiver.content.first.include?("data2").should be_true
+    receiver.content.first.include?("data3").should be_true
+    receiver.content.first.include?("data4").should be_true
+  end
+
+  specify "should be able to draw a table on the canvas with no headings" do
+    pdf = PDF::Wrapper.new
+    
+    table = PDF::Wrapper::Table.new do |t|
+      t.data = (1..50).collect { [1,2] }
+      t.headers = ["col1", "col2"]
+      t.show_headers = nil
+    end
+
+    pdf.table(table)
+
+    receiver = PageTextReceiver.new
+    reader = PDF::Reader.string(pdf.render, receiver)
+
+    receiver.content.first.include?("col1").should be_false
+    receiver.content.first.include?("col2").should be_false
+  end
+
+  specify "should be able to draw a table on the canvas with headers on the first page only" do
+    pdf = PDF::Wrapper.new
+    
+    table = PDF::Wrapper::Table.new do |t|
+      t.data = (1..50).collect { [1,2] }
+      t.headers = ["col1", "col2"]
+      t.show_headers = :once
+    end
+
+    pdf.table(table)
+
+    receiver = PageTextReceiver.new
+    reader = PDF::Reader.string(pdf.render, receiver)
+
+    receiver.content[0].include?("col1").should be_true
+    receiver.content[0].include?("col2").should be_true
+    receiver.content[1].include?("col1").should be_false
+    receiver.content[1].include?("col2").should be_false
+  end
+
+  specify "should be able to draw a table on the canvas with headers on all pages" do
+    pdf = PDF::Wrapper.new
+    
+    table = PDF::Wrapper::Table.new do |t|
+      t.data = (1..50).collect { [1,2] }
+      t.headers = ["col1", "col2"]
+      t.show_headers = :page
+    end
+
+    pdf.table(table)
+
+    receiver = PageTextReceiver.new
+    reader = PDF::Reader.string(pdf.render, receiver)
+
+    receiver.content[0].include?("col1").should be_true
+    receiver.content[0].include?("col2").should be_true
+    receiver.content[1].include?("col1").should be_true
+    receiver.content[1].include?("col2").should be_true
+  end
+
+  specify "should leave the cursor in the bottom left when adding a table" do
+    pdf = PDF::Wrapper.new
+    data = [%w{head1 head2},%w{data1 data2}]
+    pdf.table(data, :left => pdf.margin_left)
+    x,y = pdf.current_point
+    x.to_i.should eql(pdf.margin_left)
+  end
+
+  specify "should default to using as much available space when adding a table that isn't left aligned with the left margin" do
+    pdf = PDF::Wrapper.new
+    data = [%w{head1 head2},%w{data1 data2}]
+    pdf.table(data, :left => 100)
+    x,y = pdf.current_point
+    x.to_i.should eql(100)
+  end
+
+end