buoy.widget

Class BTable


public class BTable
extends Widget

A BTable is a Widget that displays a grid of objects. Typically the objects are Strings, but other types of objects can be used as well. It optionally can allow the user to select rows, columns, or individual cells, and to edit the contents of cells. There are methods for adding and removing rows and columns, and for setting the contents of cells. Alternatively, you can set a TableModel to provide more complex behaviors.

BTable does not provide scrolling automatically. Normally, it is used inside a BScrollPane. When a BTable is set as the content of a BScrollPane, it automatically places its column headers (which are represented by a separate Widget) into the BScrollPane's column header position. When using a BTable outside a BScrollPane, you will need to call getTableHeader() to get the Widget representing the column headers, and position it separately.

You may also want to access the column headers directly, in order to respond to events in the headers. For example, suppose you want mouse clicks in a column header to select the clicked column, and deselect all other columns. This is done by adding an event listener to the header Widget:

 table.getTableHeader().addEventLink(MousePressedEvent.class, new Object() {
   void processEvent(MousePressedEvent ev)
   {
     table.clearSelection();
     table.setColumnSelected(table.findColumn(ev.getPoint()), true);
   }
 });
 

A BTable can optionally allow the user to reorder the columns by dragging their headers. This affects only the display of the table, not the internal data representation. Whenever a method takes a column index as an argument, that index refers to the internal ordering, not to the display order. Therefore, any reordering of columns by the user will be completely invisible to the program, and can be ignored.

A BTable is a wrapper around a JTable and its associated classes, which together form a powerful but also very complex API. BTable exposes only the most commonly used features of this API. To use other features, call getComponent() to get the underlying JTable, then manipulate it directly. For example, you can set a custom TableCellRenderer to customize the appearance of individual cells, or set a TableCellEditor to control the user interface for editing cells.

In addition to the event types generated by all Widgets, BTables generate the following event types:

Author:
Peter Eastman

Nested Class Summary

class
BTable.BTableHeader
This inner class is the Widget that draws the table's column headers.
static class
BTable.SelectionMode
This inner class represents a selection mode.

Field Summary

static BTable.SelectionMode
SELECT_CELLS
static BTable.SelectionMode
SELECT_COLUMNS
static BTable.SelectionMode
SELECT_NONE
static BTable.SelectionMode
SELECT_ROWS

Constructor Summary

BTable()
Create a BTable with no rows or columns.
BTable(TableModel model)
Create a BTable whose contents are determined by a TableModel.
BTable(cellData[][] , columnTitle[] )
Create a BTable, and populate it with the data in an array.
BTable(int rows, int cols)
Create an empty BTable of a specified size.

Method Summary

