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/image.rb,
lib/prawn/table/cell/in_table.rb,
lib/prawn/table/cell/subtable.rb,
lib/prawn/table/cell/span_dummy.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

Image, SpanDummy, Subtable, Text

Defined Under Namespace

Modules: InTable Classes: Image, SpanDummy, 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.



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/prawn/table/cell.rb', line 200

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
  @colspan = 1
  @rowspan = 1
  @dummy_cells = []

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

  @initializer_run = true
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.



136
137
138
 
# File 'lib/prawn/table/cell.rb', line 136

def background_color
  @background_color
end

#border_colors ⇒ Object (readonly)

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



124
125
126
 
# File 'lib/prawn/table/cell.rb', line 124

def border_colors
  @border_colors
end

#border_widths ⇒ Object (readonly)

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



120
121
122
 
# File 'lib/prawn/table/cell.rb', line 120

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



116
117
118
 
# File 'lib/prawn/table/cell.rb', line 116

def borders
  @borders
end

#colspan ⇒ Object

Number of columns this cell spans. Defaults to 1.



140
141
142
 
# File 'lib/prawn/table/cell.rb', line 140

def colspan
  @colspan
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.



130
131
132
 
# File 'lib/prawn/table/cell.rb', line 130

def content
  @content
end

#dummy_cells ⇒ Object (readonly)

Array of SpanDummy cells (if any) that represent the other cells in this span group. They know their own width / height, but do not draw anything.



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

def dummy_cells
  @dummy_cells
end

#height ⇒ Object

Returns the cell’s height in points, inclusive of padding. If the cell is the master cell of a rowspan, returns the width of the entire span group.



305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/prawn/table/cell.rb', line 305

def height
  return height_ignoring_span if @colspan == 1 && @rowspan == 1

  # We're in a span group; get the maximum height per row (including the
  # master cell) and sum each row.
  row_heights = Hash.new(0)
  dummy_cells.each do |cell|
    row_heights[cell.row] = [row_heights[cell.row], cell.height].max
  end
  row_heights[row] = [row_heights[row], height_ignoring_span].max
  row_heights.values.inject(0, &:+)
end

#padding ⇒ Object

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



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

def padding
  @padding
end

#rowspan ⇒ Object

Number of rows this cell spans. Defaults to 1.



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

def rowspan
  @rowspan
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.



400
401
402
403
404
405
406
407
408
409
410
 
# File 'lib/prawn/table/cell.rb', line 400

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.



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/prawn/table/cell.rb', line 156

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)
    if img = content[:image]
      return Cell::Image.new(pdf, at, content)
    end
    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
    raise Errors::UnrecognizedTableContent
  end
end

Instance Method Details

#avg_spanned_min_width ⇒ Object

Min-width of the span divided by the number of columns.



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

def avg_spanned_min_width
  min_width.to_f / colspan
end

#border_bottom_color ⇒ Object 



555
556
557
 
# File 'lib/prawn/table/cell.rb', line 555

def border_bottom_color
  @border_colors[2]
end

#border_bottom_color=(val) ⇒ Object 



559
560
561
 
# File 'lib/prawn/table/cell.rb', line 559

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

#border_bottom_width ⇒ Object 



613
614
615
 
# File 'lib/prawn/table/cell.rb', line 613

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

#border_bottom_width=(val) ⇒ Object 



617
618
619
 
# File 'lib/prawn/table/cell.rb', line 617

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]



512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
 
# File 'lib/prawn/table/cell.rb', line 512

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 



563
564
565
 
# File 'lib/prawn/table/cell.rb', line 563

def border_left_color
  @border_colors[3]
end

#border_left_color=(val) ⇒ Object 



567
568
569
 
# File 'lib/prawn/table/cell.rb', line 567

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

#border_left_width ⇒ Object 



621
622
623
 
# File 'lib/prawn/table/cell.rb', line 621

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

#border_left_width=(val) ⇒ Object 



625
626
627
 
# File 'lib/prawn/table/cell.rb', line 625

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

#border_right_color ⇒ Object 



547
548
549
 
# File 'lib/prawn/table/cell.rb', line 547

def border_right_color
  @border_colors[1]
end

#border_right_color=(val) ⇒ Object 



551
552
553
 
# File 'lib/prawn/table/cell.rb', line 551

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

#border_right_width ⇒ Object 



605
606
607
 
# File 'lib/prawn/table/cell.rb', line 605

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

#border_right_width=(val) ⇒ Object 



609
610
611
 
# File 'lib/prawn/table/cell.rb', line 609

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

#border_top_color ⇒ Object 



531
532
533
 
# File 'lib/prawn/table/cell.rb', line 531

def border_top_color
  @border_colors[0]
end

#border_top_color=(val) ⇒ Object 



535
536
537
 
# File 'lib/prawn/table/cell.rb', line 535

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

#border_top_width ⇒ Object 



597
598
599
 
# File 'lib/prawn/table/cell.rb', line 597

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

#border_top_width=(val) ⇒ Object 



601
602
603
 
# File 'lib/prawn/table/cell.rb', line 601

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]



578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
 
# File 'lib/prawn/table/cell.rb', line 578

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.



320
321
322
323
324
325
326
 
# File 'lib/prawn/table/cell.rb', line 320

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.



270
271
272
273
274
275
276
 
# File 'lib/prawn/table/cell.rb', line 270

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.



