Parent

Prawn::Table::Cell

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, Tables, and (in the future) stamps, images, and arbitrary content.

Cells are a basic building block for table support (see Prawn::Table).

Please subclass me if you want new content types! I'm designed to be very extensible. See the different standard Cell subclasses in lib/prawn/table/cell/*.rb for a template.

Constants

FPTolerance

A small amount added to the bounding box width to cover over floating- point errors when round-tripping from content_width to width and back. This does not change cell positioning; it only slightly expands each cell's bounding box width so that rounding error does not prevent a cell from rendering.

Attributes

background_color[RW]

The background color, if any, for this cell. Specified in HTML RGB format, e.g., "ccffff". The background is drawn under the whole cell, including any padding.

border_colors[R]

HTML RGB-format ("ccffff") border colors: [top, right, bottom, left].

border_widths[R]

Width, in PDF points, of the cell's borders: [top, right, bottom, left].

borders[RW]

Specifies which borders to enable. Must be an array of zero or more of: [:left, :right, :top, :bottom].

content[RW]

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.

height[W]

Manually specify the cell's height.

padding[R]

Amount of dead space (in PDF points) inside the borders but outside the content. Padding defaults to 5pt.

Public Class Methods

draw_cells(cells) click to toggle source

Given an array of pairs [cell, pt], draws each cell at its corresponding pt, making sure all backgrounds are behind all borders and content.

# File lib/prawn/table/cell.rb, line 247
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
make(pdf, content, options={}) click to toggle source

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.

# File lib/prawn/table/cell.rb, line 102
def self.make(pdf, content, options={})
  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)
    options.update(content)
    content = options[:content]
  else
    options[:content] = content
  end

  case content
  when Prawn::Table::Cell
    content
  when String
    Cell::Text.new(pdf, at, options)
  when Prawn::Table
    Cell::Subtable.new(pdf, at, options)
  when Array
    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}"
  end
end
new(pdf, point, options={}) click to toggle source

Sets up a cell on the document pdf, at the given x/y location point, with the given options. Cell, like Table, follows the "options set accessors" paradigm (see "Options" under the Table documentation), so any cell accessor cell.foo = :bar can be set by providing the option :foo => :bar here.

# File lib/prawn/table/cell.rb, line 144
def initialize(pdf, point, options={})
  @pdf   = pdf
  @point = point

  # Set defaults; these can be changed by options
  @padding       = [5, 5, 5, 5]
  @borders       = [:top, :bottom, :left, :right]
  @border_widths = [1] * 4
  @border_colors = ['000000'] * 4

  options.each { |k, v| send("#{k}=", v) }
end

Public Instance Methods

border_bottom_color() click to toggle source
# File lib/prawn/table/cell.rb, line 402
def border_bottom_color
  @border_colors[2]
end
border_bottom_color=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 406
def border_bottom_color=(val)
  @border_colors[2] = val
end
border_bottom_width() click to toggle source
# File lib/prawn/table/cell.rb, line 460
def border_bottom_width
  @borders.include?(:bottom) ? @border_widths[2] : 0
end
border_bottom_width=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 464
def border_bottom_width=(val)
  @border_widths[2] = val
end
border_color=(color) click to toggle source

Sets border colors on this cell. The argument can be one of:

  • an integer (sets all colors)

  • a two-element array [vertical, horizontal]

  • a three-element array [top, horizontal, bottom]

  • a four-element array [top, right, bottom, left]

# File lib/prawn/table/cell.rb, line 359
def border_color=(color)
  @border_colors = case
  when color.nil?
    ["000000"] * 4
  when String === color # all colors
    [color, color, color, color]
  when color.length == 2 # vert, horiz
    [color[0], color[1], color[0], color[1]]
  when color.length == 3 # top, horiz, bottom
    [color[0], color[1], color[2], color[1]]
  when color.length == 4 # top, right, bottom, left
    [color[0], color[1], color[2], color[3]]
  else
    raise ArgumentError, ":border_color must be a string " +
      "or an array [v,h] or [t,r,b,l]"
  end
end
Also aliased as: border_colors=
border_colors=(color) click to toggle source
Alias for: border_color=
border_left_color() click to toggle source
# File lib/prawn/table/cell.rb, line 410
def border_left_color
  @border_colors[3]
end
border_left_color=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 414
def border_left_color=(val)
  @border_colors[3] = val
end
border_left_width() click to toggle source
# File lib/prawn/table/cell.rb, line 468
def border_left_width
  @borders.include?(:left) ? @border_widths[3] : 0
end
border_left_width=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 472
def border_left_width=(val)
  @border_widths[3] = val
end
border_right_color() click to toggle source
# File lib/prawn/table/cell.rb, line 394
def border_right_color
  @border_colors[1]