void
addColumn(Object columnTitle)
Add a column to this table.
void
addColumn(Object columnTitle, columnData[] )
Add a column to the end of this table.
void
addRow(int index, rowData[] )
Add a row to the table.
void
addRow(rowData[] )
Add a row to the end of the table.
void
clearSelection()
Deselect all rows and columns.
void
editCellAt(int row, int col)
Programmatically begin editing a specified cell, if editing is allowed.
int
findColumn(Point pos)
Given a Point which represents a pixel location, find which column the Point lies on.
int
findRow(Point pos)
Given a Point which represents a pixel location, find which row the Point lies on.
Object
getCellValue(int row, int col)
Get the value contained in a cell.
int
getColumnCount()
Get the number of columns in the table.
Object
getColumnHeader(int col)
Get the header value for a column.
int
getColumnWidth(int col)
Get the width of a column.
boolean
getColumnsReorderable()
Get whether the user is allowed to reorder columns by dragging their headers.
boolean
getColumnsResizable()
Get whether the user is allowed to resize columns by clicking between the headers and dragging.
TableModel
getModel()
Get the TableModel which controls the contents of this BTable.
int
getRowCount()
Get the number of rows in the table.
int
getRowHeight(int row)
Get the height of a row.
Point[]
getSelectedCells()
Get an array of Points which contain the indices of all selected cells.
int[]
getSelectedColumns()
Get an array which contains the indices of all selected columns.
int[]
getSelectedRows()
Get an array which contains the indices of all selected rows.
BTable.SelectionMode
getSelectionMode()
Get the selection mode for this table.
boolean
getShowHorizontalLines()
Get whether this table displays horizontal lines between the rows.
boolean
getShowVerticalLines()
Get whether this table displays vertical lines between the columns.
BTable.BTableHeader
getTableHeader()
Get the Widget that displays this table's column headers.
boolean
isCellSelected(int row, int col)
Determine whether a cell is selected.
boolean
isColumnEditable(int index)
Determine whether the cells in a particular column may be edited.
boolean
isColumnSelected(int col)
Determine whether a column is selected.
boolean
isMultipleSelectionEnabled()
Determine whether this table allows multiple cells to be selected.
boolean
isRowSelected(int row)
Determine whether a row is selected.
void
removeAllColumns()
Remove all columns from this table.
void
removeAllRows()
Remove all rows from the table.
void
removeColumn(int index)
Remove a column from this table.
void
removeRow(int index)
Remove a row from the table.
void
scrollToCell(int row, int col)
Scroll the BTable's parent BScrollPane to ensure that a particular cell is visible.
void
setCellSelected(int row, int col, boolean selected)
Set whether a cell is selected.
void
setCellValue(int row, int col, Object value)
Set the value contained in a cell.
void
setColumnEditable(int index, boolean editable)
Set whether the cells in a particular column may be edited.
void
setColumnHeader(int col, Object value)
Set the header value for a column.
void
setColumnSelected(int col, boolean selected)
Set whether a column is selected.
void
setColumnWidth(int col, int width)
Set the width of a column.
void
setColumnsReorderable(boolean reorderable)
Set whether the user is allowed to reorder columns by dragging their headers.
void
setColumnsResizable(boolean resizable)
Set whether the user is allowed to resize columns by clicking between the headers and dragging.
void
setModel(TableModel model)
Set the TableModel which controls the contents of this BTable.
void
setMultipleSelectionEnabled(boolean multiple)
Set whether this table should allow multiple cells to be selected.
void
setRowHeight(int row, int height)
Set the height of a row.
void
setRowSelected(int row, boolean selected)
Set whether a row is selected.
void
setSelectionMode(BTable.SelectionMode mode)
Set the selection mode for this table.
void
setShowHorizontalLines(boolean show)
Set whether this table displays horizontal lines between the rows.
void
setShowVerticalLines(boolean show)
Set whether this table displays vertical lines between the columns.
void
sizeColumnToFit(int col)
Adjust the width of a column based on the size of its header.

Methods inherited from class buoy.widget.Widget

addEventLink, dispatchEvent, getBackground, getBounds, getComponent, getCursor, getFont, getMaximumSize, getMinimumSize, getName, getParent, getPreferredSize, hasFocus, isEnabled, isFocusable, isVisible, repaint, requestFocus, setBackground, setCursor, setEnabled, setFocusable, setFont, setName, setVisible

Methods inherited from class buoy.event.EventSource

addEventLink, addEventLink, addEventLink, dispatchEvent, removeEventLink

Field Details

SELECT_CELLS

public static final BTable.SelectionMode SELECT_CELLS

SELECT_COLUMNS

public static final BTable.SelectionMode SELECT_COLUMNS

SELECT_NONE

public static final BTable.SelectionMode SELECT_NONE

SELECT_ROWS

public static final BTable.SelectionMode SELECT_ROWS

Constructor Details

BTable

public BTable()
Create a BTable with no rows or columns.

BTable

public BTable(TableModel model)
Create a BTable whose contents are determined by a TableModel.

BTable

public BTable(cellData[][] ,
              columnTitle[] )
Create a BTable, and populate it with the data in an array.
Parameters:

BTable

public BTable(int rows,
              int cols)
Create an empty BTable of a specified size.
Parameters:
rows - the number of rows
cols - the number of columns

Method Details

addColumn

public void addColumn(Object columnTitle)
Add a column to this table.

This method works by manipulating the default TableModel for this table. If you have set a custom model, either by passing it to the constructor or by calling setModel(), this method has no effect.

Parameters:
columnTitle - the title of the column to add (usually a String)

addColumn

public void addColumn(Object columnTitle,
                      columnData[] )
Add a column to the end of this table.

