prawn 0.11.1 → 0.15.0

data/lib/prawn/table/cell.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8   
+# encoding: utf-8
 
 # cell.rb: Table cell drawing.
 #
@@ -6,10 +6,13 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
+require 'date'
 module Prawn
   class Document
 
-    # Instantiates and draws a cell on the document. 
+    # @group Experimental API
+
+    # Instantiates and draws a cell on the document.
     #
     #   cell(:content => "Hello world!", :at => [12, 34])
     #
@@ -20,9 +23,9 @@ module Prawn
       cell.draw
       cell
     end
-    
-    # Set up, but do not draw, a cell. Useful for creating cells with 
-    # formatting options to be inserted into a Table. Call +draw+ on the 
+
+    # Set up, but do not draw, a cell. Useful for creating cells with
+    # formatting options to be inserted into a Table. Call +draw+ on the
     # resulting Cell to ink it.
     #
     # See the documentation on Prawn::Cell for details on the arguments.
@@ -34,7 +37,7 @@ module Prawn
   end
 
   class Table
-    
+
     # A Cell is a rectangular area of the page into which content is drawn. It
     # has a framework for sizing itself and adding padding and simple styling.
     # There are several standard Cell subclasses that handle things like text,
@@ -53,20 +56,58 @@ module Prawn
       #
       attr_reader :padding
 
-      # If provided, the minimum width that this cell will permit.
-      # 
-      def min_width
+      # If provided, the minimum width that this cell in its column will permit.
+      #
+      def min_width_ignoring_span
         set_width_constraints
         @min_width
       end
-      
-      # If provided, the maximum width that this cell can be drawn in.
+
+      # Minimum width of the entire span group this cell controls.
       #
-      def max_width
+      def min_width
+        return min_width_ignoring_span if @colspan == 1
+
+        # Sum up the largest min-width from each column, including myself.
+        min_widths = Hash.new(0)
+        dummy_cells.each do |cell|
+          min_widths[cell.column] =
+            [min_widths[cell.column], cell.min_width].max
+        end
+        min_widths[column] = [min_widths[column], min_width_ignoring_span].max
+        min_widths.values.inject(0, &:+)
+      end
+
+      # Min-width of the span divided by the number of columns.
+      #
+      def avg_spanned_min_width
+        min_width.to_f / colspan
+      end
+
+      # If provided, the maximum width that this cell can be drawn in, within
+      # its column.
+      #
+      def max_width_ignoring_span
         set_width_constraints
         @max_width
       end
 
+      # Maximum width of the entire span group this cell controls.
+      #
+      def max_width
+        return max_width_ignoring_span if @colspan == 1
+
+        # Sum the smallest max-width from each column in the group, including
+        # myself.
+        max_widths = Hash.new(0)
+        dummy_cells.each do |cell|
+          max_widths[cell.column] =
+            [max_widths[cell.column], cell.max_width].min
+        end
+        max_widths[column] = [max_widths[column], max_width_ignoring_span].min
+        max_widths.values.inject(0, &:+)
+      end
+
       # Manually specify the cell's height.
       #
       attr_writer :height
@@ -84,11 +125,15 @@ module Prawn
       #
       attr_reader :border_colors
 
+      # Line style
+      #
+      attr_reader :border_lines
+
       # Specifies the content for the cell. Must be a "cellable" object. See the
       # "Data" section of the Prawn::Table documentation for details on cellable
       # objects.
       #
-      attr_accessor :content 
+      attr_accessor :content
 
       # The background color, if any, for this cell. Specified in HTML RGB
       # format, e.g., "ccffff". The background is drawn under the whole cell,
@@ -96,6 +141,21 @@ module Prawn
       #
       attr_accessor :background_color
 
+      # Number of columns this cell spans. Defaults to 1.
+      #
+      attr_reader :colspan
+
+      # Number of rows this cell spans. Defaults to 1.
+      #
+      attr_reader :rowspan
+
+      # Array of SpanDummy cells (if any) that represent the other cells in
+      # this span group. They know their own width / height, but do not draw
+      # anything.
+      #
+      # @private
+      attr_reader :dummy_cells 
+
       # Instantiates a Cell based on the given options. The particular class of
       # cell returned depends on the :content argument. See the Prawn::Table
       # documentation under "Data" for allowable content types.
