prawn-table 0.0.1

data/lib/prawn/table/column_width_calculator.rb

@@ -0,0 +1,182 @@
+# encoding: utf-8
+
+module Prawn
+  class Table
+    # @private
+    class ColumnWidthCalculator
+      def initialize(cells)
+        @cells = cells
+
+        @widths_by_column        = Hash.new(0)
+        @rows_with_a_span_dummy  = Hash.new(false)
+
+        #calculate for each row if it includes a Cell:SpanDummy
+        @cells.each do |cell|
+          @rows_with_a_span_dummy[cell.row] = true if cell.is_a?(Cell::SpanDummy)
+        end
+      end
+
+      # does this row include a Cell:SpanDummy?
+      #
+      # @param row - the row that should be checked for Cell:SpanDummy elements
+      #
+      def has_a_span_dummy?(row)
+        @rows_with_a_span_dummy[row]
+      end
+
+      # helper method
+      # column widths are stored in the values array
+      # a cell may span cells whose value is only partly given
+      # this function handles this special case
+      #
+      # @param values - The columns widths calculated up until now
+      # @param cell - The current cell
+      # @param index - The current column
+      # @param meth - Meth (min/max); used to calculate values to be filled
+      #
+      def fill_values_if_needed(values, cell, index, meth)
+        #have all spanned indices been filled with a value?
+        #e.g. values[0], values[1] and values[2] don't return nil given a index of 0 and a colspan of 3
+        number_of_nil_values = 0
+        cell.colspan.times do |i|
+          number_of_nil_values += 1 if values[index+i].nil?
+        end
+
+        #nothing to do? because
+        #a) all values are filled
+        return values if number_of_nil_values == 0
+        #b) no values are filled
+        return values if number_of_nil_values == cell.colspan
+        #c) I am not sure why this line is needed FIXXME
+        #some test cases manage to this line even though there is no dummy cell in the row
+        #I'm not sure if this is a sign for a further underlying bug.
+        return values unless has_a_span_dummy?(cell.row)
+        #fill up the values array
+
+        #calculate the new sum
+        new_sum = cell.send(meth) * cell.colspan
+        #substract any calculated values
+        cell.colspan.times do |i|
+          new_sum -= values[index+i] unless values[index+i].nil?
+        end
+
+        #calculate value for the remaining - not yet filled - cells.
+        new_value = new_sum.to_f / number_of_nil_values
+        #fill the not yet filled cells
+        cell.colspan.times do |i|
+          values[index+i] = new_value if values[index+i].nil?
+        end
+        return values
+      end
+
+      def natural_widths
+        #calculate natural column width for all rows that do not include a span dummy
+        @cells.each do |cell|
+          unless has_a_span_dummy?(cell.row)
+            @widths_by_column[cell.column] =
+              [@widths_by_column[cell.column], cell.width.to_f].max
+          end
+        end
+
+        #integrate natural column widths for all rows that do include a span dummy
+        @cells.each do |cell|
+          next unless has_a_span_dummy?(cell.row)
+          #the width of a SpanDummy cell will be calculated by the "mother" cell
+          next if cell.is_a?(Cell::SpanDummy)
+
+          if cell.colspan == 1
+            @widths_by_column[cell.column] =
+              [@widths_by_column[cell.column], cell.width.to_f].max
+          else
+            #calculate the current with of all cells that will be spanned by the current cell
+            current_width_of_spanned_cells =
+              @widths_by_column.to_a[cell.column..(cell.column + cell.colspan - 1)]
+                               .collect{|key, value| value}.inject(0, :+)
+
+            #update the Hash only if the new with is at least equal to the old one
+            #due to arithmetic errors we need to ignore a small difference in the new and the old sum
+            #the same had to be done in the column_widht_calculator#natural_width
+            update_hash = ((cell.width.to_f - current_width_of_spanned_cells) >
+                           Prawn::FLOAT_PRECISION)
+
+            if update_hash
+              # Split the width of colspanned cells evenly by columns
+              width_per_column = cell.width.to_f / cell.colspan
+              # Update the Hash
+              cell.colspan.times do |i|
+                @widths_by_column[cell.column + i] = width_per_column
+              end
+            end
+          end
+        end
+
+        @widths_by_column.sort_by { |col, _| col }.map { |_, w| w }
+      end
+
+      # get column widths (either min or max depending on meth)
+      # used in cells.rb
+      #
+      # @param row_or_column - you may call this on either rows or columns
+      # @param meth - min/max
+      # @param aggregate - functions from cell.rb to be used to aggregate e.g. avg_spanned_min_width
+      #
+      def aggregate_cell_values(row_or_column, meth, aggregate)
+        values = {}
+
+        #calculate values for all cells that do not span accross multiple cells
+        #this ensures that we don't have a problem if the first line includes
+        #a cell that spans across multiple cells
+        @cells.each do |cell|
+          #don't take spanned cells
+          if cell.colspan == 1 and cell.class != Prawn::Table::Cell::SpanDummy
+            index = cell.send(row_or_column)
+            values[index] = [values[index], cell.send(meth)].compact.send(aggregate)
+          end
+        end
+
+        # if there are only colspanned or rowspanned cells in a table
+        spanned_width_needs_fixing = true
+
+        @cells.each do |cell|
+          index = cell.send(row_or_column)
+          if cell.colspan > 1
+            #special treatment if some but not all spanned indices in the values array have been calculated
+            #only applies to rows
+            values = fill_values_if_needed(values, cell, index, meth) if row_or_column == :column
+            #calculate current (old) return value before we do anything
+            old_sum = 0
+            cell.colspan.times { |i|
+              old_sum += values[index+i] unless values[index+i].nil?
+            }
+
+            #calculate future return value
+            new_sum = cell.send(meth) * cell.colspan
+
+            #due to float rounding errors we need to ignore a small difference in the new
+            #and the old sum the same had to be done in
+            #the column_width_calculator#natural_width
+            spanned_width_needs_fixing = ((new_sum - old_sum) > Prawn::FLOAT_PRECISION)
+
+            if spanned_width_needs_fixing
+              #not entirely sure why we need this line, but with it the tests pass
+              values[index] = [values[index], cell.send(meth)].compact.send(aggregate)
+              #overwrite the old values with the new ones, but only if all entries existed
+              entries_exist = true
+              cell.colspan.times { |i| entries_exist = false if values[index+i].nil? }
+              cell.colspan.times { |i|
+                values[index+i] = cell.send(meth) if entries_exist
+              }
+            end
+          else
+            if spanned_width_needs_fixing && cell.class == Prawn::Table::Cell::SpanDummy
+              values[index] = [values[index], cell.send(meth)].compact.send(aggregate)
+            end
+          end
+        end
+
+        return values.values.inject(0, &:+)
+      end
+    end
+
+  end
+end

