de.kupzog.ktable
Class KTable

java.lang.Object
  extended by org.eclipse.swt.widgets.Widget
      extended by org.eclipse.swt.widgets.Control
          extended by org.eclipse.swt.widgets.Scrollable
              extended by org.eclipse.swt.widgets.Composite
                  extended by org.eclipse.swt.widgets.Canvas
                      extended by de.kupzog.ktable.KTable
All Implemented Interfaces:
org.eclipse.swt.graphics.Drawable

public class KTable
extends org.eclipse.swt.widgets.Canvas

Custom drawn tabel widget for SWT GUIs.

The idea of KTable is to have a flexible grid of cells to display data in it. The class focuses on displaying data and not on collecting the data to display. The latter is done by the KTableModel which has to be implemented for each specific case. Some default tasks are done by a base implementation called KTableDefaultModel. Look also into KTableSortedModel that provides a transparent sorting of cells.
The table asks the table model for the amount of columns and rows, the sizes of columns and rows and for the content of the cells which are currently drawn. Even if the table has a million rows, it won’t get slower because it only requests those cells it currently draws. Only a bad table model can influence the drawing speed negatively.

When drawing a cell, the table calls a KTableCellRenderer to do this work. The table model determines which cell renderer is used for which cell. A default renderer is available (KTableCellRenderer.defaultRenderer), but the creation of self-written renderers for specific purposes is assumed. Some default renderers are available in the package de.kupzog.ktable.cellrenderers.*.

KTable allows to F columns and rows. Each column can have an individual size while the rows are all of the same height except the first row. Multiple column and row headers are possible. These "fixed" cells will not be scrolled out of sight. The column and row count always starts in the upper left corner with 0, independent of the number of column headers or row headers.

It is also possible to span cells over several rows and/or columns. The KTable asks the model do provide this information via belongsToCell(col, row). This method must return the cell the given cell should be merged with.

Changing of model values is possible by implementations of KTableCellEditor. Again the KTable asks the model to provide an implementation. Note that there are multiple celleditors available in the package de.kupzog.ktable.editors!

Author:
Friederich Kupzog
See Also:
KTableModel, KTableDefaultModel, KTableSortedModel, KTableCellRenderer, KTableCellEditor, KTableCellSelectionListener

Field Summary
 
Fields inherited from class org.eclipse.swt.widgets.Control
handle
 
Constructor Summary
KTable(org.eclipse.swt.widgets.Composite parent, int style)
          Creates a new KTable.
 
Method Summary
 void addCellResizeListener(KTableCellResizeListener listener)
          Adds a listener that is notified when a cell is resized.
 void addCellSelectionListener(KTableCellSelectionListener listener)
          Adds a listener that is notified when a cell is selected.
 org.eclipse.swt.graphics.Point calcColumnNum(int x, int y)
          Returns the number of the column that is present at position x or -1, if out of area.
 void clearSelection()
          Clears the current selection (in all selection modes).
 void dispose()
           
 org.eclipse.swt.graphics.Rectangle getCellRect(int col, int row)
          Returns the area that is occupied by the given cell.
 org.eclipse.swt.graphics.Point[] getCellSelection()
          Returns an array of the selected cells as Point[].
 KTableModel getModel()
          returns the current table model
 int[] getRowSelection()
          Returns an array of the selected row numbers.
 int getStyle()
           
 java.lang.String getToolTipText()
          Returns the global tooltip for the whole table.
 org.eclipse.swt.graphics.Point getValidCell(int colToCheck, int rowToCheck)
          Looks into the model to determine if the given cell is overlapped by a cell that spans several columns/rows.
 org.eclipse.swt.graphics.Rectangle getVisibleCells()
           
 int getVisibleRowCount()
           
 boolean isCellFullyVisible(int col, int row)
           
 boolean isCellSelected(int col, int row)
          Returns true, if the given cell is selected.
 boolean isCellVisible(int col, int row)
           
 boolean isFixedCell(int col, int row)
           
 boolean isHeaderCell(int col, int row)
           
 boolean isMultiSelectMode()
          Returns true if in "Multi Selection Mode".
 boolean isRowFullyVisible(int row)
           
 boolean isRowSelected(int row)
          Returns true, if the given row is selected.
 boolean isRowSelectMode()
          Returns true if in "Full Selection Mode".
 boolean isRowVisible(int row)
           
 void openEditorInFocus()
          This method activated the cell editor on the current focus cell, if the table model allows cell editing for this cell.
 void redraw(int firstCol, int firstRow, int numOfCols, int numOfRows)
          Redraws the the cells only in the given area.
 void redraw(org.eclipse.swt.graphics.Rectangle cellsToRedraw)
          Redraws the the cells only in the given area.
 boolean removeCellResizeListener(KTableCellResizeListener listener)
          Removes the listener if present.
 boolean removeCellSelectionListener(KTableCellSelectionListener listener)
          Removes the listener if present.
 int resizeColumnOptimal(int column)
          Resizes the given column to its optimal width.
 void setDefaultCursor(org.eclipse.swt.graphics.Cursor cursor, org.eclipse.swt.graphics.Point size_below_hotspot)
          Sets the default cursor to the given cursor.
 void setModel(KTableModel model)
          Sets the table model.
 void setSelection(int col, int row, boolean scroll)
          Selects the given cell.
 void setSelection(org.eclipse.swt.graphics.Point[] selections, boolean scroll)
          Selects the given cells - Point.x is column index, Point.y is row index.
 void setStyle(int style)
          Overwrites the style bits that determine certain behavior of KTable.
 void setToolTipText(java.lang.String tooltip)
          Sets the global tooltip for the whole table.
 void updateCell(int col, int row)
          Interface method to update the content of a cell.
 