end
border_right_color=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 398
def border_right_color=(val)
  @border_colors[1] = val
end
border_right_width() click to toggle source
# File lib/prawn/table/cell.rb, line 452
def border_right_width
  @borders.include?(:right) ? @border_widths[1] : 0
end
border_right_width=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 456
def border_right_width=(val)
  @border_widths[1] = val
end
border_top_color() click to toggle source
# File lib/prawn/table/cell.rb, line 378
def border_top_color
  @border_colors[0]
end
border_top_color=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 382
def border_top_color=(val)
  @border_colors[0] = val
end
border_top_width() click to toggle source
# File lib/prawn/table/cell.rb, line 444
def border_top_width
  @borders.include?(:top) ? @border_widths[0] : 0
end
border_top_width=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 448
def border_top_width=(val)
  @border_widths[0] = val
end
border_width=(width) click to toggle source

Sets border widths on this cell. The argument can be one of:

  • an integer (sets all widths)

  • a two-element array [vertical, horizontal]

  • a three-element array [top, horizontal, bottom]

  • a four-element array [top, right, bottom, left]

# File lib/prawn/table/cell.rb, line 425
def border_width=(width)
  @border_widths = case
  when width.nil?
    ["000000"] * 4
  when Numeric === width # all widths
    [width, width, width, width]
  when width.length == 2 # vert, horiz
    [width[0], width[1], width[0], width[1]]
  when width.length == 3 # top, horiz, bottom
    [width[0], width[1], width[2], width[1]]
  when width.length == 4 # top, right, bottom, left
    [width[0], width[1], width[2], width[3]]
  else
    raise ArgumentError, ":border_width must be a string " +
      "or an array [v,h] or [t,r,b,l]"
  end
end
Also aliased as: border_widths=
border_widths=(width) click to toggle source
Alias for: border_width=
content_height() click to toggle source

Returns the height of the bare content in the cell, excluding padding.

# File lib/prawn/table/cell.rb, line 216
def content_height
  if @height # manually set
    return @height - padding_top - padding_bottom
  end
  
  natural_content_height
end
content_width() click to toggle source

Returns the width of the bare content in the cell, excluding padding.

# File lib/prawn/table/cell.rb, line 190
def content_width
  if @width # manually set
    return @width - padding_left - padding_right
  end

  natural_content_width
end
draw(pt=[x, y]) click to toggle source

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.

# File lib/prawn/table/cell.rb, line 239
def draw(pt=[x, y])
  self.class.draw_cells([[self, pt]])
end
draw_background(pt) click to toggle source

Draws the cell's background color.

# File lib/prawn/table/cell.rb, line 486
def draw_background(pt)
  if @background_color
    @pdf.mask(:fill_color) do
      @pdf.fill_color @background_color
      @pdf.fill_rectangle pt, width, height
    end
  end
end
draw_borders(pt) click to toggle source

Draws borders around the cell. Borders are centered on the bounds of the cell outside of any padding, so the caller is responsible for setting appropriate padding to ensure the border does not overlap with cell content.

# File lib/prawn/table/cell.rb, line 500
def draw_borders(pt)
  x, y = pt

  @pdf.mask(:line_width, :stroke_color) do
    @borders.each do |border|
      idx = {:top => 0, :right => 1, :bottom => 2, :left => 3}[border]
      border_color = @border_colors[idx]
      border_width = @border_widths[idx]

      next if border_width <= 0

      # Left and right borders are drawn one-half border beyond the center
      # of the corner, so that the corners end up square.
      from, to = case border
                 when :top
                   [[x, y], [x+width, y]]
                 when :bottom
                   [[x, y-height], [x+width, y-height]]
                 when :left
                   [[x, y + (border_top_width / 2.0)],
                    [x, y - height - (border_bottom_width / 2.0)]]
                 when :right
                   [[x+width, y + (border_top_width / 2.0)],
                    [x+width, y - height - (border_bottom_width / 2.0)]]
                 end

      @pdf.line_width   = border_width
      @pdf.stroke_color = border_color
      @pdf.stroke_line(from, to)
    end
  end
end
draw_bounded_content(pt) click to toggle source

Draws the cell's content at the point provided.

# File lib/prawn/table/cell.rb, line 261
def draw_bounded_content(pt)
  @pdf.float do
    @pdf.bounding_box([pt[0] + padding_left, pt[1] - padding_top], 
                      :width  => content_width + FPTolerance,
                      :height => content_height + FPTolerance) do
      draw_content
    end
  end
end
draw_content() click to toggle source

Draws cell content within the cell's bounding box. Must be implemented in subclasses.

# File lib/prawn/table/cell.rb, line 536
def draw_content
  raise NotImplementedError, "subclasses must implement draw_content"
end
height() click to toggle source

Returns the cell's height in points, inclusive of padding.

