java.sun.com > Guidelines Home Page > Java Look and Feel Design Guidelines > Part III: The Components of the Java Foundation Classes > 12: Selectable Lists, Tables, and Tree Components > Tables

Tables

A table organizes related information into a series of rows and columns. Each field in the table is called a "cell." By default, a cell contains a text field, but you can replace it with graphics and other components, such as a checkbox or combo box. The cell with keyboard focus has an inner border, which is drawn in the primary 1 color in the application's color theme.

The following figure illustrates the use of a table to display the records of employees in a company database. The cell with the value 377 is selected and has keyboard focus, but cannot be edited. The table lets you change an employee's project, but not the first or last name or employee ID.

The background color of a cell depends on:

• Whether the cell is selected
• Whether the cell is editable or noneditable
• The background color of the table

The following table shows how a cell gets its background color.

Table 10   Background Color of Table Cells 

Type of Cell	Background Color	Example
An unselected cell (editable)	The background color of the table, which is white by default.
An unselected cell (noneditable)	The secondary 3 color, which is gray in the default color scheme.
A selected cell that is editable and currently has keyboard focus	White. The inner border is drawn in the primary 1 color to indicate that the cell has keyboard focus. (For information on color themes in the Java look and feel, see Colors.)
A selected cell that is noneditable and currently has keyboard focus	The primary 3 color, which is light blue in the default color theme. The inner border is primary 1.
Any other selected cell	The primary 3 color, which is light blue in the default color theme.

Users can select a cell and edit its contents if the component in that cell supports editing. For example, if a cell contains a text field, users can type, cut, copy, and paste text. For more information on editing text in a table, see Editable Text Fields.

Users can press Tab to advance to the next cell and select its contents. For the keyboard operations that are appropriate for tables, see Table 27.

 The gray background of noneditable cells is not a default JFC behavior, but it is a recommended practice. You must explicitly specify the color.

Table Appearance

The JFC provides several options that enable you to define the appearance of your table. You can turn on the display of horizontal and vertical lines that define the table cells, as shown in Figure 188. You can set the horizontal and vertical padding around the content of a cell. You can also set the width of the columns.

 When resizing a table vertically, make sure that it always displays a whole number of rows.

Table Scrolling

You can provide scrolling of your table by placing the table inside a scroll pane. A table has column headers only when it is in a scroll pane. For information on scrolling, see Scroll Panes.

Column Reordering

You can enable users to rearrange the columns in the table. When users drag the column header to the right or left, the entire column moves. Releasing the mouse button places the column at the new location.

The following figure shows the Last Name column being dragged to the right. In this case, the column is selected (although users can also drag an unselected column).

Column Resizing

You can enable users to resize the columns in a table. Users drag the border of the column header to the right to make the column wider and to the left to make the column narrower. When users resize a column, you must decide whether to change the width of the entire table or adjust the other columns so that the overall width is preserved. The JFC-supplied resize options are described in the following table. (Numbers represent relative widths.)

Table 11   Table Resize Options 

The original table. The double arrow shows the east resize pointer before the columns are resized.
Resize next Resizes the columns on either side of the border being moved. One column becomes bigger, while the other becomes smaller.
Resize subsequent Resizes the column whose border was moved and all columns to its right. This option is the default option.
Resize last Resizes the column whose border was moved and the last (rightmost) column.
Resize all Resizes all other columns, distributing the remaining space proportionately.
Resize off Resizes the column whose border was moved and makes the table wider or narrower to adjust the space added or removed from the column. This is the only option that changes the overall width of the table.

 Use either the Resize Next or Resize Off options (described in Table 11) to avoid unexpected results in your tables.

Row Sorting

You can give users the ability to sort the rows in a table by clicking the column headers. An email application, which displays a list of messages in a table, is well suited for row sorting. As shown in the following figure, users can sort the messages by date, sender, or subject. The header of the From column appears in bold to indicate that the messages are currently sorted alphabetically by sender.

 Put column header text in bold to indicate the table column that currently determines the sort order. If something happens to invalidate the sort order, remove the visual indicator.

 If your application has a menu bar, provide row sorting as a set of menu items as well (for example, include "Sort by Sender" in the View menu). This practice makes sorting available through the keyboard.

 Row sorting is not included with the table component. However, the JFC contains sample code that can be used to implement row sorting. See The Java Tutorial (described in Java) for more information.

Selection Models for Tables

When designing a table, you must decide which objects (cells, rows, or columns) users can select. The JFC provides 24 models for selecting objects in tables, but they are not all distinct.

 The following nine selection models are recommended for use in the Java look and feel:

• No selection
• Single cell
• Single range of cells
• Single row
• Single range of rows
• Multiple ranges of rows
• Single column
• Single range of columns
• Multiple ranges of columns

No Selection

You can turn off selection in a table. Nothing is selected when users click in a cell.

SIngle Cell

You can enable users to select a cell by clicking it. The cell gets keyboard focus, which is indicated by an inner border. Any previous selection is deselected.