data/manual/contents.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+#
+# Generates the Prawn by example manual.
+
+require_relative "example_helper"
+
+Encoding.default_external = Encoding::UTF_8
+
+Prawn::ManualBuilder::Example.generate("manual.pdf",
+  :skip_page_creation => true, :page_size => "FOLIO") do
+
+  load_package "table"
+end

data/manual/example_helper.rb

@@ -0,0 +1,8 @@
+# encoding: UTF-8
+
+require "prawn"
+require_relative "../lib/prawn/table"
+
+require "prawn/manual_builder"
+
+Prawn::ManualBuilder.manual_dir = File.dirname(__FILE__)

data/manual/table/basic_block.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+#
+# All of the previous styling options we've seen deal with all the table cells
+# at once.
+#
+# With initializer blocks we may deal with specific cells.
+# A block passed to one of the table methods (<code>Prawn::Table.new</code>,
+# <code>Prawn::Document#table</code>, <code>Prawn::Document#make_table</code>)
+# will be called after cell setup but before layout. This is a very flexible way
+# to specify styling and layout constraints.
+#
+# Just like the <code>Prawn::Document.generate</code> method, the table
+# initializer blocks may be used with and without a block argument.
+#
+# The table class has three methods that are handy within an initializer block:
+# <code>cells</code>, <code>rows</code> and <code>columns</code>. All three
+# return an instance of <code>Prawn::Table::Cells</code> which represents
+# a selection of cells.
+#
+# <code>cells</code> return all the table cells, while <code>rows</code> and
+# <code>columns</code> accept a number or a range as argument which returns a
+# single row/column or a range of rows/columns respectively. (<code>rows</code>
+# and <code>columns</code> are also aliased as <code>row</code> and
+# <code>column</code>)
+#
+# The <code>Prawn::Table::Cells</code> class also defines <code>rows</code> and
+# <code>columns</code> so they may be chained to narrow the selection of cells.
+#
+# All of the cell styling options we've seen on previous examples may be set as
+# properties of the selection of cells.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["Header",           "A " * 5, "B"],
+           ["Data row",         "C",      "D " * 5],
+           ["Another data row", "E",      "F"]]
+
+  table(data) do
+    cells.padding = 12
+    cells.borders = []
+
+    row(0).borders      = [:bottom]
+    row(0).border_width = 2
+    row(0).font_style   = :bold
+
+    columns(0..1).borders = [:right]
+
+    row(0).columns(0..1).borders = [:bottom, :right]
+  end
+end

data/manual/table/before_rendering_page.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+#
+# <code>Prawn::Table#initialize</code> takes a
+# <code>:before_rendering_page</code> argument, to adjust the way an entire page
+# of table cells is styled. This allows you to do things like draw a border
+# around the entire table as displayed on a page.
+#
+# The callback is passed a Cells object that is numbered based on the order of
+# the cells on the page (e.g., the first row on the page is
+# <code>cells.row(0)</code>).
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  table([["foo", "bar", "baz"]] * 40) do |t|
+    t.cells.border_width = 1
+    t.before_rendering_page do |page|
+      page.row(0).border_top_width       = 3
+      page.row(-1).border_bottom_width   = 3
+      page.column(0).border_left_width   = 3
+      page.column(-1).border_right_width = 3
+    end
+  end
+end

