R6 class that manages cells in a table.

Source: R/TableCells.R

The `TableCells` manages the `TableCell` objects that comprise a `BasicTable` object.

Format

R6Class object.

Active bindings

rowCount

The number of rows in the table.

columnCount

The number of columns in the table.

rows

The rows of cells in the table - represented as a list, each element of which is a list of `TableCell` objects.

all

A list of the cells in the table. Each element in this list is a `TableCell` object.

Methods

Public methods

Method new()

Create a new `TableCells` object.

Usage

TableCells$new(parentTable = NULL)

Arguments

parentTable

Owning table.

Returns

No return value.

Method reset()

Clear all cells from the table.

Usage

TableCells$reset()

Returns

No return value.

Method getCell()

Retrieve a specific `TableCell` object at the specified location in the table.

Usage

TableCells$getCell(r = NULL, c = NULL)

Arguments

r

The row number of the cell to retrieve.

c

The column number of the cell to retrieve.

Returns

A `TableCell` object.

Method getValue()

Retrieve the value of a specific `TableCell` object at the specified location in the table.

Usage

TableCells$getValue(r = NULL, c = NULL, formattedValue = FALSE)

Arguments

r

The row number of the cell value to retrieve.

c

The column number of the cell value to retrieve.

formattedValue

`TRUE` to retrieve the formatted (character) cell value, `FALSE` (default) to retrieve the raw cell value (typically numeric).

Returns

The value of the cell.

Method getRowValues()

Get a vector or list of the values in a row for the entire row or a subset of columns.

Usage

TableCells$getRowValues(
  rowNumber = NULL,
  columnNumbers = NULL,
  formattedValue = FALSE,
  asList = FALSE,
  rebase = TRUE
)

Arguments

rowNumber

The row number to retrieve the values for (a single row number).

columnNumbers

The column numbers of the cell value to retrieve (can be a vector of column numbers).

formattedValue

`TRUE` to retrieve the formatted (character) cell value, `FALSE` (default) to retrieve the raw cell value (typically numeric).

asList

`TRUE` to retrieve the values as a list, `FALSE` (default) to retrieve the values as a vector.

rebase

`TRUE` to rebase the list/vector so that the first element is at index 1, `FALSE` to retain the original column numbers.

Returns

A vector or list of the cell values.

Method getColumnValues()

Get a vector or list of the values in a column for the entire column or a subset of rows.

Usage

TableCells$getColumnValues(
  columnNumber = NULL,
  rowNumbers = NULL,
  formattedValue = FALSE,
  asList = FALSE,
  rebase = TRUE
)

Arguments

columnNumber

The column number to retrieve the values for (a single column number).

rowNumbers

The row numbers of the cell value to retrieve (can be a vector of row numbers).

formattedValue

`TRUE` to retrieve the formatted (character) cell value, `FALSE` (default) to retrieve the raw cell value (typically numeric).

asList

`TRUE` to retrieve the values as a list, `FALSE` (default) to retrieve the values as a vector.

rebase

`TRUE` to rebase the list/vector so that the first element is at index 1, `FALSE` to retain the original row numbers.

Returns

A vector or list of the cell values.

Method setCell()

Create a cell in the table and set the details of the cell.

Usage

TableCells$setCell(
  r = NULL,
  c = NULL,
  cellType = "cell",
  rawValue = NULL,
  formattedValue = NULL,
  visible = TRUE,
  baseStyleName = NULL,
  styleDeclarations = NULL,
  rowSpan = NULL,
  colSpan = NULL
)

Arguments

r

The row number of the cell.

c

The column number of the cell.

cellType

The type of the cell - must be one of the following values: root, rowHeader, columnHeader, cell, total.

rawValue

The raw value of the cell - typically a numeric value.

formattedValue

The formatted value of the cell - typically a character value.

visible

`TRUE` (default) to specify that the cell is visible, `FALSE` to specify that the cell will be invisible.

baseStyleName

The name of a style from the table theme that will be used to style this cell.

styleDeclarations

A list of CSS style definitions.

rowSpan

A number greater than 1 to indicate that this cell is merged with cells below. `NULL` (default) or 1 means the cell is not merged across rows.

colSpan

