pdf-wrapper 0.1.3 → 0.2.0

data/lib/pdf/wrapper/table.rb

@@ -19,7 +19,6 @@ module PDF
       # TODO: add support for a table footer
       #       - repeating each page, or just at the bottom? 
       #       - if it repeats, should it be different on each page? ie. a sum of that pages rows, etc.
-      # TODO: add support for manually specifying 1 or more column widths
       # TODO: maybe support for multiple data sets with group headers/footers. useful for subtotals, etc
 
       x, y = current_point
@@ -85,6 +84,9 @@ module PDF
       # TODO: when calculating the min cell width, we basically want the width of the widest character. At the
       #       moment I'm stripping all pango markup tags from the string, which means if any character is made
       #       intentioanlly large, we'll miss it and it might not fit into our table cell.
+      # TODO: allow column widths to be set manually
+
+      # calculate the min and max width of every cell in the table
       t.cells.each_with_index do |row, row_idx|
         row.each_with_index do |cell, col_idx|
           opts = t.options_for(col_idx, row_idx).only(default_text_options.keys)
@@ -93,6 +95,8 @@ module PDF
           cell.max_width  = text_width(cell.data, opts) + (padding * 4)
         end
       end
+
+      # calculate the min and max width of every cell in the headers row
       if t.headers
         t.headers.each_with_index do |cell, col_idx|
           opts = t.options_for(col_idx, :headers).only(default_text_options.keys)
@@ -101,7 +105,12 @@ module PDF
           cell.max_width  = text_width(cell.data, opts) + (padding * 4)
         end
       end
+
+      # let the table decide on the actual widths it will use for each col
       t.calc_col_widths!
+
+      # now that we know how wide each column will be, we can calculate the 
+      # height of every cell in the table
       t.cells.each_with_index do |row, row_idx|
         row.each_with_index do |cell, col_idx|
           opts = t.options_for(col_idx, row_idx).only(default_text_options.keys)
@@ -109,7 +118,11 @@ module PDF
           cell.height = text_height(cell.data, t.col_width(col_idx) - (padding * 2), opts) + (padding * 2)
         end
       end
+
+      # let the table calculate how high each row is going to be
       t.calc_row_heights!
+
+      # perform the same height calcs for the header row if necesary
       if t.headers
         t.headers.each_with_index do |cell, col_idx|
           opts = t.options_for(col_idx, :headers).only(default_text_options.keys)
@@ -147,7 +160,7 @@ module PDF
     # with optional headings, then pass the object to Wrapper#table
     #
     #    table = Table.new do |t|
-    #      t.headings = ["Words", "Numbers"]
+    #      t.headers = ["Words", "Numbers"]
     #      t.data = [['one',  1],
     #                ['two',  2],
     #                ['three',3]]
@@ -167,16 +180,16 @@ module PDF
     #
     # For example:
     #
-    #    table = Table.new do |t|
+    #    table = Table.new(:font_size => 10) do |t|
     #      t.headers = ["Words", "Numbers"]
     #      t.data = [['one',  1],
     #                ['two',  2],
     #                ['three',3]]
-    #      t.table_options :font_size => 10
     #      t.row_options 0, :color => :green
     #      t.row_options 2, :color => :red
     #      t.col_options 0, :color => :blue
     #      t.cell_options 2, 2, :font_size => 18
+    #      t.manual_column_width 2, 40
     #    end
     #    pdf.table(table)
     #
@@ -188,19 +201,17 @@ module PDF
     # top of the table, and :page for the default.
     #
     class Table
-      attr_reader :cells, :headers
+      attr_reader :cells#, :headers
       attr_accessor :width, :show_headers
 
       #
-      # headers should be a single array
-      #  
-      #   ["first", "second"]
-      def initialize
+      def initialize(opts = {})
 
         # default table options
-        @table_options  = {}
+        @table_options  = opts
         @col_options    = Hash.new({})
         @row_options    = Hash.new({})