data/manual/table/cell_border_lines.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+#
+# The <code>border_lines</code> option accepts an array with the styles of the
+# border sides. The default is <code>[:solid, :solid, :solid, :solid]</code>.
+#
+# <code>border_lines</code> must be set to an array.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data =  [ ["Look at how the cell border lines can be mixed", "", ""],
+            ["dotted top border", "", ""],
+            ["solid right border", "", ""],
+            ["dotted bottom border", "", ""],
+            ["dashed left border", "", ""]
+          ]
+
+  text "Cell :border_lines => [:dotted, :solid, :dotted, :dashed]"
+
+  table(data, :cell_style =>
+    { :border_lines => [:dotted, :solid, :dotted, :dashed] })
+end

data/manual/table/cell_borders_and_bg.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+#
+# The <code>borders</code> option accepts an array with the border sides that
+# will be drawn. The default is <code>[:top, :bottom, :left, :right]</code>.
+#
+# <code>border_width</code> may be set with a numeric value.
+#
+# Both <code>border_color</code> and <code>background_color</code> accept an
+# HTML like RGB color string ("FF0000")
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["Look at how the cells will look when styled", "", ""],
+           ["They probably won't look the same", "", ""]
+         ]
+
+  { :borders => [:top, :left],
+    :border_width => 3,
+    :border_color => "FF0000"}.each do |property, value|
+
+      text "Cell #{property}: #{value.inspect}"
+      table(data, :cell_style => {property => value})
+      move_down 20
+  end
+
+  text "Cell background_color: FFFFCC"
+  table(data, :cell_style => {:background_color => "FFFFCC"})
+end

data/manual/table/cell_dimensions.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+#
+# To style all the table cells you can use the <code>:cell_style</code> option
+# with the table methods. It accepts a hash with the cell style options.
+#
+# Some straightforward options are <code>width</code>, <code>height</code>,
+# and <code>padding</code>. All three accept numeric values to set the property.
+#
+# <code>padding</code> also accepts a four number array that defines the padding
+# in a CSS like syntax setting the top, right, bottom, left sequentially. The
+# default is 5pt for all sides.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["Look at how the cells will look when styled", "", ""],
+           ["They probably won't look the same", "", ""]
+         ]
+
+  {:width => 160, :height => 50, :padding => 12}.each do |property, value|
+    text "Cell's #{property}: #{value}"
+    table(data, :cell_style => {property => value})
+    move_down 20
+  end
+
+  text "Padding can also be set with an array: [0, 0, 0, 30]"
+  table(data, :cell_style => {:padding => [0, 0, 0, 30]})
+end

data/manual/table/cell_text.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+#
+# Text cells accept the following options: <code>align</code>,
+# <code>font</code>, <code>font_style</code>, <code>inline_format</code>,
+# <code>kerning</code>, <code>leading</code>, <code>min_font_size</code>,
+# <code>overflow</code>, <code>rotate</code>, <code>rotate_around</code>,
+# <code>single_line</code>, <code>size</code>, <code>text_color</code>,
+# and <code>valign</code>.
+#
+# Most of these style options are direct translations from the text methods
+# styling options.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["Look at how the cells will look when styled", "", ""],
+           ["They probably won't look the same", "", ""]
+         ]
+
+  table data, :cell_style => { :font => "Times-Roman", :font_style => :italic }
+  move_down 20
+
+  table data, :cell_style => { :size => 18, :text_color => "346842" }
+  move_down 20
+
+  table [["Just <font size='18'>some</font> <b><i>inline</i></b>", "", ""],
+         ["<color rgb='FF00FF'>styles</color> being applied here", "", ""]],
+         :cell_style => { :inline_format => true }
+  move_down 20
+
+  table [["1", "2", "3", "rotate"]], :cell_style => { :rotate => 30 }
+  move_down 20
+
+  table data, :cell_style => { :overflow => :shrink_to_fit, :min_font_size => 8,
+                               :width => 60, :height => 30 }
+end

data/manual/table/column_widths.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+#
+# Prawn will make its best attempt to identify the best width for the columns.
+# If the end result isn't good, we can override it with some styling.
+#
+# Individual column widths can be set with the <code>:column_widths</code>
+# option. Just provide an array with the sequential width values for the columns
+# or a hash were each key-value pair represents the column 0-based index and its
+# width.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  data = [ ["this is not quite as long as the others",
+            "here we have a line that is long but with smaller words",
+            "this is so very looooooooooooooooooooooooooooooong"] ]
+
+  text "Prawn trying to guess the column widths"
+  table(data)
+  move_down 20
+
+  text "Manually setting all the column widths"
+  table(data, :column_widths => [100, 200, 240])
+  move_down 20
+
+  text "Setting only the last column width"
+  table(data, :column_widths => {2 => 240})
+end