@@ -104,14 +164,19 @@ module Prawn
         at = options.delete(:at) || [0, pdf.cursor]
         content = content.to_s if content.nil? || content.kind_of?(Numeric) ||
           content.kind_of?(Date)
-        
+
         if content.is_a?(Hash)
+          if content[:image]
+            return Cell::Image.new(pdf, at, content)
+          end
           options.update(content)
           content = options[:content]
         else
           options[:content] = content
         end
 
+        options[:content] = content = "" if content.nil?
+
         case content
         when Prawn::Table::Cell
           content
@@ -123,8 +188,7 @@ module Prawn
           subtable = Prawn::Table.new(options[:content], pdf, {})
           Cell::Subtable.new(pdf, at, options.merge(:content => subtable))
         else
-          # TODO: other types of content
-          raise ArgumentError, "Content type not recognized: #{content.inspect}"
+          raise Errors::UnrecognizedTableContent
         end
       end
 
@@ -151,8 +215,14 @@ module Prawn
         @borders       = [:top, :bottom, :left, :right]
         @border_widths = [1] * 4
         @border_colors = ['000000'] * 4
+        @border_lines  = [:solid] * 4
+        @colspan = 1
+        @rowspan = 1
+        @dummy_cells = []
 
         options.each { |k, v| send("#{k}=", v) }
+
+        @initializer_run = true
       end
 
       # Supports setting multiple properties at once.
@@ -165,19 +235,40 @@ module Prawn
       #   cell.border_width = 2
       #
       def style(options={}, &block)
-        options.each { |k, v| send("#{k}=", v) }
+        options.each do |k, v|
+          send("#{k}=", v) if respond_to?("#{k}=")
+        end
 
         # The block form supports running a single block for multiple cells, as
         # in Cells#style.
         block.call(self) if block
       end
 
-      # Returns the cell's width in points, inclusive of padding.
+      # Returns the width of the cell in its first column alone, ignoring any
+      # colspans.
       #
-      def width
+      def width_ignoring_span
         # We can't ||= here because the FP error accumulates on the round-trip
         # from #content_width.
-        @width || (content_width + padding_left + padding_right)
+        defined?(@width) && @width || (content_width + padding_left + padding_right)
+      end
+
+      # Returns the cell's width in points, inclusive of padding. If the cell is
+      # the master cell of a colspan, returns the width of the entire span
+      # group.
+      #
+      def width
+        return width_ignoring_span if @colspan == 1 && @rowspan == 1
+
+        # We're in a span group; get the maximum width per column (including
+        # the master cell) and sum each column.
+        column_widths = Hash.new(0)
+        dummy_cells.each do |cell|
+          column_widths[cell.column] =
+            [column_widths[cell.column], cell.width].max
+        end
+        column_widths[column] = [column_widths[column], width_ignoring_span].max
+        column_widths.values.inject(0, &:+)
       end
 
       # Manually sets the cell's width, inclusive of padding.
@@ -189,59 +280,156 @@ module Prawn
       # Returns the width of the bare content in the cell, excluding padding.
       #
       def content_width
-        if @width # manually set
+        if defined?(@width) && @width # manually set
           return @width - padding_left - padding_right
         end
 
         natural_content_width
       end
 
+      # Width of the entire span group.
+      #
+      def spanned_content_width
+        width - padding_left - padding_right
+      end
+
       # Returns the width this cell would naturally take on, absent other
       # constraints. Must be implemented in subclasses.
       #
       def natural_content_width
-        raise NotImplementedError, 
+        raise NotImplementedError,
           "subclasses must implement natural_content_width"
       end
 
-      # Returns the cell's height in points, inclusive of padding.
+      # Returns the cell's height in points, inclusive of padding, in its first
+      # row only.
       #
-      def height
+      def height_ignoring_span
         # We can't ||= here because the FP error accumulates on the round-trip
         # from #content_height.
