de.kupzog.ktable
Interface KTableModel

All Known Implementing Classes:
BooleanModelExample, KTableDefaultModel, KTableSortedModel, PaletteExampleModel, SortableModelExample, SpanModelExample, TextModelExample, TownExampleModel

public interface KTableModel

The table model is the most important part of KTable. It provides
- content information
- layout information
- rendering information
to the KTable.

Generally speaking, all functions should return their results as quick as possible, since they might be called a few times when laying out and drawing the widget.

NOTE that there exists a default implementation in the class KTableDefaultModel that handles the column width and row height in the table. It also provides a framework for more advanced tablemodels, for example KTableSortedModel.
Before implementing this interface, consider extending KTableDefaultModel

Author:
Friedrich Kupzog, Lorenz Maierhofer

Method Summary
 org.eclipse.swt.graphics.Point belongsToCell(int col, int row)
          Allows cells to merge with other cells.
 KTableCellEditor getCellEditor(int col, int row)
          A table cell will be "in place editable" if this method returns a valid cell editor for the given cell.
 KTableCellRenderer getCellRenderer(int col, int row)
          Returns the cell renderer for the given cell.
 int getColumnCount()
          This function tells the KTable how many columns have to be displayed.
 int getColumnWidth(int col)
          Each column can have its individual width.
 java.lang.Object getContentAt(int col, int row)
          This method should return the content at the given position.
 int getFixedHeaderColumnCount()
          This function tells the KTable how many columns form the "column header".
 int getFixedHeaderRowCount()
          This function tells the KTable how many rows form the "row header".
 int getFixedSelectableColumnCount()
          This functon tells the KTable how many columns form a fixed region that is not scrolled.
 int getFixedSelectableRowCount()
          This functon tells the KTable how many rows form a fixed region that is not scrolled.
 int getRowCount()
          This function tells the KTable how many rows have to be displayed.
 int getRowHeight(int row)
          All rows except the first row have the same height.
 int getRowHeightMinimum()
          This function should return the minimum height of the rows.
 java.lang.String getTooltipAt(int col, int row)
          This method allows the model to set a tooltip for a given cell.
 boolean isColumnResizable(int col)
          This function should return true if the user should be allowed to resize the given column.
 boolean isRowResizable(int row)
          This function should return true if the user should be allowed to resize the rows.
 void setColumnWidth(int col, int width)
          Each column can have its individual width.
 void setContentAt(int col, int row, java.lang.Object value)
          If getCellEditor() does return any editor instead of null, the table will use this method to set the changed cell values.
 void setRowHeight(int row, int value)
          If the user resizes a row, the model has to keep track of these changes.
 

Method Detail

getContentAt

java.lang.Object getContentAt(int col,
                              int row)
This method should return the content at the given position. The content is an Object, that means it can be everything.

The returned Object is handed over to the KTableCellRenderer. You can decide which renderer is used in getCellRenderer. Usually, the renderer expects the content being of a certain type.


getTooltipAt

java.lang.String getTooltipAt(int col,
                              int row)
This method allows the model to set a tooltip for a given cell. It is shown when the mouse stops over a cell and typically gives advanced information or shows the complete content.

Return null or "" if no tooltip should be displayed.

Parameters:
col - The column index
row - The row index
Returns:
Returns the text that should be displayed when the tooltip for the cell is shown to the user.

getCellEditor

KTableCellEditor getCellEditor(int col,
                               int row)
A table cell will be "in place editable" if this method returns a valid cell editor for the given cell. For no edit functionalitity return null.

Parameters:
col - The column index
row - The row index
Returns:
Returns an instance of KTableCellEditor that will be responsible of showing an editor control and writing back the changed value by calling setContentAt().

setContentAt

void setContentAt(int col,
                  int row,
                  java.lang.Object value)
If getCellEditor() does return any editor instead of null, the table will use this method to set the changed cell values.

Parameters:
col - The column index.
row - The row index.

getCellRenderer

KTableCellRenderer getCellRenderer(int col,
                                   int row)
Returns the cell renderer for the given cell.

For a first approach, KTableCellRenderer.defaultRenderer can be returned. For some default renderer behavior, look at the classses in the package de.kupzog.ktable.cellrenderers .

If this does not suite your needs, you can easily derive your own cellrenderer from KTableCellRenderer. If it is some general, not too specific renderer, we would be happy to include it as a default renderer!

Parameters:
col - The column index
row - The row index
Returns:
Returns the cell renderer that is responsible for drawing the cell.

