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

padding[R]

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

height[W]

Manually specify the cell’s height.

borders[RW]

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

border_widths[R]

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

border_colors[R]

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

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.

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.

Public Class Methods

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 103
103:       def self.make(pdf, content, options={})
104:         at = options.delete(:at) || [0, pdf.cursor]
105:         content = content.to_s if content.nil? || content.kind_of?(Numeric) ||
106:           content.kind_of?(Date)
107:         
108:         if content.is_a?(Hash)
109:           options.update(content)
110:           content = options[:content]
111:         else
112:           options[:content] = content
113:         end
114: 
115:         case content
116:         when Prawn::Table::Cell
117:           content
118:         when String
119:           Cell::Text.new(pdf, at, options)
120:         when Prawn::Table
121:           Cell::Subtable.new(pdf, at, options)
122:         when Array
123:           subtable = Prawn::Table.new(options[:content], pdf, {})
124:           Cell::Subtable.new(pdf, at, options.merge(:content => subtable))
125:         else
126:           # TODO: other types of content
127:           raise ArgumentError, "Content type not recognized: #{content.inspect}"
128:         end
129:       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 145
145:       def initialize(pdf, point, options={})
146:         @pdf   = pdf
147:         @point = point
148: 
149:         # Set defaults; these can be changed by options
150:         @padding       = [5, 5, 5, 5]
151:         @borders       = [:top, :bottom, :left, :right]
152:         @border_widths = [1] * 4
153:         @border_colors = ['000000'] * 4
154: 
155:         options.each { |k, v| send("#{k}=", v) }
156:       end

Public Instance Methods

border_bottom_color() click to toggle source

     # File lib/prawn/table/cell.rb, line 379
379:       def border_bottom_color
380:         @border_colors[2]
381:       end

border_bottom_color=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 383
383:       def border_bottom_color=(val)
384:         @border_colors[2] = val
385:       end

border_bottom_width() click to toggle source

     # File lib/prawn/table/cell.rb, line 437
437:       def border_bottom_width
438:         @borders.include?(:bottom) ? @border_widths[2] : 0
439:       end

border_bottom_width=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 441
441:       def border_bottom_width=(val)
442:         @border_widths[2] = val
443:       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 336
336:       def border_color=(color)
337:         @border_colors = case
338:         when color.nil?
339:           ["000000"] * 4
340:         when String === color # all colors
341:           [color, color, color, color]
342:         when color.length == 2 # vert, horiz
343:           [color[0], color[1], color[0], color[1]]
344:         when color.length == 3 # top, horiz, bottom
345:           [color[0], color[1], color[2], color[1]]
346:         when color.length == 4 # top, right, bottom, left
347:           [color[0], color[1], color[2], color[3]]
348:         else
349:           raise ArgumentError, ":border_color must be a string " +
350:             "or an array [v,h] or [t,r,b,l]"
351:         end
352:       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 387
387:       def border_left_color
388:         @border_colors[3]
389:       end

border_left_color=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 391
391:       def border_left_color=(val)
392:         @border_colors[3] = val
393:       end

border_left_width() click to toggle source

     # File lib/prawn/table/cell.rb, line 445
445:       def border_left_width
446:         @borders.include?(:left) ? @border_widths[3] : 0
447:       end

border_left_width=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 449
449:       def border_left_width=(val)
450:         @border_widths[3] = val
451:       end

border_right_color() click to toggle source

     # File lib/prawn/table/cell.rb, line 371
371:       def border_right_color
372:         @border_colors[1]
373:       end

border_right_color=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 375
375:       def border_right_color=(val)
376:         @border_colors[1] = val
377:       end

border_right_width() click to toggle source

     # File lib/prawn/table/cell.rb, line 429
429:       def border_right_width
430:         @borders.include?(:right) ? @border_widths[1] : 0
431:       end

border_right_width=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 433
433:       def border_right_width=(val)
434:         @border_widths[1] = val
435:       end