In the following figure, the cell containing 377 is selected and has keyboard focus. The cell cannot be edited, as indicated by the primary 3 background color.

Range of Cells

You can enable users to select a single cell or a rectangular range of cells. Users select a cell by clicking it. That cell gets keyboard focus and becomes the anchor point of the selection. Users extend the selection by moving the pointer to a new cell and Shift-clicking. Users can also select a range of cells by dragging through the range.

In the following figure, the user has selected the range by clicking Sophia and then Shift-clicking 1273. The cell containing Sophia is noneditable, as indicated by its blue background.

In range selection, the selection always extends from the cell with the anchor point to the cell where the user Shift-clicked. If users move the pointer within the selection and Shift-click, the selection becomes smaller. For example, if the user Shift-clicks Stewart in the preceding figure, the selection is reduced to four cells (Sophia, Amann, Samuel, and Stewart).

Single Row

You can enable users to select an entire row by clicking any cell in the row. The clicked cell gets keyboard focus, which is indicated by an inner border. Any previous selection is deselected.

In the following figure, the user has clicked the cell containing 811. This cell is not editable, as indicated by its background color.

Single Range of Rows

You can enable users to select one row or a range of rows. Users select a row by clicking any cell in the row. The cell that has been clicked gets keyboard focus and becomes the anchor point of the selection. Users extend the selection by moving the pointer to a new row and Shift-clicking. Users can also select a range of rows by dragging through the range.

In the following figure, the user has clicked Krakatoa and then Shift-clicked the FireDog in Mary Dole's row. The cell containing Amann is editable, as indicated by its white background.

In range selection, the selection always extends from the row with the anchor point to the row where the user has Shift-clicked. If users Shift-click within an existing selection, the selection becomes smaller. For example, if the user Shift-clicks Butler in the preceding figure, the selection is reduced to the two rows containing Krakatoa and Butler.

Multiple Ranges of Rows

You can enable users to select a single row, a range of rows, or multiple row ranges (also known as "discontinuous," "discontiguous," or "disjoint" ranges). Users select a single row by clicking any cell in the row and extend the selection by Shift-clicking. To start another range, users Control-click any cell in a row. The cell gets keyboard focus and becomes the anchor point of the new range. The selection of the row toggles as follows:

• If the row is not already selected, it is selected. A subsequent Shift-click selects all rows from the anchor point to the row where the user has Shift-clicked.
• If the row is within an existing selection, the row is deselected. A subsequent Shift-click deselects all rows from the anchor point to the row where the user has Shift-clicked.

Users can also select another range by dragging through the range while holding down the Control key.

In Figure 195, the user has selected the first range by clicking Winter and then Shift-clicking Amann. The user has created another range by Control-clicking Mary and then Shift-clicking Roscoe. The cell containing Mary has keyboard focus and is noneditable.

Click here to view the corresponding code for Figure 195 (also available on the book's companion CD-ROM).

Multiple-range selection is well suited for an email application that uses a table to display message headers, as shown in Figure 190. Users can select one or more message headers (especially useful for deleting, moving, or forwarding messages).

Single Column

You can enable users to select an entire column by clicking any cell in the column. The cell that was clicked gets keyboard focus, which is indicated by an inner border. Any previous selection is deselected.

In the following figure, the user has clicked Krakatoa in the Project column. The white background indicates that the cell can be edited.

Single Range of Columns

You can enable users to select one column or a range of columns. Users select a column by clicking any cell in the column. The cell that was clicked gets keyboard focus and becomes the anchor point of the selection. Users extend the selection by moving the pointer to a new column and Shift-clicking. Users can also select a range of columns by dragging through the range.

In the following figure, the user has clicked 1273 and then Shift-clicked Amann. The cell containing 1273 cannot be edited, as indicated by its background color.

In range selection, the selection always extends from the column with the anchor point to the column where the user has Shift-clicked. If users Shift-click within an existing selection, the selection becomes smaller.

Multiple Ranges of Columns

You can enable users to select a single column, a range of columns, or multiple-column ranges (also known as "discontinuous," "discontiguous," or "disjoint" ranges). Users select a single column by clicking any cell in the column and extend the selection by Shift-clicking. To start another range, users Control-click any cell in the column. The cell gets keyboard focus and becomes the anchor point of the range. The selection of the column toggles as follows:

• If the column is not already selected, it is selected. A subsequent Shift-click selects all columns from the anchor point to the column where the user Shift-clicked.
• If the column is within an existing selection, the column is deselected. A subsequent Shift-click deselects all columns from the anchor point to the column where the user Shift-clicked.

Users can also select or deselect another range by dragging through the range while holding down the Control key.

In the following figure, the user has clicked Peter and then Shift-clicked Amann. The user has selected another range by Control-clicking Krakatoa, which has keyboard focus and can be edited, as indicated by its white background.

 Give your users as much flexibility in your selection scheme as makes sense for your application. Enable selection of a range or multiple ranges if you can.

Java Look and Feel Design Guidelines, second edition. Copyright 2001. Sun Microsystems, Inc. All Rights Reserved.