oracle.javatools.ui.table
Class TableHelper

java.lang.Object
  oracle.javatools.ui.table.TableHelper

public class TableHelper
extends java.lang.Object

TableHelper is a decorator class for JTable with a number of nice and enhanced features and a cleaner UI, which are available as static helper methods. All these features are available in GenericTable. We strongly recommend our clients to use GenericTable. If you are already using a JTable or a customized JTable and could not move to GenericTable for some valid reason, you can get all the enhanced features through this TableHelper.

Features provided by this TableHelper:

• DropDown button for showing / hiding columns: A dropdown button is displayed at the end of the column header which contains checkbox menu items allowing the user to hide and show columns. This is handled regardless of the table model by adding and removing columns from the TableColumnModel. You can switch this behavior on and off using the setColumnSelectorAvailable() method. Clients can also decide on which columns user can hide using GenericTableModel.
• No Entry Instruction Text: This Instruction text will be displayed in the first row when there is no data in the table. The instruction text must be in the form: "No object Name". You can set this text using setNoEntryInstructionText() method.
• Sort column icon: A different column sort icon recommended by Oracle User Interface Team is displayed if the table is sorted based on a table column. The appearance of this icon is less distracting than the icons used for this purpose elsewhere (i.e. it isn't a garish bright green faux-3d thing that looks like it escaped from a 1991 Borland product), and is closer in appearance to the icon used by one particular operating system for this purpose. This is handled by GenericTableHeaderRenderer. Clients can set this as a renderer for their table column header. This is supported only if sorting is enabled through a RowSorter. See the method JTable.setRowSorter.
• Sort column highlighting: The column currently being used to sort the table is highlighted in a slightly different color from the other columns in the table. This makes it easier to see which column is the sort column. This is handled by GenericTableCellRenderer for the table cells which highlights the sort column. This is supported only if sorting is enabled through a RowSorter. See the method JTable.setRowSorter. Clients can all installGenericTableCellRenderers to set this renderer on JTable's default TableCellRender.
• Column Alignment: If the TableModel implements GenericTableModel and GenericTableCellRenderer is used for the table, the column will be aligned based on the getColumnAlignment() value for the column. Clients can set Generic renderer on their table using installGenericTableCellRenderers.
• Double click column resizing: When the user double-clicks on the separator between two columns, the column to the left of the separator will be resized to the width of the widest cell in that column. You can turn this behavior on and off using the setResizeColumnOnDoubleClick() method.
• Utility to resize columns: The sizeTableToContents() method can be used to resize all columns in this table so that they are wide enough to display the widest cell in that column. If called after populating your table model, this will improve the appearance of your table by reducing the number of truncated columns and making the columns a reasonable size for their contents.
• Setting preferred number of rows to display: The setPreferredVisibleRowCount method sets the preferred number of rows to display in a JTable without requiring scrolling. Setting this property affects the return value of getPreferredScrollableViewportSize method of the table, which is used to calculate the preferred size of an enclosing viewport.
• Column Header Selection support: JTableHeader doesn't select the column when we click on it. This feature adds column header selection support for the table. Clients can turn on this feature using setColumnHeaderSelectionEnabled method. Enabling this property will only select the table column when clicked on corresponding table header. To paint the selected column with a selection highlight background color, clients should set table's column renderer to GenericTableHeaderRenderer.
• SelectAll Rows support: If setSelectAllEnabled is turned on for the table, then user can click on the upper left corner of the table to select all elements in the table This will be applicable only if the table has a valid RowHeader.
• Rollover Highlighting: If rollOverHighlighting is enabled, cells will be painted with a special highlight color when the user hovers mouse over the cells or rows or columns. Turning on/off this property on table will automatically extend it to the table's row and column header. Clients can call setRolloverHighlightingEnabled method to enable or disable this. However clients should call this method after setting their Renderers on table or headers. The renderes should not be changed after turning on this feature. Rollover highlight will not work properly if they do so.
• Easy clipboard transfer handling: The values which are copied to the clipboard by the internal data transfer handler of TableHelper may come from DisplayableTable interface by implementing convertValueToText method. If values in the data model do not have a human-readable toString() representation which is suitable for the clipboard, they may be handled there. TableHelper's TableTransferHandler also supports paste operation which will paste the copied rows/columns depending on row or column selection. Clients can install this TransferHandler using installTableTransferHandler

Constructor Summary

TableHelper()

Method Summary

static int	getCellWidth(javax.swing.JTable table, java.lang.Object value, int row, int col) Return the preferred size of a table cell
static javax.swing.Action[]	getColumnSelectorActions(javax.swing.JTable table) Returns the additional ColumnSelector actions if it has been set before.
static int	getDefaultRowHeight() Returns the default row height for the table cell recommended by Oracle UI guidelines.
static java.lang.String	getNoEntryInstructionText(javax.swing.JTable table) Returns the instruction text of the table when there is no entry in the table.
static int	getPreferredVisibleRowCount(javax.swing.JTable table) Returns the value of the visibleRowCount property.
static javax.swing.Action	getSelectColumnsAction(javax.swing.JTable table) Returns the additional select columns action if it has been set before.
static javax.swing.Icon	getSortIconDown() Returns the column sort icon when the sort order is descending to be displayed on the table header.
static javax.swing.Icon	getSortIconUp() Returns the column sort icon when the sort order is ascending to be displayed on the table header.
static java.lang.String	getTruncatedCellValue(javax.swing.JTable table, int row, int col) Figure out if the renderer has been truncated by the column width and if so return the complete value of the cell.
static void	installGenericTableRenderer(javax.swing.JTable table) Set GenericTableCellRenderer for objects, numbers, doubles, dates, booleans, and icons column class type of this table.
static void	installTableTransferHandler(javax.swing.JTable table, boolean supportsPaste) Installs TableTransferHandler that supports copy and paste
static boolean	isColumnHeaderSelectionEnabled(javax.swing.JTable table) Returns whether column header selection is supported for the table.
static boolean	isColumnSelectorAvailable(javax.swing.JTable table) Get whether the dropdown button is displayed at the end of the column header for hiding and showing columns is available on this instance of table.
static boolean	isResizeColumnOnDoubleClick(javax.swing.JTable table) Get whether the user can resize columns in this table by double clicking the resize divider between two columns.
static boolean	isRolloverHighlightingEnabled(javax.swing.JTable table) Returns whether rollover highlighting is enabled/disabled on the table.
static boolean	isSelectAllEnabled(javax.swing.JTable table) Returns whether selectAll feature is enabled for the table.
static void	setColumnHeaderSelectionEnabled(javax.swing.JTable table, boolean select) Add column header selection support for the table.
static void	setColumnSelectorActions(javax.swing.JTable table, javax.swing.Action... actions) This method adds the specified actions to the end of ColumnSelector dropdow menu.
static void	setColumnSelectorAvailable(javax.swing.JTable table, boolean isAvailable) Set whether this table will display a dropdown button at the end of the column header to hide/show columns.
static void	setNoEntryInstructionText(javax.swing.JTable table, java.lang.String text) Sets the instruction text on the firt row of the table when there is no entry in the table.
static void	setPreferredVisibleRowCount(javax.swing.JTable table, int visibleRowCount) Sets the visibleRowCount property.
static void	setResizeColumnOnDoubleClick(javax.swing.JTable table, boolean isOn) Set whether the user can resize columns in this table by double clicking the resize divider between two columns.
static void	setRolloverHighlightingEnabled(javax.swing.JTable table, boolean enable) Set rollover highlighting enabled/disabled on the table.
static void	setSelectAllEnabled(javax.swing.JTable table, javax.swing.JScrollPane pane, boolean enable) Enables whether the user can click on upper left corner to select all cells in the table by clicking on it.
static void	setSelectColumnsAction(javax.swing.JTable table, javax.swing.Action selectColumn) This method adds the specified SelectColumns action to the end of ColumnSelector dropdow menu.
static void	setVisibleRows(javax.swing.JTable table, javax.swing.JScrollPane sp, int rows) Set the preferred size of the scrollpane to the desired number of visible table rows.
static int	sizeColumnToContents(javax.swing.JTable table, int col, boolean sortCol, int sampleSize, java.lang.Object[] prototypeValues) Size one column of a table to be just large enough to fully display its current contents.
static void	sizeColumnToContents(javax.swing.JTable table, int col, int sampleSize) Size one column of a table to be just large enough to fully display its current contents.
static void	sizeColumnToMaximumWidth(javax.swing.JTable table, int x) Size the column in the table at location x to the maximum width of all cells in that column.
static void	sizeTableToContents(javax.swing.JTable table)
static void	sizeTableToContents(javax.swing.JTable table, java.lang.Object[] prototypeValues) Utility method that will set the preferred size of all columns in this table so that they are just big enough to display their contents.
static void	stopCellEditing(javax.swing.JTable table) Utility method to stop cell editing in the table.

Methods inherited from class java.lang.Object

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

Constructor Detail

TableHelper

public TableHelper()

Method Detail

setColumnSelectorAvailable

public static void setColumnSelectorAvailable(javax.swing.JTable table,
                                              boolean isAvailable)

Set whether this table will display a dropdown button at the end of the column header to hide/show columns. To get this feature, table should be put inside a JScrollPane.

Parameters:

isAvailable - if true, a dropdown button will be provided at the end of the column header of this table with checkbox menu items for each column. The user can use these to hide and show columns.

isColumnSelectorAvailable

public static boolean isColumnSelectorAvailable(javax.swing.JTable table)

Get whether the dropdown button is displayed at the end of the column header for hiding and showing columns is available on this instance of table.

Returns:

whether the column selector drop down button is available.

setSelectColumnsAction

public static void setSelectColumnsAction(javax.swing.JTable table,
                                          javax.swing.Action selectColumn)

This method adds the specified SelectColumns action to the end of ColumnSelector dropdow menu. The name from the action is used as the menu item label. Before setting this action, clients should turn on the column selector using setColumnSelectorAvailable.

getSelectColumnsAction

public static javax.swing.Action getSelectColumnsAction(javax.swing.JTable table)

Returns the additional select columns action if it has been set before.

setColumnSelectorActions

public static void setColumnSelectorActions(javax.swing.JTable table,
                                            javax.swing.Action... actions)

This method adds the specified actions to the end of ColumnSelector dropdow menu. The name from the action is used as the menu item label. Before setting this action, clients should turn on the column selector using setColumnSelectorAvailable.

getColumnSelectorActions

public static javax.swing.Action[] getColumnSelectorActions(javax.swing.JTable table)

Returns the additional ColumnSelector actions if it has been set before.

setNoEntryInstructionText

public static void setNoEntryInstructionText(javax.swing.JTable table,
                                             java.lang.String text)

Sets the instruction text on the firt row of the table when there is no entry in the table. The instruction text must be in the form: "No object Name".

getNoEntryInstructionText

public static java.lang.String getNoEntryInstructionText(javax.swing.JTable table)

Returns the instruction text of the table when there is no entry in the table. This instruction text will be displayed on the first row of the table.

installGenericTableRenderer

public static void installGenericTableRenderer(javax.swing.JTable table)

Set GenericTableCellRenderer for objects, numbers, doubles, dates, booleans, and icons column class type of this table. The current default TableCellRenderer for these column class types will be wrapped with GenericTableCellRenderer. GenericTableCellRenderer provided features like sort column highlighting and alignment. This also sets the table header column renderer to GenericTableHeaderRenderer. Please refer to GenericTableCellRenderer and GenericTableHeaderRenderer for more information.

setResizeColumnOnDoubleClick

public static void setResizeColumnOnDoubleClick(javax.swing.JTable table,
                                                boolean isOn)

Set whether the user can resize columns in this table by double clicking the resize divider between two columns. This property works best if the column auto-resizing behavior is turned off in the table. You can turn it off using:

   table.setAutoResizeMode( JTable.AUTO_RESIZE_OFF );
 

Parameters:

isOn - if true, the user can resize columns

isResizeColumnOnDoubleClick

public static boolean isResizeColumnOnDoubleClick(javax.swing.JTable table)

Get whether the user can resize columns in this table by double clicking the resize divider between two columns.

sizeTableToContents

public static void sizeTableToContents(javax.swing.JTable table)

See Also:

sizeTableToContents(JTable, Object[])

sizeTableToContents

public static void sizeTableToContents(javax.swing.JTable table,
                                       java.lang.Object[] prototypeValues)

Utility method that will set the preferred size of all columns in this table so that they are just big enough to display their contents. This method works best when the column auto-resizing behavior is turned off. You can turn it off using:

   table.setAutoResizeMode( JTable.AUTO_RESIZE_OFF );
 

sizeColumnToContents

public static void sizeColumnToContents(javax.swing.JTable table,
                                        int col,
                                        int sampleSize)

Size one column of a table to be just large enough to fully display its current contents.

getCellWidth

public static int getCellWidth(javax.swing.JTable table,
                               java.lang.Object value,
                               int row,
                               int col)

Return the preferred size of a table cell

sizeColumnToMaximumWidth

public static void sizeColumnToMaximumWidth(javax.swing.JTable table,
                                            int x)

Size the column in the table at location x to the maximum width of all cells in that column.

sizeColumnToContents

public static int sizeColumnToContents(javax.swing.JTable table,
                                       int col,
                                       boolean sortCol,
                                       int sampleSize,
                                       java.lang.Object[] prototypeValues)

Size one column of a table to be just large enough to fully display its current contents.

setVisibleRows

public static void setVisibleRows(javax.swing.JTable table,
                                  javax.swing.JScrollPane sp,
                                  int rows)

Set the preferred size of the scrollpane to the desired number of visible table rows. If the table is current visible this also revalidates the scrollpane.

setPreferredVisibleRowCount

public static void setPreferredVisibleRowCount(javax.swing.JTable table,
                                               int visibleRowCount)

Sets the visibleRowCount property. This sets the preferred number of rows to display without requiring scrolling. Setting this property affects the return value of the JTable.getPreferredScrollableViewportSize method, which is used to calculate the preferred size of an enclosing viewport. See that method's documentation for more details.

The default value of this property is -1, indicating null PreferredScrollableViewportSize.

Calling this method with a negative value will set the PreferredScrollableViewportSize to null.

Parameters:

visibleRowCount - an integer specifying the preferred number of rows to display without requiring scrolling

See Also:

getPreferredVisibleRowCount(javax.swing.JTable)

getPreferredVisibleRowCount

public static int getPreferredVisibleRowCount(javax.swing.JTable table)

Returns the value of the visibleRowCount property. See the documentation for setPreferredVisibleRowCount(javax.swing.JTable, int) for details on how to interpret this value.

Returns:

the value of the visibleRowCount property.

See Also:

setPreferredVisibleRowCount(javax.swing.JTable, int)

getDefaultRowHeight

public static int getDefaultRowHeight()

Returns the default row height for the table cell recommended by Oracle UI guidelines. The default value is 19.

setColumnHeaderSelectionEnabled

public static void setColumnHeaderSelectionEnabled(javax.swing.JTable table,
                                                   boolean select)

Add column header selection support for the table. Enabling this property will only select the table column when clicked on corresponding table header. To paint the selected column with a selection highlight background color, clients should set table's column renderer to GenericTableHeaderRenderer.

isColumnHeaderSelectionEnabled

public static boolean isColumnHeaderSelectionEnabled(javax.swing.JTable table)

Returns whether column header selection is supported for the table.

setSelectAllEnabled

public static void setSelectAllEnabled(javax.swing.JTable table,
                                       javax.swing.JScrollPane pane,
                                       boolean enable)

Enables whether the user can click on upper left corner to select all cells in the table by clicking on it.

isSelectAllEnabled

public static boolean isSelectAllEnabled(javax.swing.JTable table)

Returns whether selectAll feature is enabled for the table.

setRolloverHighlightingEnabled

public static void setRolloverHighlightingEnabled(javax.swing.JTable table,
                                                  boolean enable)

Set rollover highlighting enabled/disabled on the table. This method should be called after setting any all the renders on the table. This will not work if the renders are changed after this call.

isRolloverHighlightingEnabled

public static boolean isRolloverHighlightingEnabled(javax.swing.JTable table)

Returns whether rollover highlighting is enabled/disabled on the table.

installTableTransferHandler

public static void installTableTransferHandler(javax.swing.JTable table,
                                               boolean supportsPaste)

Installs TableTransferHandler that supports copy and paste

getTruncatedCellValue

public static java.lang.String getTruncatedCellValue(javax.swing.JTable table,
                                                     int row,
                                                     int col)

Figure out if the renderer has been truncated by the column width and if so return the complete value of the cell.

stopCellEditing

public static void stopCellEditing(javax.swing.JTable table)

Utility method to stop cell editing in the table.

getSortIconUp

public static javax.swing.Icon getSortIconUp()

Returns the column sort icon when the sort order is ascending to be displayed on the table header.

getSortIconDown

public static javax.swing.Icon getSortIconDown()

Returns the column sort icon when the sort order is descending to be displayed on the table header.