Methods inherited from class org.eclipse.swt.widgets.Canvas
getCaret, scroll, setCaret, setFont
 
Methods inherited from class org.eclipse.swt.widgets.Composite
changed, computeSize, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, setFocus, setLayout, setLayoutDeferred, setTabList
 
Methods inherited from class org.eclipse.swt.widgets.Scrollable
computeTrim, getClientArea, getHorizontalBar, getVerticalBar
 
Methods inherited from class org.eclipse.swt.widgets.Control
addControlListener, addFocusListener, addHelpListener, addKeyListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addPaintListener, addTraverseListener, computeSize, forceFocus, getAccessible, getBackground, getBorderWidth, getBounds, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getParent, getShell, getSize, getVisible, internal_dispose_GC, internal_new_GC, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, redraw, redraw, removeControlListener, removeFocusListener, removeHelpListener, removeKeyListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removePaintListener, removeTraverseListener, setBackground, setBounds, setBounds, setCapture, setCursor, setEnabled, setForeground, setLayoutData, setLocation, setLocation, setMenu, setParent, setRedraw, setSize, setSize, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, update
 
Methods inherited from class org.eclipse.swt.widgets.Widget
addDisposeListener, addListener, getData, getData, getDisplay, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, setData, setData, toString
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

KTable

public KTable(org.eclipse.swt.widgets.Composite parent,
              int style)
Creates a new KTable. possible styles:
Method Detail

dispose

public void dispose()
Overrides:
dispose in class org.eclipse.swt.widgets.Widget

getVisibleRowCount

public int getVisibleRowCount()
Returns:
Returns the number of visible rows in the table. This always contains the fixed rows, and adds the number of rows that fit in the rest based on the currently shown top-row.

getCellRect

public org.eclipse.swt.graphics.Rectangle getCellRect(int col,
                                                      int row)
Returns the area that is occupied by the given cell. Respects cell span.

Parameters:
col - the column index
row - the row index
Returns:
returns the area the cell content is drawn at.
Throws:
java.lang.IllegalArgumentException - if the given cell is not a cell that is visible, but overlapped by a spanning cell. Call getValidCell() first to ensure it is a visible cell.

redraw

public void redraw(org.eclipse.swt.graphics.Rectangle cellsToRedraw)
Redraws the the cells only in the given area.

Parameters:
cellsToRedraw - Defines the area to redraw. The rectangles elements are not pixels but cell numbers.

redraw

public void redraw(int firstCol,
                   int firstRow,
                   int numOfCols,
                   int numOfRows)
Redraws the the cells only in the given area.

Parameters:
firstCol - the first column to draw.
firstRow - the first row to draw. (Map if you use a sorted model!)
numOfCols - the number of columns to draw.
numOfRows - the number of rows to draw.

getValidCell

public org.eclipse.swt.graphics.Point getValidCell(int colToCheck,
                                                   int rowToCheck)
Looks into the model to determine if the given cell is overlapped by a cell that spans several columns/rows. In that case the index of the cell responsible for the content (in the left upper corner) is returned. Otherwise the given cell is returned.

Parameters:
colToCheck - The column index of the cell to check.
rowToCheck - The row index of the cell to check. (as seen by the KTable. Map if you use a sorted model!)
Returns:
returns the cell that overlaps the given cell, or the given cell if no cell overlaps it.
Throws:
java.lang.IllegalArgumentException - If the model returns cells on Model.belongsToCell() that are on the right or below the given cell.
See Also:
KTableSortedModel#mapToTable(int);

updateCell

public void updateCell(int col,
                       int row)
Interface method to update the content of a cell.

Don't forget to map the row index if a sorted model is used.

Parameters:
col - The column index
row - The row index.
See Also:
KTableSortedModel.mapRowIndexToTable(int)

isFixedCell

public boolean isFixedCell(int col,
                           int row)