-        @height || (content_height + padding_top + padding_bottom)
+        defined?(@height) && @height || (content_height + padding_top + padding_bottom)
+      end
+
+      # Returns the cell's height in points, inclusive of padding. If the cell
+      # is the master cell of a rowspan, returns the width of the entire span
+      # group.
+      #
+      def height
+        return height_ignoring_span if @colspan == 1 && @rowspan == 1
+
+        # We're in a span group; get the maximum height per row (including the
+        # master cell) and sum each row.
+        row_heights = Hash.new(0)
+        dummy_cells.each do |cell|
+          row_heights[cell.row] = [row_heights[cell.row], cell.height].max
+        end
+        row_heights[row] = [row_heights[row], height_ignoring_span].max
+        row_heights.values.inject(0, &:+)
       end
 
       # Returns the height of the bare content in the cell, excluding padding.
       #
       def content_height
-        if @height # manually set
+        if defined?(@height) && @height # manually set
           return @height - padding_top - padding_bottom
         end
-        
+
         natural_content_height
       end
 
+      # Height of the entire span group.
+      #
+      def spanned_content_height
+        height - padding_top - padding_bottom
+      end
+
       # Returns the height this cell would naturally take on, absent
       # constraints. Must be implemented in subclasses.
       #
       def natural_content_height
-        raise NotImplementedError, 
+        raise NotImplementedError,
           "subclasses must implement natural_content_height"
       end
 
+      # Indicates the number of columns that this cell is to span. Defaults to
+      # 1.
+      #
+      # This must be provided as part of the table data, like so:
+      #
+      #   pdf.table([["foo", {:content => "bar", :colspan => 2}]])
+      #
+      # Setting colspan from the initializer block is invalid because layout
+      # has already run. For example, this will NOT work:
+      #
+      #   pdf.table([["foo", "bar"]]) { cells[0, 1].colspan = 2 }
+      #
+      def colspan=(span)
+        if defined?(@initializer_run) && @initializer_run
+          raise Prawn::Errors::InvalidTableSpan,
+            "colspan must be provided in the table's structure, never in the " +
+            "initialization block. See Prawn's documentation for details."
+        end
+
+        @colspan = span
+      end
+
+      # Indicates the number of rows that this cell is to span. Defaults to 1.
+      #
+      # This must be provided as part of the table data, like so:
+      #
+      #   pdf.table([["foo", {:content => "bar", :rowspan => 2}], ["baz"]])
+      #
+      # Setting rowspan from the initializer block is invalid because layout
+      # has already run. For example, this will NOT work:
+      #
+      #   pdf.table([["foo", "bar"], ["baz"]]) { cells[0, 1].rowspan = 2 }
+      #
+      def rowspan=(span)
+        if defined?(@initializer_run) && @initializer_run
+          raise Prawn::Errors::InvalidTableSpan,
+            "rowspan must be provided in the table's structure, never in the " +
+            "initialization block. See Prawn's documentation for details."
+        end
+
+        @rowspan = span
+      end
+
       # Draws the cell onto the document. Pass in a point [x,y] to override the
       # location at which the cell is drawn.
       #
+      # If drawing a group of cells at known positions, look into
+      # Cell.draw_cells, which ensures that the backgrounds, borders, and
+      # content are all drawn in correct order so as not to overlap.
+      #
       def draw(pt=[x, y])
-        set_width_constraints
+        Prawn::Table::Cell.draw_cells([[self, pt]])
+      end
 
-        draw_background(pt)
-        draw_borders(pt)
-        @pdf.bounding_box([pt[0] + padding_left, pt[1] - padding_top], 
-                          :width  => content_width + FPTolerance,
-                          :height => content_height + FPTolerance) do
-          draw_content
+      # Given an array of pairs [cell, pt], draws each cell at its
+      # corresponding pt, making sure all backgrounds are behind all borders
+      # and content.
+      #
+      def self.draw_cells(cells)
+        cells.each do |cell, pt|
+          cell.set_width_constraints
+          cell.draw_background(pt)
+        end
+
+        cells.each do |cell, pt|
+          cell.draw_borders(pt)
+          cell.draw_bounded_content(pt)
+        end
+      end
+
+      # Draws the cell's content at the point provided.
+      #
+      def draw_bounded_content(pt)
+        @pdf.float do
+          @pdf.bounding_box([pt[0] + padding_left, pt[1] - padding_top],
+                            :width  => spanned_content_width + FPTolerance,
+                            :height => spanned_content_height + FPTolerance) do
+            draw_content
+          end
         end
       end
 