border_top_color() click to toggle source

     # File lib/prawn/table/cell.rb, line 363
363:       def border_top_color
364:         @border_colors[0]
365:       end

border_top_color() click to toggle source

     # File lib/prawn/table/cell.rb, line 355
355:       def border_top_color
356:         @border_colors[0]
357:       end

border_top_color=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 367
367:       def border_top_color=(val)
368:         @border_colors[0] = val
369:       end

border_top_color=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 359
359:       def border_top_color=(val)
360:         @border_colors[0] = val
361:       end

border_top_width() click to toggle source

     # File lib/prawn/table/cell.rb, line 421
421:       def border_top_width
422:         @borders.include?(:top) ? @border_widths[0] : 0
423:       end

border_top_width=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 425
425:       def border_top_width=(val)
426:         @border_widths[0] = val
427:       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 402
402:       def border_width=(width)
403:         @border_widths = case
404:         when width.nil?
405:           ["000000"] * 4
406:         when Numeric === width # all widths
407:           [width, width, width, width]
408:         when width.length == 2 # vert, horiz
409:           [width[0], width[1], width[0], width[1]]
410:         when width.length == 3 # top, horiz, bottom
411:           [width[0], width[1], width[2], width[1]]
412:         when width.length == 4 # top, right, bottom, left
413:           [width[0], width[1], width[2], width[3]]
414:         else
415:           raise ArgumentError, ":border_width must be a string " +
416:             "or an array [v,h] or [t,r,b,l]"
417:         end
418:       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 217
217:       def content_height
218:         if @height # manually set
219:           return @height - padding_top - padding_bottom
220:         end
221:         
222:         natural_content_height
223:       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 191
191:       def content_width
192:         if @width # manually set
193:           return @width - padding_left - padding_right
194:         end
195: 
196:         natural_content_width
197:       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.

     # File lib/prawn/table/cell.rb, line 236
236:       def draw(pt=[x, y])
237:         set_width_constraints
238: 
239:         draw_background(pt)
240:         draw_borders(pt)
241:         @pdf.bounding_box([pt[0] + padding_left, pt[1] - padding_top], 
242:                           :width  => content_width + FPTolerance,
243:                           :height => content_height + FPTolerance) do
244:           draw_content
245:         end
246:       end

height() click to toggle source

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

     # File lib/prawn/table/cell.rb, line 209
209:       def height
210:         # We can't ||= here because the FP error accumulates on the round-trip
211:         # from #content_height.
212:         @height || (content_height + padding_top + padding_bottom)
213:       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 65
65:       def max_width
66:         set_width_constraints
67:         @max_width
68:       end

min_width() click to toggle source

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

    # File lib/prawn/table/cell.rb, line 58
58:       def min_width
59:         set_width_constraints
60:         @min_width
61:       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 228
228:       def natural_content_height
229:         raise NotImplementedError, 
230:           "subclasses must implement natural_content_height"
231:       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 202
202:       def natural_content_width
203:         raise NotImplementedError, 
204:           "subclasses must implement natural_content_width"
205:       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 279
279:       def padding=(pad)
280:         @padding = case
281:         when pad.nil?
282:           [0, 0, 0, 0]
283:         when Numeric === pad # all padding
284:           [pad, pad, pad, pad]
285:         when pad.length == 2 # vert, horiz
286:           [pad[0], pad[1], pad[0], pad[1]]
287:         when pad.length == 3 # top, horiz, bottom
288:           [pad[0], pad[1], pad[2], pad[1]]
289:         when pad.length == 4 # top, right, bottom, left
290:           [pad[0], pad[1], pad[2], pad[3]]
291:         else
292:           raise ArgumentError, ":padding must be a number or an array [v,h] " +
293:             "or [t,r,b,l]"
294:         end
295:       end

padding_bottom() click to toggle source

     # File lib/prawn/table/cell.rb, line 313
313:       def padding_bottom
314:         @padding[2]
315:       end