+        @manual_col_widths = {}
         @header_options = {}
         @show_headers  = :page
 
@@ -224,18 +235,40 @@ module PDF
         end
       end
 
-      # Specify the tables optional column headers.
+      # Retrieve or set the table's optional column headers.
       #
-      # The single argument should be an array like:
+      # With no arguments, the currents headers will be returned
       #
-      #   [ "col one", "col two"]
-      def headers=(h)
+      #   t.headers
+      #   => ["col one", "col two"]
+      #
+      # The first argument is an array of text to use as column headers
+      #
+      #   t.headers ["col one", "col two]
+      #
+      # The optional second argument sets the cell options for the header
+      # cells. See PDF::Wrapper#cell for a list of possible options. 
+      #
+      #   t.headers ["col one", "col two], :color => :block, :fill_color => :black
+      #
+      # If the options hash is left unspecified, the default table options will 
+      # be used.
+      #
+      def headers(h = nil, opts = {})
         # TODO: raise an exception of the size of the array does not match the size
         #       of the data row arrays
         # TODO: ensure h is array-like
+        return @headers if h.nil?
         @headers = h.collect do |str|
           Wrapper::Cell.new(str)
         end
+        @header_options = opts
+      end
+
+      def headers=(h)
+        # TODO: remove this method at some point. Deprecation started on 10th August 2008.
+        warn "WARNING: Table#headers=() is deprecated, headers should now be set along with header options using Table#headers()"
+        headers h
       end
 
       # access a particular cell at location x, y
@@ -245,14 +278,24 @@ module PDF
 
       # Set or retrieve options that apply to every cell in the table.
       # For a list of valid options, see Wrapper#cell.
+      #
+      # WARNING. This method is deprecated. Table options should be passed to the
+      #          PDF::Wrapper::Table constructor instead
       def table_options(opts = nil)
+        # TODO: remove this method at some point. Deprecation started on 10th August 2008.
+        warn "WARNING: Table#table_options() is deprecated, please see the documentation for PDF::Wrapper::Table"
         @table_options = @table_options.merge(opts) if opts
         @table_options
       end
 
       # set or retrieve options that apply to header cells
       # For a list of valid options, see Wrapper#cell.
+      #
+      # WARNING. This method is deprecated. Header options should be passed to the
+      #          PDF::Wrapper::Table#headers method instead
       def header_options(opts = nil)
+        # TODO: remove this method at some point. Deprecation started on 10th August 2008.
+        warn "WARNING: Table#header_options() is deprecated, please see the documentation for PDF::Wrapper::Table"
         @header_options = @header_options.merge(opts) if opts
         @header_options
       end
@@ -282,6 +325,25 @@ module PDF
         self
       end
 
+      # Manually set the width for 1 or more columns 
+      #
+      # <tt>spec</tt>::     Which columns to set the width for. :odd, :even, a range, an Array of numbers or a number
+      #
+      def manual_col_width(spec, width)
+        width = width.to_f
+        each_column do |col_idx|
+          if (spec == :even && (col_idx % 2) == 0) ||
+             (spec == :odd  && (col_idx % 2) == 1) ||
+             (spec.class == Range && spec.include?(col_idx)) ||
+             (spec.class == Array && spec.include?(col_idx)) ||
+             (spec.respond_to?(:to_i) && spec.to_i == col_idx)
+            
+            @manual_col_widths[col_idx] = width
+          end
+        end
+        self
+      end
+
       # set options that apply to 1 or more rows
       # For a list of valid options, see Wrapper#cell.
       # <tt>spec</tt>::     Which columns to add the options to. :odd, :even, a range, an Array of numbers or a number
@@ -301,7 +363,7 @@ module PDF
 
       # calculate the combined options for a particular cell
       #
-      # To get the options for a regular cell, use numbers to refernce the exact cell:
+      # To get the options for a regular cell, use numbers to reference the exact cell:
       #
       #    options_for(3, 3)
       #
