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.



145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/prawn/table/cell.rb', line 145

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

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.



97
98
99
 
# File 'lib/prawn/table/cell.rb', line 97

def background_color
  @background_color
end

#border_colors ⇒ Object (readonly)

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



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

def border_colors
  @border_colors
end

#border_widths ⇒ Object (readonly)

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



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

def border_widths
  @border_widths
end

#borders ⇒ Object

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



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

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.



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

def content
  @content
end

#height ⇒ Object

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



209
210
211
212
213
 
# File 'lib/prawn/table/cell.rb', line 209

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

#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

.draw_cells(cells) ⇒ Object

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



248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/prawn/table/cell.rb', line 248

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 = {}) ⇒ 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.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/prawn/table/cell.rb', line 103

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

Instance Method Details

#border_bottom_color ⇒ Object 



403
404
405
 
# File 'lib/prawn/table/cell.rb', line 403

def border_bottom_color
  @border_colors[2]
end

#border_bottom_color=(val) ⇒ Object 



407
408
409
 
# File 'lib/prawn/table/cell.rb', line 407

def border_bottom_color=(val)
  @border_colors[2] = val
end

#border_bottom_width ⇒ Object 



461
462
463
 
# File 'lib/prawn/table/cell.rb', line 461

def border_bottom_width
  @borders.include?(:bottom) ? @border_widths[2] : 0
end

#border_bottom_width=(val) ⇒ Object 



465
466
467
 
# File 'lib/prawn/table/cell.rb', line 465

def border_bottom_width=(val)
  @border_widths[2] = val
end

#border_color=(color) ⇒ Object Also known as: border_colors=

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]



360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
 
# File 'lib/prawn/table/cell.rb', line 360

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

#border_left_color ⇒ Object 



411
412
413
 
# File 'lib/prawn/table/cell.rb', line 411

def border_left_color
  @border_colors[3]
end

#border_left_color=(val) ⇒ Object 



415
416
417
 
# File 'lib/prawn/table/cell.rb', line 415

def border_left_color=(val)
  @border_colors[3] = val
end

#border_left_width ⇒ Object 



469
470
471
 
# File 'lib/prawn/table/cell.rb', line 469

def border_left_width
  @borders.include?(:left) ? @border_widths[3] : 0
end

#border_left_width=(val) ⇒ Object 



473
474
475
 
# File 'lib/prawn/table/cell.rb', line 473

def border_left_width=(val)
  @border_widths[3] = val
end

#border_right_color ⇒ Object 



395
396
397
 
# File 'lib/prawn/table/cell.rb', line 395

def border_right_color
  @border_colors[1]
end

#border_right_color=(val) ⇒ Object 



399
400
401
 
# File 'lib/prawn/table/cell.rb', line 399

def border_right_color=(val)
  @border_colors[1] = val
end

#border_right_width ⇒ Object 



453
454
455
 
# File 'lib/prawn/table/cell.rb', line 453

def border_right_width
  @borders.include?(:right) ? @border_widths[1] : 0
end

#border_right_width=(val) ⇒ Object 



457
458
459
 
# File 'lib/prawn/table/cell.rb', line 457

def border_right_width=(val)
  @border_widths[1] = val
end

#border_top_color ⇒ Object 



379
380
381
 
# File 'lib/prawn/table/cell.rb', line 379

def border_top_color
  @border_colors[0]
end

#border_top_color=(val) ⇒ Object 



383
384
385
 
# File 'lib/prawn/table/cell.rb', line 383

def border_top_color=(val)
  @border_colors[0] = val
end

#border_top_width ⇒ Object 



445
446
447
 
# File 'lib/prawn/table/cell.rb', line 445

def border_top_width
  @borders.include?(:top) ? @border_widths[0] : 0
end

#border_top_width=(val) ⇒ Object 



449
450
451
 
# File 'lib/prawn/table/cell.rb', line 449

def border_top_width=(val)
  @border_widths[0] = val
end

#border_width=(width) ⇒ Object Also known as: border_widths=

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]



426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
 
# File 'lib/prawn/table/cell.rb', line 426

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

#content_height ⇒ Object

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



217
218
219
220
221
222
223
 
# File 'lib/prawn/table/cell.rb', line 217

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.



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

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.

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.



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

def draw(pt=[x, y])
  self.class.draw_cells([[self, pt]])
end

#draw_background(pt) ⇒ Object

Draws the cell’s background color.



487
488
489
490
491
492
493
494
 
# File 'lib/prawn/table/cell.rb', line 487

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

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.



501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
 
# File 'lib/prawn/table/cell.rb', line 501

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

Draws the cell’s content at the point provided.



262
263
264
265
266
267
268
269
270
 
# File 'lib/prawn/table/cell.rb', line 262

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

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

Raises:

  • (NotImplementedError) 


537
538
539
 
# File 'lib/prawn/table/cell.rb', line 537

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

#max_width ⇒ Object

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



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

def max_width
  set_width_constraints
  @max_width
end

#min_width ⇒ Object

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



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

def min_width
  set_width_constraints
  @min_width
end

#natural_content_height ⇒ Object

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

Raises:

  • (NotImplementedError) 


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

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) 


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

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

#padding_bottom ⇒ Object 



337
338
339
 
# File 'lib/prawn/table/cell.rb', line 337

def padding_bottom
  @padding[2]
end

#padding_bottom=(val) ⇒ Object 



341
342
343
 
# File 'lib/prawn/table/cell.rb', line 341

def padding_bottom=(val)
  @padding[2] = val
end

#padding_left ⇒ Object 



345
346
347
 
# File 'lib/prawn/table/cell.rb', line 345

def padding_left
  @padding[3]
end

#padding_left=(val) ⇒ Object 



349
350
351
 
# File 'lib/prawn/table/cell.rb', line 349

def padding_left=(val)
  @padding[3] = val
end

#padding_right ⇒ Object 



329
330
331
 
# File 'lib/prawn/table/cell.rb', line 329

def padding_right
  @padding[1]
end

#padding_right=(val) ⇒ Object 



333
334
335
 
# File 'lib/prawn/table/cell.rb', line 333

def padding_right=(val)
  @padding[1] = val
end

#padding_top ⇒ Object 



321
322
323
 
# File 'lib/prawn/table/cell.rb', line 321

def padding_top
  @padding[0]
end

#padding_top=(val) ⇒ Object 



325
326
327
 
# File 'lib/prawn/table/cell.rb', line 325

def padding_top=(val)
  @padding[0] = val
end

#set_width_constraints ⇒ Object

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



480
481
482
483
 
# File 'lib/prawn/table/cell.rb', line 480

def set_width_constraints
  @min_width ||= padding_left + padding_right
  @max_width ||= @pdf.bounds.width
end

#style(options = {}, &block) ⇒ Object

Supports setting multiple properties at once.

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

is the same as:

cell.padding = 0
cell.border_width = 2



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

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

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



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

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.



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

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

#x ⇒ Object

x-position of the cell within the parent bounds.



274
275
276
 
# File 'lib/prawn/table/cell.rb', line 274

def x
  @point[0]
end

#x=(val) ⇒ Object

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



280
281
282
 
# File 'lib/prawn/table/cell.rb', line 280

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

#y ⇒ Object

y-position of the cell within the parent bounds.



286
287
288
 
# File 'lib/prawn/table/cell.rb', line 286

def y
  @point[1]
end

#y=(val) ⇒ Object

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



292
293
294
 
# File 'lib/prawn/table/cell.rb', line 292

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