Parameters:
col - The column index
row - The row index
Returns:
Returns true if the given cell is a fixed cell, that is a header cell. Returns false otherwise.

isHeaderCell

public boolean isHeaderCell(int col,
                            int row)
Parameters:
col - The column index
row - The row index
Returns:
Returns true if the given cell is within the region specified by the model using the methods getFixedHeaderColumnCount() and getFixedHeaderRowCount()

setDefaultCursor

public void setDefaultCursor(org.eclipse.swt.graphics.Cursor cursor,
                             org.eclipse.swt.graphics.Point size_below_hotspot)
Sets the default cursor to the given cursor. This instance is saved internally and displayed whenever no linecursor or resizecursor is shown.

The difference to setCursor is that this cursor will be preserved over action cursor changes.

Parameters:
cursor - The cursor to use, or null if the OS default cursor should be used.
size_below_hotspot - The number of pixels that are needed to paint the cursor below and right of the cursor hotspot (that is the actual location the cursor is pointing to).

NOTE that this is just there to allow better positioning of tooltips. Currently SWT does not provide an API to get the size of the cursor. So these values are taken to calculate the position of the tooltip. The the tooltip is placed pt.x pixels left and pt.y pixels below the mouse location.
If you don't know the size of the cursor (for example you use a default one), set null or new Point(-1, -1).


calcColumnNum

public org.eclipse.swt.graphics.Point calcColumnNum(int x,
                                                    int y)
Returns the number of the column that is present at position x or -1, if out of area. When cells are spanned, returns the address of the spanned cell.

Parameters:
x - the x location of an event in table coordinates
y - The y location of an event in table coordinates
Returns:
Returns the point where x is the column index, y is the row index.

isCellVisible

public boolean isCellVisible(int col,
                             int row)

isCellFullyVisible

public boolean isCellFullyVisible(int col,
                                  int row)

isRowVisible

public boolean isRowVisible(int row)
Parameters:
row - The row index AS SEEN BY KTABLE. If you use a sorted model, don't forget to map the index.
Returns:
Returns true if the row is visible.

isRowFullyVisible

public boolean isRowFullyVisible(int row)
Parameters:
row - the row index to check - as seen by ktable. If you use a sorted model, don't forget to map.
Returns:
Returns true if the row is fully visible.

setToolTipText

public void setToolTipText(java.lang.String tooltip)
Sets the global tooltip for the whole table.
Note that this is only shown if the cell has no tooltip set. For tooltips on cell level (that overwrite this value), look for the method getTooltipText().

Overrides:
setToolTipText in class org.eclipse.swt.widgets.Control
Parameters:
tooltip - The global tooltip for the table.
See Also:
KTableModel.getTooltipAt(int, int), getToolTipText()

getToolTipText

public java.lang.String getToolTipText()
Returns the global tooltip for the whole table.
Note that this is not shown when there is a non-empty tooltip for the cell.

Overrides:
getToolTipText in class org.eclipse.swt.widgets.Control
See Also:
setToolTipText(String), KTableModel.getTooltipAt(int, int)

resizeColumnOptimal

public int resizeColumnOptimal(int column)
Resizes the given column to its optimal width. Is also called if user doubleclicks in the resize area of a resizable column. The optimal width is determined by asking the CellRenderers for the visible cells of the column for the optimal with and taking the minimum of the results. Note that the optimal width is only determined for the visible area of the table because otherwise this could take very long time.

Parameters:
column - The column to resize
Returns:
int The optimal with that was determined or -1, if column out of range.

openEditorInFocus

public void openEditorInFocus()
This method activated the cell editor on the current focus cell, if the table model allows cell editing for this cell.


addCellSelectionListener

public void addCellSelectionListener(KTableCellSelectionListener listener)
Adds a listener that is notified when a cell is selected. This can happen either by a click on the cell or by arrow keys. Note that the listener is not called for each cell that the user selects in one action using Shift+Click. To get all these cells use the listener and getCellSelecion() or getRowSelection().

Parameters:
listener -

addCellResizeListener

public void addCellResizeListener(KTableCellResizeListener listener)
Adds a listener that is notified when a cell is resized. This happens when the mouse button is released after a resizing.

Parameters:
listener -

removeCellSelectionListener

public boolean removeCellSelectionListener(KTableCellSelectionListener listener)
Removes the listener if present. Returns true, if found and removed from the list of listeners.


removeCellResizeListener

public boolean removeCellResizeListener(KTableCellResizeListener listener)
Removes the listener if present. Returns true, if found and removed from the list of listeners.


isRowSelectMode

public boolean isRowSelectMode()
Returns true if in "Full Selection Mode". Mode is determined by style bits in the constructor or by setStyle(). (style: SWT.FULL_SELECTION)

Returns:
boolean