A number greater than 1 to indicate that this cell is merged with cells to the right. `NULL` (default) or 1 means the cell is not merged across columns.

Returns

A vector or list of the cell values.

Method setBlankCell()

Create an empty cell in the table and set the details of the cell.

Usage

TableCells$setBlankCell(
  r = NULL,
  c = NULL,
  cellType = "cell",
  visible = TRUE,
  baseStyleName = NULL,
  styleDeclarations = NULL,
  rowSpan = NULL,
  colSpan = NULL,
  asNBSP = FALSE
)

Arguments

r

The row number of the cell.

c

The column number of the cell.

cellType

The type of the cell - must be one of the following values: root, rowHeader, columnHeader, cell, total.

visible

`TRUE` (default) to specify that the cell is visible, `FALSE` to specify that the cell will be invisible.

baseStyleName

The name of a style from the table theme that will be used to style this cell.

styleDeclarations

A list of CSS style definitions.

rowSpan

A number greater than 1 to indicate that this cell is merged with cells below. `NULL` (default) or 1 means the cell is not merged across rows.

colSpan

A number greater than 1 to indicate that this cell is merged with cells to the right. `NULL` (default) or 1 means the cell is not merged across columns.

asNBSP

`TRUE` if the cell should be rendered as   in HTML, `FALSE` (default) otherwise.

Returns

A vector or list of the cell values.

Method deleteCell()

Replace the `TableCell` object at the specified location in the table with a blank cell.

Usage

TableCells$deleteCell(r = NULL, c = NULL)

Arguments

r

The row number of the cell value to delete

c

The column number of the cell value to delete

Returns

The `TableCell` object that is the new blank cell.

Method setValue()

Update the value of a cell in the table.

Usage

TableCells$setValue(r = NULL, c = NULL, rawValue = NULL, formattedValue = NULL)

Arguments

r

The row number of the cell.

c

The column number of the cell.

rawValue

The raw value of the cell - typically a numeric value.

formattedValue

The formatted value of the cell - typically a character value.

Returns

No return value.

Method setRow()

Create multiple cells in one row of a table.

Usage

TableCells$setRow(
  rowNumber = NULL,
  startAtColumnNumber = 1,
  cellTypes = "cell",
  rawValues = NULL,
  formattedValues = NULL,
  formats = NULL,
  visiblity = TRUE,
  baseStyleNames = NULL,
  fmtFuncArgs = NULL
)

Arguments

rowNumber

The row number where the cells will be created.

startAtColumnNumber

The column number to start generating cells at. Default value 1.

cellTypes

The types of the cells - either a single value or a vector of the same length as rawValues. Each cellType must be one of the following values: root, rowHeader, columnHeader, cell, total.

rawValues

A vector or list of values. A cell will be generated in the table for each element in the vector/list.

formattedValues

A vector or list of formatted values. Must be either `NULL`, a single value or a vector/list of the same length as rawValues.

formats

A vector or list of formats. Must be either `NULL`, a single value or a vector/list of the same length as rawValues.

visiblity

A logical vector. Must be either a single logical value or a vector/list of the same length as rawValues.

baseStyleNames

A character vector. Must be either a single style name (from the table theme) or a vector of style names of the same length as rawValues.

fmtFuncArgs

A list that is length 1 or the same length as the number of columns in the row, where each list element specifies a list of arguments to pass to custom R format functions.

Returns

No return value.

Method setColumn()

Create multiple cells in one column of a table.

Usage

TableCells$setColumn(
  columnNumber = NULL,
  startAtRowNumber = 2,
  cellTypes = "cell",
  rawValues = NULL,
  formattedValues = NULL,
  formats = NULL,
  visiblity = TRUE,
  baseStyleNames = NULL,
  fmtFuncArgs = NULL
)

Arguments

columnNumber

The column number where the cells will be created.

startAtRowNumber

The row number to start generating cells at. Default value 2.

cellTypes

The types of the cells - either a single value or a vector of the same length as rawValues. Each cellType must be one of the following values: root, rowHeader, columnHeader, cell, total.

rawValues

A vector or list of values. A cell will be generated in the table for each element in the vector/list.

formattedValues

A vector or list of formatted values. Must be either `NULL`, a single value or a vector of the same length as rawValues.

formats

