TableCells {basictabler} | R Documentation |
R6 class that manages cells in a table.
Description
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()