buoy.widget
Class BTable

java.lang.Object
  buoy.event.EventSource
      buoy.widget.Widget
          buoy.widget.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:

• CellValueChangedEvent
• SelectionChangedEvent

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(int rows, int cols)
Create an empty BTable of a specified size.

BTable(java.lang.Object[][] cellData, java.lang.Object[] columnTitle)
Create a BTable, and populate it with the data in an array.

BTable(javax.swing.table.TableModel model)
Create a BTable whose contents are determined by a TableModel.

Method Summary

void	addColumn(java.lang.Object columnTitle) Add a column to this table.
void	addColumn(java.lang.Object columnTitle, java.lang.Object[] columnData) Add a column to the end of this table.
void	addRow(int index, java.lang.Object[] rowData) Add a row to the table.
void	addRow(java.lang.Object[] 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(java.awt.Point pos) Given a Point which represents a pixel location, find which column the Point lies on.
int	findRow(java.awt.Point pos) Given a Point which represents a pixel location, find which row the Point lies on.
java.lang.Object	getCellValue(int row, int col) Get the value contained in a cell.
int	getColumnCount() Get the number of columns in the table.
java.lang.Object	getColumnHeader(int col) Get the header value for 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.
int	getColumnWidth(int col) Get the width of a column.
javax.swing.JTable	getComponent() Get the java.awt.Component corresponding to this Widget.
javax.swing.table.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.
java.awt.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, java.lang.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, java.lang.Object value) Set the header value for a column.
void	setColumnSelected(int col, boolean selected) Set whether a column is selected.
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	setColumnWidth(int col, int width) Set the width of a column.
void	setModel(javax.swing.table.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, 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, removeEventLink

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SELECT_NONE

public static final BTable.SelectionMode SELECT_NONE

SELECT_ROWS

public static final BTable.SelectionMode SELECT_ROWS

SELECT_COLUMNS

public static final BTable.SelectionMode SELECT_COLUMNS

SELECT_CELLS

public static final BTable.SelectionMode SELECT_CELLS

Constructor Detail

BTable

public BTable()

Create a BTable with no rows or columns.

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

BTable

public BTable(java.lang.Object[][] cellData,
              java.lang.Object[] columnTitle)

Create a BTable, and populate it with the data in an array.

Parameters:

cellData - element [i][j] is the object to display in row i, column j

columnTitle - the list of column titles (usually Strings)

BTable

public BTable(javax.swing.table.TableModel model)

Create a BTable whose contents are determined by a TableModel.

Method Detail

getComponent

public javax.swing.JTable getComponent()

Description copied from class: Widget

Get the java.awt.Component corresponding to this Widget.

Overrides:

getComponent in class Widget

getTableHeader

public BTable.BTableHeader getTableHeader()

Get the Widget that displays this table's column headers.

getModel

public javax.swing.table.TableModel getModel()

Get the TableModel which controls the contents of this BTable.

setModel

public void setModel(javax.swing.table.TableModel model)

Set the TableModel which controls the contents of this BTable.

addColumn

public void addColumn(java.lang.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(java.lang.Object columnTitle,
                      java.lang.Object[] 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)

columnData - the objects to display in the cells of the new column

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

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.

addRow

public void addRow(java.lang.Object[] 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:

rowData - the objects to display in the cells of the new row

addRow

public void addRow(int index,
                   java.lang.Object[] 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

rowData - the objects to display in the cells of the new row

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

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.

getRowCount

public int getRowCount()

Get the number of rows in the table.

getColumnCount

public int getColumnCount()

Get the number of columns in the table.

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

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

getCellValue

public java.lang.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

setCellValue

public void setCellValue(int row,
                         int col,
                         java.lang.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

getColumnHeader

public java.lang.Object getColumnHeader(int col)

Get the header value for a column.

Parameters:

col - the column index

setColumnHeader

public void setColumnHeader(int col,
                            java.lang.Object value)

Set the header value for a column.

Parameters:

col - the column index

value - the value to place into the column header

getRowHeight

public int getRowHeight(int row)

Get the height of a row.

Parameters:

row - the row index

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

getColumnWidth

public int getColumnWidth(int col)

Get the width of a column.

Parameters:

col - the column index

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

sizeColumnToFit

public void sizeColumnToFit(int col)

Adjust the width of a column based on the size of its header.

Parameters:

col - the column index

getColumnsResizable

public boolean getColumnsResizable()

Get whether the user is allowed to resize columns by clicking between the headers and dragging.

setColumnsResizable

public void setColumnsResizable(boolean resizable)

Set whether the user is allowed to resize columns by clicking between the headers and dragging.

getColumnsReorderable

public boolean getColumnsReorderable()

Get whether the user is allowed to reorder columns by dragging their headers.

setColumnsReorderable

public void setColumnsReorderable(boolean reorderable)

Set whether the user is allowed to reorder columns by dragging their headers.

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.

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.

isMultipleSelectionEnabled

public boolean isMultipleSelectionEnabled()

Determine whether this table allows multiple cells to be selected.

setMultipleSelectionEnabled

public void setMultipleSelectionEnabled(boolean multiple)

Set whether this table should allow 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

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

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.

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

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

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.

isCellSelected

public boolean isCellSelected(int row,
                              int col)

Determine whether a cell is selected.

Parameters:

row - the row index

col - the column index

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

getSelectedCells

public java.awt.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.

clearSelection

public void clearSelection()

Deselect all rows and columns.

findRow

public int findRow(java.awt.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

findColumn

public int findColumn(java.awt.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

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

getShowHorizontalLines

public boolean getShowHorizontalLines()

Get whether this table displays horizontal lines between the rows.

setShowHorizontalLines

public void setShowHorizontalLines(boolean show)

Set whether this table displays horizontal lines between the rows.

getShowVerticalLines

public boolean getShowVerticalLines()

Get whether this table displays vertical lines between the columns.

setShowVerticalLines

public void setShowVerticalLines(boolean show)

Set whether this table displays vertical lines between the columns.

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