@@ -374,7 +436,7 @@ module PDF
 
       private
 
-      # the main smarts behind deciding on the width of each column. If possible, 
+      # the main smarts behind deciding on the width of each column. If possible,
       # each cell will get the maximum amount of space it wants. If not, some
       # negotiation happens to find the best possible set of widths.
       def calc_column_widths
@@ -395,6 +457,13 @@ module PDF
           end
         end
 
+        # override the min and max col widths with manual ones where appropriate
+        # freeze the values so that the algorithm that adjusts the widths
+        # leaves them untouched
+        @manual_col_widths.each { |key, val| val.freeze }
+        max_col_widths.merge! @manual_col_widths
+        min_col_widths.merge! @manual_col_widths
+
         if min_col_widths.values.sum > self.width
           raise RuntimeError, "table content cannot fit into a table width of #{self.width}"
         end
@@ -414,18 +483,24 @@ module PDF
         col_widths
       end
 
-      # ceck to ensure every cell has a minimum and maximum cell width defined
+      # check to ensure every cell has a minimum and maximum cell width defined
       def check_cell_widths
         @cells.each do |row|
-          row.each do |cell|
+          row.each_with_index do |cell, col_idx|
             raise "Every cell must have a min_width defined before being rendered to a document" if cell.min_width.nil?
             raise "Every cell must have a max_width defined before being rendered to a document" if cell.max_width.nil?
+            if @manual_col_widths[col_idx] && cell.min_width > @manual_col_widths[col_idx]
+              raise "Manual width for col #{col_idx} is too low"
+            end
           end
         end
         if @headers
-          @headers.each do |cell|
+          @headers.each_with_index do |cell, col_idx|
             raise "Every header cell must have a min_width defined before being rendered to a document" if cell.min_width.nil?
             raise "Every header cell must have a max_width defined before being rendered to a document" if cell.max_width.nil?
+            if @manual_col_widths[col_idx] && cell.min_width > @manual_col_widths[col_idx]
+              raise "Manual width for col #{col_idx} is too low"
+            end
           end
         end
       end
@@ -457,9 +532,9 @@ module PDF
       # if the widths of every column are less than the total width
       # of the table, grow them to make use of it.
       #
-      # col_widths - the cuurect hash of widths for each column index
+      # col_widths - the current hash of widths for each column index
       # max_col_widths - the maximum width each column desires
-      # pas_max - can the width of a colum grow beyond its maximum desired
+      # past_max - can the width of a colum grow beyond its maximum desired
       def grow_col_widths(col_widths, max_col_widths, past_max = false)
         loop do
           each_column do |idx|

data/lib/pdf/wrapper/text.rb

@@ -1,9 +1,36 @@
 module PDF
   class Wrapper
 
-    # change the default font size
+    # Change the default font size
+    #
+    # If no block is provided, the change is permanent. If a block
+    # is provided, the change will revert at the end of the block
+    #
+    # Permanant change:
+    #
+    #   pdf.font_size 10
+    #
+    # Temporary change:
+    #
+    #   pdf.font_size 20
+    #   pdf.text "This text is size 20"
+    #   pdf.font_size(10) do
+    #     pdf.text "This text is size 20"
+    #   end
+    #   pdf.text "This text is size 20"
+    #
     def font_size(size)
-      @default_font_size = size.to_i unless size.nil?
+      new_size = size.to_i
+      raise ArgumentError, 'font size must be > 0' if new_size <= 0
+
+      if block_given?
+        orig_size = @default_font_size
+        @default_font_size = new_size
+        yield
+        @default_font_size = orig_size
+      else
+        @default_font_size = new_size
+      end
     end
     alias font_size= font_size
 
@@ -65,7 +92,7 @@ module PDF
           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)
+          render_layout(layout, options[:padding], options[:padding], texth)
         end
 
       end