# File lib/prawn/table/cell.rb, line 208
def height
  # We can't ||= here because the FP error accumulates on the round-trip
  # from #content_height.
  @height || (content_height + padding_top + padding_bottom)
end
max_width() click to toggle source

If provided, the maximum width that this cell can be drawn in.

# File lib/prawn/table/cell.rb, line 64
def max_width
  set_width_constraints
  @max_width
end
min_width() click to toggle source

If provided, the minimum width that this cell will permit.

# File lib/prawn/table/cell.rb, line 57
def min_width
  set_width_constraints
  @min_width
end
natural_content_height() click to toggle source

Returns the height this cell would naturally take on, absent constraints. Must be implemented in subclasses.

# File lib/prawn/table/cell.rb, line 227
def natural_content_height
  raise NotImplementedError, 
    "subclasses must implement natural_content_height"
end
natural_content_width() click to toggle source

Returns the width this cell would naturally take on, absent other constraints. Must be implemented in subclasses.

# File lib/prawn/table/cell.rb, line 201
def natural_content_width
  raise NotImplementedError, 
    "subclasses must implement natural_content_width"
end
padding=(pad) click to toggle source

Sets padding on this cell. The argument can be one of:

  • an integer (sets all padding)

  • a two-element array [vertical, horizontal]

  • a three-element array [top, horizontal, bottom]

  • a four-element array [top, right, bottom, left]

# File lib/prawn/table/cell.rb, line 302
def padding=(pad)
  @padding = case
  when pad.nil?
    [0, 0, 0, 0]
  when Numeric === pad # all padding
    [pad, pad, pad, pad]
  when pad.length == 2 # vert, horiz
    [pad[0], pad[1], pad[0], pad[1]]
  when pad.length == 3 # top, horiz, bottom
    [pad[0], pad[1], pad[2], pad[1]]
  when pad.length == 4 # top, right, bottom, left
    [pad[0], pad[1], pad[2], pad[3]]
  else
    raise ArgumentError, ":padding must be a number or an array [v,h] " +
      "or [t,r,b,l]"
  end
end
padding_bottom() click to toggle source
# File lib/prawn/table/cell.rb, line 336
def padding_bottom
  @padding[2]
end
padding_bottom=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 340
def padding_bottom=(val)
  @padding[2] = val
end
padding_left() click to toggle source
# File lib/prawn/table/cell.rb, line 344
def padding_left
  @padding[3]
end
padding_left=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 348
def padding_left=(val)
  @padding[3] = val
end
padding_right() click to toggle source
# File lib/prawn/table/cell.rb, line 328
def padding_right
  @padding[1]
end
padding_right=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 332
def padding_right=(val)
  @padding[1] = val
end
padding_top() click to toggle source
# File lib/prawn/table/cell.rb, line 320
def padding_top
  @padding[0]
end
padding_top=(val) click to toggle source
# File lib/prawn/table/cell.rb, line 324
def padding_top=(val)
  @padding[0] = val
end
set_width_constraints() click to toggle source

Sets the cell's minimum and maximum width. Deferred until requested because padding and size can change.

# File lib/prawn/table/cell.rb, line 479
def set_width_constraints
  @min_width ||= padding_left + padding_right
  @max_width ||= @pdf.bounds.width
end
style(options={}, &block) click to toggle source

Supports setting multiple properties at once.

cell.style(:padding => 0, :border_width => 2)

is the same as:

cell.padding = 0
cell.border_width = 2
# File lib/prawn/table/cell.rb, line 166
def style(options={}, &block)
  options.each { |k, v| send("#{k}=", v) }

  # The block form supports running a single block for multiple cells, as
  # in Cells#style.
  block.call(self) if block
end
width() click to toggle source

Returns the cell's width in points, inclusive of padding.

# File lib/prawn/table/cell.rb, line 176
def width
  # We can't ||= here because the FP error accumulates on the round-trip
  # from #content_width.
  @width || (content_width + padding_left + padding_right)
end
width=(w) click to toggle source

Manually sets the cell's width, inclusive of padding.

# File lib/prawn/table/cell.rb, line 184
def width=(w)
  @width = @min_width = @max_width = w
end
x() click to toggle source

x-position of the cell within the parent bounds.

# File lib/prawn/table/cell.rb, line 273
def x
  @point[0]
end
x=(val) click to toggle source

Set the x-position of the cell within the parent bounds.

# File lib/prawn/table/cell.rb, line 279
def x=(val)
  @point[0] = val
end
y() click to toggle source

y-position of the cell within the parent bounds.

# File lib/prawn/table/cell.rb, line 285
def y
  @point[1]
end
y=(val) click to toggle source

Set the y-position of the cell within the parent bounds.

# File lib/prawn/table/cell.rb, line 291
def y=(val)
  @point[1] = val
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.