class HexaPDF::Layout::TableBox::Cells


Represents the cells of a TableBox.

This class is a wrapper around an array of arrays and provides some utility methods for managing and styling the cells.

Table data transformation into correct form

One of the main purposes of this class is to transform the cell data provided on initialization into the representation a TableBox instance can work with.

The data argument for ::new is an array of arrays representing the rows of the table. Each row array may contain one of the following items:

  • A single Box instance defining the content of the cell.

  • An array of Box instances defining the content of the cell.

  • A hash which defines the content of the cell as well as, optionally, additional information through the following keys:


    The content for the cell. This may be a single Box or an array of Box instances.


    An integer specifying the number of rows this cell should span.


    An integer specifying the number of columsn this cell should span.


    A hash of properties (see Box#properties) to be set on the cell itself.

    All other key-value pairs are taken to be cell styling information (like :background_color) and assigned to the cell style.

Additionally, the first item in the data argument is treated specially if it is not an array:

  • If it is a hash, it is assumed to be style properties to be set on all created cell instances.

  • If it is a callable object, it needs to accept a cell as argument and is called for all created cell instances.

Any properties or styling information retrieved from the respective item in data takes precedence over the above globally specified information.

Here is an example input data array:

data = [[box1, {col_span: 2, content: box2}, box3],
        [box4, box5, {col_span: 2, row_span: 2, content: [box6.1, box6.2]}],
        [box7, box8]]

And this is what the table will look like:

| box1 | box2         | box 3 |
| box4 | box5 | box6.1 box6.2 |
| box7 | box8 |               |

Public Class Methods

new(data, cell_style: nil)

Creates a new Cells instance with the given data which cannot be changed afterwards.

The optional cell_style argument can either be a hash of style properties to be assigned to every cell or a block accepting a cell for more control over e.g. style assignment. If the data has such a cell style as its first item, the cell_style argument is not used.

See the class documentation for details on the data argument.

Public Instance Methods

[](row, column)

Returns the cell (a Cell instance) in the given row and column.

Note that the same cell instance may be returned for different (row, column) arguments if the cell spans more than one row and/or column.

draw_rows(start_row, end_row, canvas, x, y)

Draws the rows from start_row to end_row on the given canvas, with the top-left corner of the resulting table being at (x, y).


Iterates over each row.

fit_rows(start_row, available_height, column_info, frame)

Fits all rows starting from start_row into an area with the given available_height, using the column information in column_info. Returns the used height as well as the row index of the last row that fit (which may be -1 if no row fits).

The column_info argument needs to be an array of arrays of the form [x_pos, width] containing the horizontal positions and widths of each column.

The frame argument is further handed down to the Cell instances for fitting.

The fitting of a cell is done through the Cell#fit method which stores the result in the cell itself. Furthermore, Cell#left and Cell#top are also assigned correctly.


Returns the number of columns.


Returns the number of rows.

style(**properties, &block)

Applies the given style properties to all cells and optionally yields all cells for more complex customization.