belongsToCell

org.eclipse.swt.graphics.Point belongsToCell(int col,
                                             int row)
Allows cells to merge with other cells.

Return the column and row index of the cell the given cell should be merged with. Note that cells can only merge with cells that have a row/col index smaller or equal than their own index.

The content of a spanned, large cell is determined by the left upper cell, a 'supercell'. Such supercells as well as cells that do not span always return their own indices. So if no cell spanning is desired, simply return the given cell location:
return new Point(col, row);

To visualize the expected return value: Normal table: Spanned table: ___________ ___________ |__|__|__|__| | |__|__| |__|__|__|__| |_____|__|__| In this case, the left upper cell (0,0) returns its own index and is responsible for the content of the whole spanned cell. The cells (0,1), (1,0) and (1,1) are overlapped and thus not visible. So they return (0,0) to signal that they belong to the cell (0,0). Note that in this case, the value of the cell (1,1) is never requested, since the large cell must always be a rectangle. Cells like ___________ | __|__|__| |__|__|__|__| are not possible.

Parameters:
col - the column index
row - the row index
Returns:
Return the given cell, or a cell the given cell should be merged with. Point.x corresponds to column index, Point.y corresponds to row index.

getRowCount

int getRowCount()
This function tells the KTable how many rows have to be displayed.

KTable counts header rows as normal rows, so the number of header rows has to be added to the number of data rows. The function must at least return the number of fixed (header + selectable) rows.

Returns:
The number of rows in the table, including the fixed rows.

getFixedHeaderRowCount

int getFixedHeaderRowCount()
This function tells the KTable how many rows form the "row header".

These rows are always displayed and not scrolled. Note that the total number of fixed columns is the sum of header and selectable fixed columns.

Returns:
int The number of fixed rows.

getFixedSelectableRowCount

int getFixedSelectableRowCount()
This functon tells the KTable how many rows form a fixed region that is not scrolled. The clickable or selectable fixed columns start after getFixedRowCount() rows. Note that the number of fixed and fixed selectable rows must be smaller or equal to getRowCount().

Returns:
Returns the number of fixed, selectable rows.

getColumnCount

int getColumnCount()
This function tells the KTable how many columns have to be displayed.

It must at least return the number of fixed and fixed selectable Columns.

Returns:
Returns the number of columns in the table, including all fixed columns.

getFixedHeaderColumnCount

int getFixedHeaderColumnCount()
This function tells the KTable how many columns form the "column header". These columns are always displayed and not scrolled - that means they are fixed. Note that cells in that region cannot be selected! The total of all fixed cells is formed by selectable and header cells.

Returns:
The number of fixed columns in the table (must be smaller or equal to the total number of columns in the table.

getFixedSelectableColumnCount

int getFixedSelectableColumnCount()
This functon tells the KTable how many columns form a fixed region that is not scrolled. The clickable fixed columns start after getFixedColumnCount() columns. Note that the number of fixed and fixed clickable columns must be smaller or equal to getColumnCount().

Returns:
Returns the number of fixed, selectable columns.

getColumnWidth

int getColumnWidth(int col)
Each column can have its individual width. The model has to manage these widths and return the values with this function.

Parameters:
col - The index of the column
Returns:
The width in pixels for this column.

isColumnResizable

boolean isColumnResizable(int col)
This function should return true if the user should be allowed to resize the given column. (all rows have the same height except the first)

Parameters:
col - The column index
Returns:
Returns true if the column is resizable.

setColumnWidth

void setColumnWidth(int col,
                    int width)
Each column can have its individual width. The model has to manage these widths. If the user resizes a column, the model has to keep track of these changes. The model is informed about such a resize by this method. (view updates are managed by the table)

Parameters:
col - the column index
width - The width in pixels to set for the given column.

getRowHeight

int getRowHeight(int row)
All rows except the first row have the same height.

Parameters:
row - The row index for the row height.
Returns:
the current height of all except the first row.

isRowResizable

boolean isRowResizable(int row)
This function should return true if the user should be allowed to resize the rows.


getRowHeightMinimum

int getRowHeightMinimum()
This function should return the minimum height of the rows. It is only needed if the rows are resizable.

Returns:
Returns the minimum height for the rows.

setRowHeight

void setRowHeight(int row,
                  int value)
If the user resizes a row, the model has to keep track of these changes. The model is informed about such a resize by this method. (view updates are managed by the table)

Parameters:
row - The row index.
value - The height of all except the first row.