This method works by manipulating the default TableModel for this table. If you have set a custom model, either by passing it to the constructor or by calling setModel(), this method has no effect.

Parameters:
columnTitle - the title of the column to add (usually a String)

addRow

public void addRow(int index,
                   rowData[] )
Add a row to the table.

This method works by manipulating the default TableModel for this table. If you have set a custom model, either by passing it to the constructor or by calling setModel(), this method has no effect.

Parameters:
index - the position at which to add the row

addRow

public void addRow(rowData[] )
Add a row to the end of the table.

This method works by manipulating the default TableModel for this table. If you have set a custom model, either by passing it to the constructor or by calling setModel(), this method has no effect.

Parameters:

clearSelection

public void clearSelection()
Deselect all rows and columns.

editCellAt

public void editCellAt(int row,
                       int col)
Programmatically begin editing a specified cell, if editing is allowed.
Parameters:
row - the row containing the cell
col - the column containing the cell

findColumn

public int findColumn(Point pos)
Given a Point which represents a pixel location, find which column the Point lies on.
Parameters:
pos - the point of interest
Returns:
the column index, or -1 if the Point is outside the table

findRow

public int findRow(Point pos)
Given a Point which represents a pixel location, find which row the Point lies on.
Parameters:
pos - the point of interest
Returns:
the row index, or -1 if the Point is outside the table

getCellValue

public Object getCellValue(int row,
                           int col)
Get the value contained in a cell.
Parameters:
row - the row containing the cell
col - the column containing the cell

getColumnCount

public int getColumnCount()
Get the number of columns in the table.

getColumnHeader

public Object getColumnHeader(int col)
Get the header value for a column.
Parameters:
col - the column index

getColumnWidth

public int getColumnWidth(int col)
Get the width of a column.
Parameters:
col - the column index

getColumnsReorderable

public boolean getColumnsReorderable()
Get whether the user is allowed to reorder columns by dragging their headers.

getColumnsResizable

public boolean getColumnsResizable()
Get whether the user is allowed to resize columns by clicking between the headers and dragging.

getModel

public TableModel getModel()
Get the TableModel which controls the contents of this BTable.

getRowCount

public int getRowCount()
Get the number of rows in the table.

getRowHeight

public int getRowHeight(int row)
Get the height of a row.
Parameters:
row - the row index

getSelectedCells

public Point[] getSelectedCells()
Get an array of Points which contain the indices of all selected cells. For every selected cell, the array contains a Point whose x field contains the column index of the cell and whose y field contains the row index. If no cells are selected, this returns an empty array.

getSelectedColumns

public int[] getSelectedColumns()
Get an array which contains the indices of all selected columns. If no columns are selected, this returns an empty array.

If the selection mode is SELECT_ROWS, the value returned by this method is meaningless and should be ignored.


getSelectedRows

public int[] getSelectedRows()
Get an array which contains the indices of all selected rows. If no rows are selected, this returns an empty array.

If the selection mode is SELECT_COLUMNS, the value returned by this method is meaningless and should be ignored.


getSelectionMode

public BTable.SelectionMode getSelectionMode()
Get the selection mode for this table. This will be equal to SELECT_NONE, SELECT_ROWS, SELECT_COLUMNS, or SELECT_CELLS.

getShowHorizontalLines

public boolean getShowHorizontalLines()
Get whether this table displays horizontal lines between the rows.

getShowVerticalLines

public boolean getShowVerticalLines()
Get whether this table displays vertical lines between the columns.

getTableHeader

public BTable.BTableHeader getTableHeader()
Get the Widget that displays this table's column headers.

isCellSelected

public boolean isCellSelected(int row,
                              int col)
Determine whether a cell is selected.
Parameters:
row - the row index
col - the column index

isColumnEditable

public boolean isColumnEditable(int index)
Determine whether the cells in a particular column may be edited.

If you have set a custom model for this table, either by passing it to the constructor or by calling setModel(), the value returned by this method is meaningless and should be ignored.

Parameters:
index - the index of the column

isColumnSelected

public boolean isColumnSelected(int col)
Determine whether a column is selected.

If the selection mode is SELECT_ROWS, the value returned by this method is meaningless and should be ignored.

Parameters:
col - the column index

isMultipleSelectionEnabled

