class HexaPDF::Layout::TableBox

A TableBox allows placing boxes in a table.

A table box instance can be fit into a rectangular area. The widths of the columns is determined by the column_widths definition. This means that there is no auto-sizing supported.

If some rows don’t fit into the provided area, the table is split. The style of the original table is also applied to the split box.

Table Cell¶ ↑

Each table cell is a Box instance and can have an associated style, e.g. for creating borders around the cell contents. It is also possible to create cells that span more than one row or column. By default a cell has a solid, black, 1pt border and a padding of 5pt on all sides.

It is important to note that the drawing of cell borders (just the drawing, size calculations are done as usual) are handled differently from standard box borders. While standard box borders are drawn inside the box, cell borders are drawn on the bounds of the box. This means that, visually, the borders of adjoining cells overlap, with the borders of cells to the right and bottom being on top.

To make sure that the cell borders are not outside of the table’s bounds, the left and top border widths of the top-left cell and the right and bottom border widths of the bottom-right cell are taken into account when calculating the available space.

Examples¶ ↑

Let’s start with a basic table:

cells = [[layout.text('A'), layout.text('B')],
         [layout.text('C'), layout.text('D')]]
composer.table(cells)

The HexaPDF::Document::Layout#table_box method accepts the cells as positional argument instead of as keyword argument but all other arguments of ::new work the same.

While the table box itself only allows box instances as cell contents, the layout helper method also allows text which it transforms to text boxes. So this is the same as the above:

composer.table([['A', 'B'], ['C', 'D']])

The style of the cells can be customized, e.g. to avoid drawing borders:

cells = [[layout.text('A'), layout.text('B')],
         [layout.text('C'), layout.text('D')]]
composer.table(cells, cell_style: {border: {width: 0}})

If the table doesn’t fit completely, it is automatically split (in this case, the last row gets moved to the second column):

cells = [[layout.text('A'), layout.text('B')],
         [layout.text('C'), layout.text('D')],
         [layout.text('E'), layout.text('F')]]
composer.column(height: 50) {|col| col.table(cells) }

It is also possible to use row and column spans:

cells = [[{content: layout.text('A'), col_span: 2}, {content: layout.text('B'), row_span: 2}],
         [{content: layout.text('C'), col_span: 2, row_span: 2}],
         [layout.text('D')]]
composer.table(cells)

Each table can have header rows and footer rows which are shown for all split parts:

header = lambda {|tb| [[{content: layout.text('Header', text_align: :center), col_span: 2}]] }
footer = lambda {|tb| [[layout.text('left'), layout.text('right', text_align: :right)]] }
cells = [[layout.text('A'), layout.text('B')],
         [layout.text('C'), layout.text('D')],
         [layout.text('E'), layout.text('F')]]
composer.column(height: 90) {|col| col.table(cells, header: header, footer: footer) }

The cells can be styled using a callable object for more complex styling:

cells = [[layout.text('A'), layout.text('B')],
         [layout.text('C'), layout.text('D')]]
block = lambda do |cell|
  cell.style.background_color =
    (cell.row == 0 && cell.column == 0 ? 'ffffaa' : 'ffffee')
end
composer.table(cells, cell_style: block)