@@ -297,7 +485,7 @@ module Prawn
       def padding_top
         @padding[0]
       end
-      
+
       def padding_top=(val)
         @padding[0] = val
       end
@@ -305,7 +493,7 @@ module Prawn
       def padding_right
         @padding[1]
       end
-      
+
       def padding_right=(val)
         @padding[1] = val
       end
@@ -313,7 +501,7 @@ module Prawn
       def padding_bottom
         @padding[2]
       end
-      
+
       def padding_bottom=(val)
         @padding[2] = val
       end
@@ -321,7 +509,7 @@ module Prawn
       def padding_left
         @padding[3]
       end
-      
+
       def padding_left=(val)
         @padding[3] = val
       end
@@ -360,14 +548,6 @@ module Prawn
         @border_colors[0] = val
       end
 
-      def border_top_color
-        @border_colors[0]
-      end
-
-      def border_top_color=(val)
-        @border_colors[0] = val
-      end
-
       def border_right_color
         @border_colors[1]
       end
@@ -450,8 +630,6 @@ module Prawn
         @border_widths[3] = val
       end
 
-      protected
-
       # Sets the cell's minimum and maximum width. Deferred until requested
       # because padding and size can change.
       #
@@ -460,10 +638,70 @@ module Prawn
         @max_width ||= @pdf.bounds.width
       end
 
+      # Sets border line style on this cell. The argument can be one of:
+      #
+      # Possible values are: :solid, :dashed, :dotted
+      #
+      # * one value (sets all lines)
+      # * a two-element array [vertical, horizontal]
+      # * a three-element array [top, horizontal, bottom]
+      # * a four-element array [top, right, bottom, left]
+      #
+      def border_line=(line)
+        @border_lines = case
+        when line.nil?
+          [:solid] * 4
+        when line.length == 1 # all lines
+          [line[0]] * 4
+        when line.length == 2
+          [line[0], line[1], line[0], line[1]]
+        when line.length == 3
+          [line[0], line[1], line[2], line[1]]
+        when line.length == 4
+          [line[0], line[1], line[2], line[3]]
+        else
+          raise ArgumentError, "border_line must be one of :solid, :dashed, "
+            ":dotted or an array [v,h] or [t,r,b,l]"
+        end
+      end
+      alias_method :border_lines=, :border_line=
+
+      def border_top_line
+        @borders.include?(:top) ? @border_lines[0] : 0
+      end
+
+      def border_top_line=(val)
+        @border_lines[0] = val
+      end
+
+      def border_right_line
+        @borders.include?(:right) ? @border_lines[1] : 0
+      end
+
+      def border_right_line=(val)
+        @border_lines[1] = val
+      end
+
+      def border_bottom_line
+        @borders.include?(:bottom) ? @border_lines[2] : 0
+      end
+
+      def border_bottom_line=(val)
+        @border_lines[2] = val
+      end
+
+      def border_left_line
+        @borders.include?(:left) ? @border_lines[3] : 0
+      end
+
+      def border_left_line=(val)
+        @border_lines[3] = val
+      end
+
       # Draws the cell's background color.
       #
       def draw_background(pt)
-        if @background_color
+        if defined?(@background_color) && @background_color
           @pdf.mask(:fill_color) do
             @pdf.fill_color @background_color
             @pdf.fill_rectangle pt, width, height
@@ -484,6 +722,7 @@ module Prawn
             idx = {:top => 0, :right => 1, :bottom => 2, :left => 3}[border]
             border_color = @border_colors[idx]
             border_width = @border_widths[idx]
+            border_line  = @border_lines[idx]
 
             next if border_width <= 0
 
@@ -502,9 +741,22 @@ module Prawn
                           [x+width, y - height - (border_bottom_width / 2.0)]]
                        end
 
+            case border_line
+            when :dashed
+              @pdf.dash border_width * 4
+            when :dotted
+              @pdf.dash border_width, :space => border_width * 2
+            when :solid
+              # normal line style
+            else
+              raise ArgumentError, "border_line must be :solid, :dotted or" +
+                " :dashed"
+            end
+
             @pdf.line_width   = border_width
             @pdf.stroke_color = border_color
             @pdf.stroke_line(from, to)
+            @pdf.undash
           end
         end
       end