Home

Theory of Operation (1.6)

Grid Regions and Coordinate Systems

Even though NatTable has 'table' in its name, its internal model is technically that of a grid. Configuration for NatTable is largely driven through the INatTableModel interface. The INatTableModel divides the grid into the following regions:

+----------+--------------------+
|0,0 ......|0,0 ................|
|..........|....................|
|. Corner .|.. Column Header ...|
|..........|....................|
|.... n1,m1|.............. n2,m2|
+----------+--------------------+
|0,0 ......|0,0 ................|
|..........|....................|
|..........|....................|
|. Row ....|....... Body .......|
|. Header .|....................|
|..........|....................|
|..........|....................|
|.... n3,m3|.............. n4,m4|
+----------+--------------------+

Each region has its own region-relative coordinate system. In addition, we sometimes talk about Grid coordinates, which are for the grid as a whole, irrespective of region. For example:

c - corner cell
C - Column header cell
R - Row header cell
b - body cell
 
. . . 0 1 2 3 4 5 6 7 8 9
. . . . . 0 1 2 3 4 5 6 7
. . . . . . . . . . . . .
0 . . c c c C C C C C C C
1 . . c c c C C C C C C C
2 0 . R R R b b b b b b b
3 1 . R R R b b b b b b b
4 2 . R R R b b b b b b b
5 3 . R R R b b b b b b b
6 4 . R R R b b b b b b b

Here the Grid coordinates range from row, col indexes (0,0) to (6,9). The Body section consists of cells from Grid coordinate (2,3) to (6,9); but in terms of Body-relative coordinates, the Body section consists of cells from Body coordinate (0,0) to (4,7).

Model, Reordered, Viewable and Visible Coordinates

In addition to the various grid regions, NatTable recognizes several layered coordinate systems:

Behind everything is the model coordinate system, which holds all of the data accessible to NatTable, whether or not it is currently visible through the UI.

NatTable allows for columns in this model grid to be reordered when it is shown through the UI. When this reordering happens, the underlying model grid is not modified. Instead, NatTable merely keeps track of what the desired reordering information and uses this information to appropriately render the grid. This gives rise to the reordered coordinate system, which consists of grid cells ordered according the the way in which they will be viewed through the UI.

Similarly, columns may be hidden from view in the UI. The viewable coordinate system is a essentially subset of the reordered coordinate system consisting of all non-hidden grid cells. Note that the viewable coordinate system contains the cells that are potentially visible, in the order in which they are seen in the UI.

The visible coordinate system consists of those cells that are actually visible to the user through the UI. It is a subset of the viewable coordinate system, with a translated origin corresponding to the location of the UI viewport.

Drawn vs. Composite

In order to support very large grids, NatTable does not allocate widgets for every cell in the grid. Instead, it draws each cell on a scrollable SWT canvas. When a particular cell is selected for edit, however, a widget control is often needed, so in that case NatTable instantiates an appropriate widget control and repositions and resizes it over the location of the cell to be edited. The INatCellPainter is responsible for cell painting, and the INatCellEditor is responsible for instantiating an edit control when a cell is selected for edit.

Cell Rendering

NatTable tries hard to render only what is needed, so it tracks what cells are currently visible and only renders them. All of the cell rendering is controlled through INatCellRenderer instances. Each grid region has its own INatCellRenderer. So when a column header cell needs to be painted, the first thing NatTable does is ask for the column header regions' INatCellRenderer. The INatCellRenderer has accessor methods to get an INatCellPainter or an INatCellEditor that is used to render a given cell. INatCellRenderer also has various methods to get the data and style information associated with a cell.