@@ -74,7 +101,7 @@ module PDF
     # 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
+    # the default font styling set by font(), 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
@@ -110,7 +137,7 @@ module PDF
     # 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>."
+    # Italics: "Some of this text is in <i>italics</i>."
     # Strikethrough: "My name is <s>Bob</s>James."
     # Monospace Font: "Code:\n<tt>puts 1</tt>."
     #
@@ -118,6 +145,7 @@ module PDF
     #
     # 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
@@ -141,7 +169,7 @@ module PDF
       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)
+      y = render_layout(layout, options[:left], options[:top])
 
       move_to(options[:left], y)
     end
@@ -175,7 +203,7 @@ module PDF
     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, 
+    # 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 
@@ -287,13 +315,18 @@ module PDF
     # 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 = {})
+    #
+    # If h is specified, lines of text will be rendered up to that height, and 
+    # the rest will be ignored. 
+    #
+    # If h is nil, lines will be rendered until the bottom margin is hit, then
+    # a new page will be started and lines will continue being rendered at the
+    # top of the new page.
+    def render_layout(layout, x, y, h = nil)
       # 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
@@ -308,17 +341,15 @@ module PDF
         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
+        if h && baseline - offset >= h
+          # the user doesn't want us to continue on the next page, so
+          # stop adding lines to the canvas
+          break
+        elsif h.nil? && (y + baseline - offset + spacing) >= self.absolute_bottom_margin
+          # create a new page and we can continue adding text
+          offset = baseline
+          start_new_page
+          y = self.y
         end
 
         # move to the start of this line

data/specs/graphics_spec.rb

@@ -3,14 +3,17 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
 context "The PDF::Wrapper class" do
+
+  before(:each) { create_pdf }
+
   specify "should be able to draw a single line onto the canvas" do
     x0 = y0 = 100
     x1 = y1 = 200
-    pdf = PDF::Wrapper.new
-    pdf.line(x0,y0,x1,y1)
+    @pdf.line(x0,y0,x1,y1)
+    @pdf.finish
 
     receiver = PDF::Reader::RegisterReceiver.new
-    reader = PDF::Reader.string(pdf.render, receiver)
+    reader = PDF::Reader.string(@output.string, receiver)
 
     # the begin_new_subpath command specifies the start of the line, append line specifies the end
     receiver.count(:begin_new_subpath).should eql(1)
@@ -23,11 +26,11 @@ context "The PDF::Wrapper class" do
     x0 = y0 = 100
     x1 = y1 = 200
     width = 5
-    pdf = PDF::Wrapper.new
-    pdf.line(x0,y0,x1,y1, :line_width => width)
+    @pdf.line(x0,y0,x1,y1, :line_width => width)
+    @pdf.finish
 
     receiver = PDF::Reader::RegisterReceiver.new
-    reader = PDF::Reader.string(pdf.render, receiver)
+    reader = PDF::Reader.string(@output.string, receiver)
 
     # the begin_new_subpath command specifies the start of the line, append line specifies the end
     receiver.count(:set_line_width).should eql(1)
@@ -43,11 +46,11 @@ context "The PDF::Wrapper class" do
   specify "should be able to draw an empty rectangle onto the canvas" do
     x = y = 100
     w = h = 200
-    pdf = PDF::Wrapper.new
-    pdf.rectangle(x,y,w,h)
+    @pdf.rectangle(x,y,w,h)
+    @pdf.finish
 
     receiver = PDF::Reader::RegisterReceiver.new
-    reader = PDF::Reader.string(pdf.render, receiver)
+    reader = PDF::Reader.string(@output.string, receiver)
 
     # the begin_new_subpath command specifies the start of the line, append line specifies the end
     callbacks = receiver.all(:append_rectangle)
@@ -61,11 +64,11 @@ context "The PDF::Wrapper class" do
     x = y = 100
     w = h = 200
     width = 5