392
393
394
 
# File 'lib/prawn/table/cell.rb', line 392

def draw(pt=[x, y])
  Prawn::Table::Cell.draw_cells([[self, pt]])
end

#draw_background(pt) ⇒ Object

Draws the cell’s background color.



639
640
641
642
643
644
645
646
 
# File 'lib/prawn/table/cell.rb', line 639

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.



653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
 
# File 'lib/prawn/table/cell.rb', line 653

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.



414
415
416
417
418
419
420
421
422
 
# File 'lib/prawn/table/cell.rb', line 414

def draw_bounded_content(pt)
  @pdf.float do
    @pdf.bounding_box([pt[0] + padding_left, pt[1] - padding_top], 
                      :width  => spanned_content_width + FPTolerance,
                      :height => spanned_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) 


689
690
691
 
# File 'lib/prawn/table/cell.rb', line 689

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

#height_ignoring_span ⇒ Object

Returns the cell’s height in points, inclusive of padding, in its first row only.



295
296
297
298
299
 
# File 'lib/prawn/table/cell.rb', line 295

def height_ignoring_span
  # 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

Maximum width of the entire span group this cell controls.



95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/prawn/table/cell.rb', line 95

def max_width
  return max_width_ignoring_span if @colspan == 1
  
  # Sum the smallest max-width from each column in the group, including
  # myself.
  max_widths = Hash.new(0)
  dummy_cells.each do |cell|
    max_widths[cell.column] =
      [max_widths[cell.column], cell.max_width].min
  end
  max_widths[column] = [max_widths[column], max_width_ignoring_span].min
  max_widths.values.inject(0, &:+)
end

#max_width_ignoring_span ⇒ Object

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



88
89
90
91
 
# File 'lib/prawn/table/cell.rb', line 88

def max_width_ignoring_span
  set_width_constraints
  @max_width
end

#min_width ⇒ Object

Minimum width of the entire span group this cell controls.



66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/prawn/table/cell.rb', line 66

def min_width
  return min_width_ignoring_span if @colspan == 1

  # Sum up the largest min-width from each column, including myself.
  min_widths = Hash.new(0)
  dummy_cells.each do |cell|
    min_widths[cell.column] = 
      [min_widths[cell.column], cell.min_width].max
  end
  min_widths[column] = [min_widths[column], min_width_ignoring_span].max
  min_widths.values.inject(0, &:+)
end

#min_width_ignoring_span ⇒ Object

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



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

def min_width_ignoring_span
  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) 


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

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) 


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

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

#padding_bottom ⇒ Object 



489
490
491
 
# File 'lib/prawn/table/cell.rb', line 489

def padding_bottom
  @padding[2]
end

#padding_bottom=(val) ⇒ Object 



493
494
495
 
# File 'lib/prawn/table/cell.rb', line 493

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

#padding_left ⇒ Object 



497
498
499
 
# File 'lib/prawn/table/cell.rb', line 497

def padding_left
  @padding[3]
end

#padding_left=(val) ⇒ Object 



501
502
503
 
# File 'lib/prawn/table/cell.rb', line 501

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

#padding_right ⇒ Object 



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

def padding_right
  @padding[1]
end

#padding_right=(val) ⇒ Object 



485
486
487
 
# File 'lib/prawn/table/cell.rb', line 485

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

#padding_top ⇒ Object 



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

def padding_top
  @padding[0]
end

#padding_top=(val) ⇒ Object 



477
478
479
 
# File 'lib/prawn/table/cell.rb', line 477

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.



632
633
634
635
 
# File 'lib/prawn/table/cell.rb', line 632

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

#spanned_content_height ⇒ Object

Height of the entire span group.



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

def spanned_content_height
  height - padding_top - padding_bottom
end

#spanned_content_width ⇒ Object

Width of the entire span group.



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

def spanned_content_width
  width - padding_left - padding_right
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



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

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. If the cell is the master cell of a colspan, returns the width of the entire span group.



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

def width
  return width_ignoring_span if @colspan == 1 && @rowspan == 1

  # We're in a span group; get the maximum width per column (including
  # the master cell) and sum each column.
  column_widths = Hash.new(0)
  dummy_cells.each do |cell|
    column_widths[cell.column] = 
      [column_widths[cell.column], cell.width].max
  end
  column_widths[column] = [column_widths[column], width_ignoring_span].max
  column_widths.values.inject(0, &:+)
end

#width=(w) ⇒ Object

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



264
265
266
 
# File 'lib/prawn/table/cell.rb', line 264

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

#width_ignoring_span ⇒ Object

Returns the width of the cell in its first column alone, ignoring any colspans.



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

def width_ignoring_span
  # We can't ||= here because the FP error accumulates on the round-trip
  # from #content_width.
  @width || (content_width + padding_left + padding_right)
end

#x ⇒ Object

x-position of the cell within the parent bounds.



426
427
428
 
# File 'lib/prawn/table/cell.rb', line 426

def x
  @point[0]
end

#x=(val) ⇒ Object

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



432
433
434
 
# File 'lib/prawn/table/cell.rb', line 432

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

#y ⇒ Object

y-position of the cell within the parent bounds.



438
439
440
 
# File 'lib/prawn/table/cell.rb', line 438

def y
  @point[1]
end

#y=(val) ⇒ Object

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



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

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