A vector or list of formats. Must be either `NULL`, a single value or a vector of the same length as rawValues.

visiblity

A logical vector. Must be either a single logical value or a vector of the same length as rawValues.

baseStyleNames

A character vector. Must be either a single style name (from the table theme) or a vector of style names of the same length as rawValues.

fmtFuncArgs

A list that is length 1 or the same length as the number of rows in the column, where each list element specifies a list of arguments to pass to custom R format functions.

Returns

No return value.

Method extendCells()

Enlarge a table to the specified size.

Usage

TableCells$extendCells(rowCount = NULL, columnCount = NULL)

Arguments

rowCount

The number of rows in the enlarged table.

columnCount

The number of columns in the enlarged table.

Returns

No return value.

Method moveCell()

Move a table cell to a different location in the table.

Usage

TableCells$moveCell(r = NULL, c = NULL, cell = NULL)

Arguments

r

The new row number to move the cell to.

c

The new column number to move the cell to.

cell

The `TableCell` object to move.

Returns

No return value.

Method insertRow()

Insert a new row in the table at the specified row number and shift existing cells on/below this row down by one row.

Usage

TableCells$insertRow(
  rowNumber = NULL,
  insertBlankCells = TRUE,
  headerCells = 1,
  totalCells = 0
)

Arguments

rowNumber

The row number where the new row is to be inserted.

insertBlankCells

`TRUE` (default) to insert blank cells in the new row, `FALSE` to create no cells in the new row.

headerCells

The number of header cells to create at the start of the row. Default value 1.

totalCells

The number of total cells to create at the end of the row. Default value 0.

Returns

No return value.

Method deleteRow()

Delete the row in the table at the specified row number and shift existing cells below this row up by one row.

Usage

TableCells$deleteRow(rowNumber = NULL)

Arguments

rowNumber

The row number of the row to be deleted.

Returns

No return value.

Method insertColumn()

Insert a new column in the table at the specified column number and shift existing cells in/to the right of this column across by one row.

Usage

TableCells$insertColumn(
  columnNumber = NULL,
  insertBlankCells = TRUE,
  headerCells = 1,
  totalCells = 0
)

Arguments

columnNumber

The column number where the new column is to be inserted.

insertBlankCells

`TRUE` (default) to insert blank cells in the new column, `FALSE` to create no cells in the new column

headerCells

The number of header cells to create at the top of the column. Default value 1.

totalCells

The number of total cells to create at the bottom of the column. Default value 0.

Returns

No return value.

Method deleteColumn()

Delete the column in the table at the specified column number and shift existing cells to the right of this column to the left by one column.

Usage

TableCells$deleteColumn(columnNumber = NULL)

Arguments

columnNumber

The column number of the column to be deleted.

Returns

No return value.

Method getCells()

Retrieve cells by a combination of row and/or column numbers. See the "Finding and Formatting" vignette for graphical examples.

Usage

TableCells$getCells(
  specifyCellsAsList = TRUE,
  rowNumbers = NULL,
  columnNumbers = NULL,
  cellCoordinates = NULL,
  excludeEmptyCells = FALSE,
  matchMode = "simple"
)

Arguments

specifyCellsAsList

`TRUE`/`FALSE` to specify how cells are retrieved. Default `TRUE`. More information is provided in the details section.

rowNumbers

A vector of row numbers that specify the rows or cells to retrieve.

columnNumbers

A vector of row numbers that specify the columns or cells to retrieve.

cellCoordinates

A list of two-element vectors that specify the coordinates of cells to retrieve. Ignored when `specifyCellsAsList=FALSE`.

excludeEmptyCells

Default `FALSE`. Specify `TRUE` to exclude empty cells.

matchMode

Either "simple" (default) or "combinations"
"simple" specifies that row and column arguments are considered separately (logical OR), e.g. rowNumbers=1 and columnNumbers=2 will match all cells in row 1 and all cells in column 2.
"combinations" specifies that row and column arguments are considered together (logical AND), e.g. rowNumbers=1 and columnNumbers=2 will match only the cell single at location (1, 2).
Arguments `rowNumbers`, `columnNumbers`, `rowGroups` and `columnGroups` are affected by the match mode. All other arguments are not.

Details