-    pdf = PDF::Wrapper.new
-    pdf.rectangle(x,y,w,h, :line_width => width)
+    @pdf.rectangle(x,y,w,h, :line_width => width)
+    @pdf.finish
 
     receiver = PDF::Reader::RegisterReceiver.new
-    reader = PDF::Reader.string(pdf.render, receiver)
+    reader = PDF::Reader.string(@output.string, receiver)
 
     # ensure the line width was set correctly
     receiver.count(:set_line_width).should eql(1)
@@ -85,10 +88,10 @@ context "The PDF::Wrapper class" do
     x = y = 100
     w = h = 200
     pdf = PDF::Wrapper.new
-    pdf.rectangle(x,y,w,h, :fill_color => :red)
+    @pdf.rectangle(x,y,w,h, :fill_color => :red)
 
     receiver = PDF::Reader::RegisterReceiver.new
-    reader = PDF::Reader.string(pdf.render, receiver)
+    reader = PDF::Reader.string(@pdf.render, receiver)
 
     # TODO: test for the appropriate pattern of callbacks
   end
@@ -101,10 +104,10 @@ context "The PDF::Wrapper class" do
     w = h = 200
     r = 5
     pdf = PDF::Wrapper.new
-    pdf.rectangle(x,y,w,h,:radius => r)
+    @pdf.rectangle(x,y,w,h,:radius => r)
 
     receiver = PDF::Reader::RegisterReceiver.new
-    reader = PDF::Reader.string(pdf.render, receiver)
+    reader = PDF::Reader.string(@pdf.render, receiver)
 
     # TODO: test for the appropriate pattern of callbacks
   end
@@ -118,10 +121,10 @@ context "The PDF::Wrapper class" do
     r = 5
     w = 5
     pdf = PDF::Wrapper.new
-    pdf.rounded_rectangle(x,y,w,h, :radius => 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)
+    reader = PDF::Reader.string(@pdf.render, receiver)
 
     # TODO: test for the appropriate pattern of callbacks
   end
@@ -134,10 +137,10 @@ context "The PDF::Wrapper class" do
     w = h = 200
     r = 5
     pdf = PDF::Wrapper.new
-    pdf.rounded_rectangle(x,y,w,h, :radius => 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)
+    reader = PDF::Reader.string(@pdf.render, receiver)
 
     # TODO: test for the appropriate pattern of callbacks
   end
@@ -150,10 +153,10 @@ context "The PDF::Wrapper class" do
     y = 200
     r = 5
     pdf = PDF::Wrapper.new
-    pdf.circle(x,y,r)
+    @pdf.circle(x,y,r)
 
     receiver = PDF::Reader::RegisterReceiver.new
-    reader = PDF::Reader.string(pdf.render, receiver)
+    reader = PDF::Reader.string(@pdf.render, receiver)
 
     # TODO: test for the appropriate pattern of callbacks
   end
@@ -167,10 +170,10 @@ context "The PDF::Wrapper class" do
     r = 5
     w = 5
     pdf = PDF::Wrapper.new
-    pdf.circle(x,y,r, :line_width => w)
+    @pdf.circle(x,y,r, :line_width => w)
 
     receiver = PDF::Reader::RegisterReceiver.new
-    reader = PDF::Reader.string(pdf.render, receiver)
+    reader = PDF::Reader.string(@pdf.render, receiver)
 
     # TODO: test for the appropriate pattern of callbacks
   end
@@ -183,10 +186,10 @@ context "The PDF::Wrapper class" do
     y = 200
     r = 5
     pdf = PDF::Wrapper.new
-    pdf.circle(x,y,r, :fill_color => :red)
+    @pdf.circle(x,y,r, :fill_color => :red)
 
     receiver = PDF::Reader::RegisterReceiver.new
-    reader = PDF::Reader.string(pdf.render, receiver)
+    reader = PDF::Reader.string(@pdf.render, receiver)
 
     # TODO: test for the appropriate pattern of callbacks
   end