public boolean isMultipleSelectionEnabled()
Determine whether this table allows multiple cells to be selected.

isRowSelected

public boolean isRowSelected(int row)
Determine whether a row is selected.

If the selection mode is SELECT_COLUMNS, the value returned by this method is meaningless and should be ignored.

Parameters:
row - the row index

removeAllColumns

public void removeAllColumns()
Remove all columns from this table.

This method works by manipulating the default TableModel for this table. If you have set a custom model, either by passing it to the constructor or by calling setModel(), this method has no effect.


removeAllRows

public void removeAllRows()
Remove all rows from the table.

This method works by manipulating the default TableModel for this table. If you have set a custom model, either by passing it to the constructor or by calling setModel(), this method has no effect.


removeColumn

public void removeColumn(int index)
Remove a column from this table.

This method works by manipulating the default TableModel for this table. If you have set a custom model, either by passing it to the constructor or by calling setModel(), this method has no effect.

Parameters:
index - the index of the column to remove

removeRow

public void removeRow(int index)
Remove a row from the table.

This method works by manipulating the default TableModel for this table. If you have set a custom model, either by passing it to the constructor or by calling setModel(), this method has no effect.

Parameters:
index - the index of the row to remove

scrollToCell

public void scrollToCell(int row,
                         int col)
Scroll the BTable's parent BScrollPane to ensure that a particular cell is visible. If the parent is not a BScrollPane, the results of calling this method are undefined, but usually it will have no effect at all.
Parameters:
row - the row containing the cell
col - the column containing the cell

setCellSelected

public void setCellSelected(int row,
                            int col,
                            boolean selected)
Set whether a cell is selected.
Parameters:
row - the row index
col - the column index
selected - specifies whether the cell should be selected

setCellValue

public void setCellValue(int row,
                         int col,
                         Object value)
Set the value contained in a cell.
Parameters:
row - the row containing the cell
col - the column containing the cell
value - the value to place into the cell

setColumnEditable

public void setColumnEditable(int index,
                              boolean editable)
Set whether the cells in a particular column may be edited.

This method works by manipulating the default TableModel for this table. If you have set a custom model, either by passing it to the constructor or by calling setModel(), this method has no effect.

Parameters:
index - the index of the column
editable - specifies whether cells in the column may be edited

setColumnHeader

public void setColumnHeader(int col,
                            Object value)
Set the header value for a column.
Parameters:
col - the column index
value - the value to place into the column header

setColumnSelected

public void setColumnSelected(int col,
                              boolean selected)
Set whether a column is selected.
Parameters:
col - the column index
selected - specifies whether the column should be selected

setColumnWidth

public void setColumnWidth(int col,
                           int width)
Set the width of a column.
Parameters:
col - the column index
width - the new width for the column

setColumnsReorderable

public void setColumnsReorderable(boolean reorderable)
Set whether the user is allowed to reorder columns by dragging their headers.

setColumnsResizable

public void setColumnsResizable(boolean resizable)
Set whether the user is allowed to resize columns by clicking between the headers and dragging.

setModel

public void setModel(TableModel model)
Set the TableModel which controls the contents of this BTable.

setMultipleSelectionEnabled

public void setMultipleSelectionEnabled(boolean multiple)
Set whether this table should allow multiple cells to be selected.

setRowHeight

public void setRowHeight(int row,
                         int height)
Set the height of a row.
Parameters:
row - the row index
height - the new height for the row

setRowSelected

public void setRowSelected(int row,
                           boolean selected)
Set whether a row is selected.
Parameters:
row - the row index
selected - specifies whether the row should be selected

setSelectionMode

public void setSelectionMode(BTable.SelectionMode mode)
Set the selection mode for this table. This should be equal to SELECT_NONE, SELECT_ROWS, SELECT_COLUMNS, or SELECT_CELLS.

setShowHorizontalLines

public void setShowHorizontalLines(boolean show)
Set whether this table displays horizontal lines between the rows.

setShowVerticalLines

public void setShowVerticalLines(boolean show)
Set whether this table displays vertical lines between the columns.

sizeColumnToFit

public void sizeColumnToFit(int col)
Adjust the width of a column based on the size of its header.
Parameters:
col - the column index

Written by Peter Eastman.