When `specifyCellsAsList=TRUE` (the default):
Get one or more rows by specifying the row numbers as a vector as the rowNumbers argument and leaving the columnNumbers argument set to the default value of `NULL`, or
Get one or more columns by specifying the column numbers as a vector as the columnNumbers argument and leaving the rowNumbers argument set to the default value of `NULL`, or
Get one or more individual cells by specifying the cellCoordinates argument as a list of vectors of length 2, where each element in the list is the row and column number of one cell,
e.g. `list(c(1, 2), c(3, 4))` specifies two cells, the first located at row 1, column 2 and the second located at row 3, column 4.
When `specifyCellsAsList=FALSE`:
Get one or more rows by specifying the row numbers as a vector as the rowNumbers argument and leaving the columnNumbers argument set to the default value of `NULL`, or
Get one or more columns by specifying the column numbers as a vector as the columnNumbers argument and leaving the rowNumbers argument set to the default value of `NULL`, or
Get one or more cells by specifying the row and column numbers as vectors for the rowNumbers and columnNumbers arguments, or
a mixture of the above, where for entire rows/columns the element in the other vector is set to `NA`, e.g. to retrieve whole rows, specify the row numbers as the rowNumbers but set the corresponding elements in the columnNumbers vector to `NA`.

Returns

A list of `TableCell` objects.

Method findCells()

Find cells matching specified criteria. See the "Finding and Formatting" vignette for graphical examples.

Usage

TableCells$findCells(
  minValue = NULL,
  maxValue = NULL,
  exactValues = NULL,
  valueRanges = NULL,
  includeNull = TRUE,
  includeNA = TRUE,
  emptyCells = "include",
  rowNumbers = NULL,
  columnNumbers = NULL,
  cellCoordinates = NULL,
  cells = NULL,
  rowColumnMatchMode = "simple"
)

Arguments

minValue

A numerical value specifying a minimum value threshold.

maxValue

A numerical value specifying a maximum value threshold.

exactValues

A vector or list specifying a set of allowed values.

valueRanges

A vector specifying one or more value range expressions which the cell values must match. If multiple value range expressions are specified, then the cell value must match any of one the specified expressions.

includeNull

Specify TRUE to include `NULL` in the matched cells, FALSE to exclude `NULL` values.

includeNA

Specify TRUE to include `NA` in the matched cells, FALSE to exclude `NA` values.

emptyCells

A word that specifies how empty cells are matched - must be one of "include" (default), "exclude" or "only".

rowNumbers

A vector of row numbers that specify the rows or cells to constrain the search.

columnNumbers

A vector of column numbers that specify the columns or cells to constrain the search.

cellCoordinates

A list of two-element vectors that specify the coordinates of cells to constrain the search.

cells

A `TableCell` object or a list of `TableCell` objects to constrain the scope of the search.

rowColumnMatchMode

Either "simple" (default) or "combinations":
"simple" specifies that row and column arguments are considered separately (logical OR), e.g. rowNumbers=1 and columnNumbers=2 will match all cells in row 1 and all cells in column 2.
"combinations" specifies that row and column arguments are considered together (logical AND), e.g. rowNumbers=1 and columnNumbers=2 will match only the cell single at location (1, 2).
Arguments `rowNumbers`, `columnNumbers`, `rowGroups` and `columnGroups` are affected by the match mode. All other arguments are not.

Returns

A list of `TableCell` objects.

Method getColumnWidths()

Retrieve the width of the longest value (in characters) in each column.

Usage

TableCells$getColumnWidths()

Returns

The width of the column in characters.

Method asList()

Return the contents of this object as a list for debugging.

Usage

TableCells$asList()

Returns

A list of various object properties.

Method asJSON()

Return the contents of this object as JSON for debugging.

Usage

TableCells$asJSON()

Returns

A JSON representation of various object properties.

Method clone()

The objects of this class are cloneable with this method.

Usage

TableCells$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# This class should only be created by the table.
# It is not intended to be created outside of the table.
library(basictabler)
tbl <- qtbl(data.frame(a=1:2, b=3:4))
cells <- tbl$cells
cells$setCell(r=4, c=1, cellType="cell", rawValue=5)
cells$setCell(r=4, c=2, cellType="cell", rawValue=6)
tbl$renderTable()