isMultiSelectMode

public boolean isMultiSelectMode()
Returns true if in "Multi Selection Mode". Mode is determined by style bits in the constructor (SWT.MULTI) or by getStyle().


clearSelection

public void clearSelection()
Clears the current selection (in all selection modes).


setSelection

public void setSelection(int col,
                         int row,
                         boolean scroll)
Selects the given cell. If scroll is true, it scrolls to show this cell if neccessary. In Row Selection Mode, the given row is selected and a scroll to the given column is done. Does nothing if the cell does not exist.

Note that if you use a sorted model, don't forget to map the row index!

Parameters:
col -
row -
scroll -

setSelection

public void setSelection(org.eclipse.swt.graphics.Point[] selections,
                         boolean scroll)
Selects the given cells - Point.x is column index, Point.y is row index. If scroll is true, scrolls so that the first of the given cell indexes becomes fully visible.

Don't forget to map the row index if a sorted model is used.

Parameters:
selections - The selected cells as points. If null or an empty array, clears the selection.
scroll - Wether it is reuqested to scroll to the first cell given as selection.
See Also:
KTableSortedModel.mapRowIndexToTable(int)

isCellSelected

public boolean isCellSelected(int col,
                              int row)
Returns true, if the given cell is selected. Works also in Row Selection Mode.

Parameters:
col - the column index.
row - the row index.
Returns:
boolean Returns true if the given cell is selected.

isRowSelected

public boolean isRowSelected(int row)
Returns true, if the given row is selected. Returns always false if not in Row Selection Mode!

If you use a sorted model, don't forget to map the row index first.

Parameters:
row - The row index as seen by the KTable.
Returns:
boolean returns true if the row is selected at the moment.

getRowSelection

public int[] getRowSelection()
Returns an array of the selected row numbers. Returns null if not in Row Selection Mode. Returns an array with one or none element if not in Multi Selection Mode.

NOTE: This returns the cell indices as seen by the KTable. If you use a sorting model, don't forget to map the indices properly.

Returns:
int[] Returns an array of rows that are selected.
See Also:
KTableSortedModel.mapRowIndexToModel(int)

getCellSelection

public org.eclipse.swt.graphics.Point[] getCellSelection()
Returns an array of the selected cells as Point[]. The columns are stored in the x fields, rows in y fields. Returns null if in Row Selection Mode.
Returns an array with one or none element if not in Multi Selection Mode.

NOTE: This returns the cell indices as seen by the KTable. If you use a sorting model, don't forget to map the indices properly.

Returns:
int[] Returns an array of points that are selected. These are no copies, so don't directly manipulate them...
See Also:
KTableSortedModel.mapRowIndexToModel(int)

getVisibleCells

public org.eclipse.swt.graphics.Rectangle getVisibleCells()
Returns:
Returns the non-fixed cells that are currently visible. The returned rectangle has the columns on the x / width coordinates and the rows at the y / height coordinates.

setModel

public void setModel(KTableModel model)
Sets the table model. The table model provides data to the table.

Parameters:
model - The KTableModel instance that provides the table with all necessary data!
See Also:
for more information.

getModel

public KTableModel getModel()
returns the current table model

Returns:
KTableModel

getStyle

public int getStyle()
Overrides:
getStyle in class org.eclipse.swt.widgets.Widget

setStyle

public void setStyle(int style)
Overwrites the style bits that determine certain behavior of KTable. Note that not all style bits can be changed after KTable is created.

Parameters:
style - The updated style bits (ORed together). Possibilities:
  • SWTX.FILL_WITH_LASTCOL - Makes the table enlarge the last column to always fill all space.
  • SWTX.FILL_WITH_DUMMYCOL - Makes the table fill any remaining space with dummy columns to fill all space.
  • SWT.FLAT - Does not paint a dark outer border line.
  • SWT.MULTI - Sets the "Multi Selection Mode". In this mode, more than one cell or row can be selected. The user can achieve this by shift-click and ctrl-click. The selected cells/rows can be scattored ofer the complete table. If you pass false, only a single cell or row can be selected. This mode can be combined with the "Row Selection Mode".
  • SWT.FULL_SELECTION - Sets the "Full Selection Mode". In the "Full Selection Mode", the table always selects a complete row. Otherwise, each individual cell can be selected. This mode can be combined with the "Multi Selection Mode".
  • SWTX.EDIT_ON_KEY - Activates a possibly present cell editor on every keystroke. (Default: only ENTER). However, note that editors can specify which events they accept.
  • SWT.HIDE_SELECTION - Hides the selected cells when the KTable looses focus.
  • SWTX.MARK_FOCUS_HEADERS - Makes KTable draw left and top header cells in a different style when the focused cell is in their row/column. This mimics the MS Excel behavior that helps find the currently selected cell(s).