Class: Prawn::Table::Cell

Inherits:
Object
  • Object
show all
Defined in:
lib/prawn/table/cell.rb,
lib/prawn/table/cell/text.rb,
lib/prawn/table/cell/in_table.rb,
lib/prawn/table/cell/subtable.rb

Overview

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.

Direct Known Subclasses

Subtable, Text

Defined Under Namespace

Modules: InTable Classes: Subtable, Text

Constant Summary collapse

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.

1

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(pdf, point, options = {}) ⇒ Cell

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.



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/prawn/table/cell.rb', line 123

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_width = 1
  @border_color = '000000'

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

  # Sensible defaults for min / max.
  @min_width = padding_left + padding_right
  @max_width = @pdf.bounds.width
end

Instance Attribute Details

#background_color ⇒ Object

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.



82
83
84
 
# File 'lib/prawn/table/cell.rb', line 82

def background_color
  @background_color
end

#border_color ⇒ Object

Specifies the color of the cell borders. Given in HTML RGB format, e.g., “ccffff”.



70
71
72
 
# File 'lib/prawn/table/cell.rb', line 70

def border_color
  @border_color
end

#border_width ⇒ Object

Specifies the width, in PDF points, of the cell’s borders.



65
66
67
 
# File 'lib/prawn/table/cell.rb', line 65

def border_width
  @border_width
end

#borders ⇒ Object

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



61
62
63
 
# File 'lib/prawn/table/cell.rb', line 61

def borders
  @borders
end

#content ⇒ Object

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.



76
77
78
 
# File 'lib/prawn/table/cell.rb', line 76

def content
  @content
end

#height ⇒ Object

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



174
175
176
177
178
 
# File 'lib/prawn/table/cell.rb', line 174

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 ⇒ Object (readonly)

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



52
53
54
 
# File 'lib/prawn/table/cell.rb', line 52

def max_width
  @max_width
end

#min_width ⇒ Object (readonly)

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



48
49
50
 
# File 'lib/prawn/table/cell.rb', line 48

def min_width
  @min_width
end

#padding ⇒ Object

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



44
45
46
 
# File 'lib/prawn/table/cell.rb', line 44

def padding
  @padding
end

Class Method Details

.make(pdf, content, options = {}) ⇒ Object

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.



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/prawn/table/cell.rb', line 88

def self.make(pdf, content, options={})
  at = options.delete(:at) || [0, pdf.cursor]
  content = "" if content.nil?
  options[:content] = content

  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

Instance Method Details

#content_height ⇒ Object

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



182
183
184
185
186
187
188
 
# File 'lib/prawn/table/cell.rb', line 182

def content_height
  if @height # manually set
    return @height - padding_top - padding_bottom
  end
  
  natural_content_height
end

#content_width ⇒ Object

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



156
157
158
159
160
161
162
 
# File 'lib/prawn/table/cell.rb', line 156

def content_width
  if @width # manually set
    return @width - padding_left - padding_right
  end

  natural_content_width
end

#draw(pt = [x, y]) ⇒ Object

Draws the cell onto the document. Pass in a point [x,y] to override the location at which the cell is drawn.



201
202
203
204
205
206
207
208
209
 
# File 'lib/prawn/table/cell.rb', line 201

def draw(pt=[x, y])
  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
  end
end

#natural_content_height ⇒ Object

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

Raises:

  • (NotImplementedError) 


193
194
195
196
 
# File 'lib/prawn/table/cell.rb', line 193

def natural_content_height
  raise NotImplementedError, 
    "subclasses must implement natural_content_height"
end

#natural_content_width ⇒ Object

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

Raises:

  • (NotImplementedError) 


167
168
169
170
 
# File 'lib/prawn/table/cell.rb', line 167

def natural_content_width
  raise NotImplementedError, 
    "subclasses must implement natural_content_width"
end

#width ⇒ Object

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



142
143
144
145
146
 
# File 'lib/prawn/table/cell.rb', line 142

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) ⇒ Object

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



150
151
152
 
# File 'lib/prawn/table/cell.rb', line 150

def width=(w)
  @width = @min_width = @max_width = w
end

#x ⇒ Object

x-position of the cell within the parent bounds.



213
214
215
 
# File 'lib/prawn/table/cell.rb', line 213

def x
  @point[0]
end

#x=(val) ⇒ Object

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



219
220
221
 
# File 'lib/prawn/table/cell.rb', line 219

def x=(val)
  @point[0] = val
end

#y ⇒ Object

y-position of the cell within the parent bounds.



225
226
227
 
# File 'lib/prawn/table/cell.rb', line 225

def y
  @point[1]
end

#y=(val) ⇒ Object

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



231
232
233
 
# File 'lib/prawn/table/cell.rb', line 231

def y=(val)
  @point[1] = val
end