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.



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/prawn/table/cell.rb', line 133

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.



92
93
94
 
# File 'lib/prawn/table/cell.rb', line 92

def background_color
  @background_color
end

#border_color ⇒ Object

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



80
81
82
 
# File 'lib/prawn/table/cell.rb', line 80

def border_color
  @border_color
end

#border_width ⇒ Object

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



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

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].



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

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.



86
87
88
 
# File 'lib/prawn/table/cell.rb', line 86

def content
  @content
end

#height ⇒ Object

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



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

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.



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

def max_width
  @max_width
end

#min_width ⇒ Object (readonly)

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



58
59
60
 
# File 'lib/prawn/table/cell.rb', line 58

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.



54
55
56
 
# File 'lib/prawn/table/cell.rb', line 54

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.



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/prawn/table/cell.rb', line 98

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.



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

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.



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

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.



211
212
213
214
215
216
217
218
219
 
# File 'lib/prawn/table/cell.rb', line 211

def draw(pt=[x, y])
  draw_background(pt)
  @pdf.bounding_box([pt[0] + padding_left, pt[1] - padding_top], 
                    :width  => content_width + FPTolerance,
                    :height => content_height + FPTolerance) do
    draw_content
  end
  draw_borders(pt)
end

#natural_content_height ⇒ Object

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

Raises:

  • (NotImplementedError) 


203
204
205
206
 
# File 'lib/prawn/table/cell.rb', line 203

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) 


177
178
179
180
 
# File 'lib/prawn/table/cell.rb', line 177

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.



152
153
154
155
156
 
# File 'lib/prawn/table/cell.rb', line 152

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.



160
161
162
 
# File 'lib/prawn/table/cell.rb', line 160

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

#x ⇒ Object

x-position of the cell within the parent bounds.



223
224
225
 
# File 'lib/prawn/table/cell.rb', line 223

def x
  @point[0]
end

#x=(val) ⇒ Object

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



229
230
231
 
# File 'lib/prawn/table/cell.rb', line 229

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

#y ⇒ Object

y-position of the cell within the parent bounds.



235
236
237
 
# File 'lib/prawn/table/cell.rb', line 235

def y
  @point[1]
end

#y=(val) ⇒ Object

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



241
242
243
 
# File 'lib/prawn/table/cell.rb', line 241

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