padding_bottom=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 317
317:       def padding_bottom=(val)
318:         @padding[2] = val
319:       end

padding_left() click to toggle source

     # File lib/prawn/table/cell.rb, line 321
321:       def padding_left
322:         @padding[3]
323:       end

padding_left=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 325
325:       def padding_left=(val)
326:         @padding[3] = val
327:       end

padding_right() click to toggle source

     # File lib/prawn/table/cell.rb, line 305
305:       def padding_right
306:         @padding[1]
307:       end

padding_right=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 309
309:       def padding_right=(val)
310:         @padding[1] = val
311:       end

padding_top() click to toggle source

     # File lib/prawn/table/cell.rb, line 297
297:       def padding_top
298:         @padding[0]
299:       end

padding_top=(val) click to toggle source

     # File lib/prawn/table/cell.rb, line 301
301:       def padding_top=(val)
302:         @padding[0] = val
303:       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 167
167:       def style(options={}, &block)
168:         options.each { |k, v| send("#{k}=", v) }
169: 
170:         # The block form supports running a single block for multiple cells, as
171:         # in Cells#style.
172:         block.call(self) if block
173:       end

width() click to toggle source

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

     # File lib/prawn/table/cell.rb, line 177
177:       def width
178:         # We can't ||= here because the FP error accumulates on the round-trip
179:         # from #content_width.
180:         @width || (content_width + padding_left + padding_right)
181:       end

width=(w) click to toggle source

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

     # File lib/prawn/table/cell.rb, line 185
185:       def width=(w)
186:         @width = @min_width = @max_width = w
187:       end

x() click to toggle source

x-position of the cell within the parent bounds.

     # File lib/prawn/table/cell.rb, line 250
250:       def x
251:         @point[0]
252:       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 256
256:       def x=(val)
257:         @point[0] = val
258:       end

y() click to toggle source

y-position of the cell within the parent bounds.

     # File lib/prawn/table/cell.rb, line 262
262:       def y
263:         @point[1]
264:       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 268
268:       def y=(val)
269:         @point[1] = val
270:       end

Protected Instance Methods

draw_background(pt) click to toggle source

Draws the cell’s background color.

     # File lib/prawn/table/cell.rb, line 465
465:       def draw_background(pt)
466:         if @background_color
467:           @pdf.mask(:fill_color) do
468:             @pdf.fill_color @background_color
469:             @pdf.fill_rectangle pt, width, height
470:           end
471:         end
472:       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 479
479:       def draw_borders(pt)
480:         x, y = pt
481: 
482:         @pdf.mask(:line_width, :stroke_color) do
483:           @borders.each do |border|
484:             idx = {:top => 0, :right => 1, :bottom => 2, :left => 3}[border]
485:             border_color = @border_colors[idx]
486:             border_width = @border_widths[idx]
487: 
488:             next if border_width <= 0
489: 
490:             # Left and right borders are drawn one-half border beyond the center
491:             # of the corner, so that the corners end up square.
492:             from, to = case border
493:                        when :top
494:                          [[x, y], [x+width, y]]
495:                        when :bottom
496:                          [[x, y-height], [x+width, y-height]]
497:                        when :left
498:                          [[x, y + (border_top_width / 2.0)],
499:                           [x, y - height - (border_bottom_width / 2.0)]]
500:                        when :right
501:                          [[x+width, y + (border_top_width / 2.0)],
502:                           [x+width, y - height - (border_bottom_width / 2.0)]]
503:                        end
504: 
505:             @pdf.line_width   = border_width
506:             @pdf.stroke_color = border_color
507:             @pdf.stroke_line(from, to)
508:           end
509:         end
510:       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 515
515:       def draw_content
516:         raise NotImplementedError, "subclasses must implement draw_content"
517:       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 458
458:       def set_width_constraints
459:         @min_width ||= padding_left + padding_right
460:         @max_width ||= @pdf.bounds.width
461:       end

Home Classes Methods

In Files

Parent

Namespace

Methods