Java TM Look and Feel Design Guidelines: Advanced Topics > Part II: Special Topics > 5: Idioms > Idioms for Text Fields and Lists   Previous Next Contents/Index/Search


Idioms for Text Fields and Lists

You can use the following idioms to help users work with text fields and lists:

  • Browse
  • Key-Search
  • Add-and-Remove

Browse Idiom

The Browse idiom enables users to specify an object--typically, a file, directory, or web page. This idiom consists of a label, an editable text field, and a command button, whose text begins with the word "Browse," as shown in Figure 57.

Figure 57   Browse Idiom


In the Browse idiom, users can enter data into the text field by either:

  • Typing in the text field
  • Clicking the command button to choose text from a list in a dialog box

Clicking the command button opens a dialog box that enables users to navigate through a hierarchy of locations and then choose a file, directory, web page, or other object. Typically, choosing an object causes the text field to display the full path to that object.

 Use the Browse idiom to enable users to specify a file, directory, web address, or other item in a very large set.

 When using the Browse idiom for choosing a file, directory, or web address, label the idiom's command button "Browse," and use "B" as its mnemonic unless that letter is a mnemonic for different button or command.

 In a window with more than one copy of the Browse idiom, assign different button text and a different mnemonic to each copy's command button. For example, you could make one button's text Browse For T emplate and another button's text Browse For M essage Folder Even if you cannot make each button's text different from the others, use a different mnemonic for each button.

Key-Search Idiom

You can help users find list items faster in your application by using the Key-Search idiom in lists, combo boxes, and trees. Figure 58 shows an example use of the Key-Search idiom.

The Key-Search idiom enables users to find a list item by typing its first letter (called the "search key" or "key"). The Key-Search idiom is case insensitive, and it works on any list of text items, even an unsorted list.

To start a key search, a user types any printable character while keyboard focus is in a list. In response, the application deselects the currently selected list item and then scrolls down to the next list item that begins with that character, highlighting that item. For example, if the user types the letter v , the key search highlights the next item that begins with V or v , as shown on the left in Figure 58.

Figure 58   Two Successive Key Searches on the Letter "v"  


To find each subsequent list item that begins with V or v , the user types the letter v again. The right side of Figure 58 shows the result of typing v after the first search, shown on the left. Successive searches on the same key cause the application to loop through the list until the user stops searching.

If a search key does not match the first character of any list item, the application should alert the user--for example, by causing the user's system to beep--but should leave the current highlighting and selection unchanged.

 Use the Key-Search idiom in any list that might become long enough to require vertical scrolling.

   As of version 1.4 of the Java 2 SDK, the key-search feature is part of the standard behavior for components that extend the JList, JComboBox, or JTree class.

Add-and-Remove Idiom

To enable users to choose a subset from a large list of objects, you can provide the Add-and-Remove idiom . This idiom consists of two lists separated by a command button row, as shown in Figure 59.

Figure 59   Add-and-Remove Idiom


The list on the left, called the original list, contains a set of objects that users can add to the list on the right--the chosen list. The command buttons enable users to control which items appear in the chosen list. In Figure 59:

  • The original list is labeled "People to Choose From."
  • The chosen list is labeled "Project Assignments."

Optionally, the chosen list can be a table, as in Figure 59. The table's leftmost column, called the main column, displays items that come from the original list. In Figure 59, the Name column is the main column.

The chosen list can have one or more supplementary columns to provide more information about each item in the main column. In Figure 59, the Project column is the only supplementary column.

Supplementary columns can be noneditable or editable:

  • Noneditable supplementary columns display information about chosen-list items.
  • Editable supplementary columns enable users to set parameters for this table's use of each chosen-list item.

 Provide the Add-and-Remove idiom if users need to choose a few objects from a long list.

 In the Add-and-Remove idiom, make the chosen list a table only if the supplementary columns hold either:

  • Noneditable data
  • User-input fields for parameters regarding this table's use of each chosen-list item

 In the Add-and-Remove idiom, if the chosen list is a table, use a row- selection model. If the table is editable, use internal editing. (For more information, see Using Row Selection Models and Editing Row-Selection Tables.)

Commands in the Add-and-Remove Idiom

Table 12 describes the command buttons that you can include in the Add-and-Remove idiom.


Button Text Mnemonic Description



Adds items to the chosen list. The Add command copies all selected items from the original list and adds them to the chosen list--at the end or, if the chosen list is sorted, in their correct positions. If the items must be unique in the chosen list, the Add command then deletes from the original list all copied items. Finally, the Add command selects the copied items in the chosen list and deselects any previously selected items in the original list. The Add command is available only while one or more items are selected in the original list. Another way to activate the Add command is to double-click an item in the original list, thereby selecting it and immediately adding it to the chosen list.

Add A ll


(Optional) Moves or copies all items from the original list to the chosen list and then selects them in the chosen list. The Add All command is available only while the original list is not empty. You should provide the Add All command only if your users need it.



Removes items from the chosen list. The Remove command removes the selected items from the chosen list, adds them to the original list (at the end or, preferably, at their previous positions) and, finally, selects the items in the original list, deselecting the chosen list. Removing an item from the chosen list has no effect on the original list if that item is already in the original list. The Remove command is available only while one or more items are selected in the chosen list.

Remo ve All


(Optional) Moves all items from the chosen list to the original list. The Remove All command is available only while the chosen list is not empty.

Move Up


(Optional) Moves the selected items one row up in the chosen list. If a user applies the Move Up command to a selection containing nonadjacent items, the command works as if the user performed it on each of the items separately. As a result, the items retain their positions relative to one another.

Move Down


(Optional) Moves the selected items one row down in the chosen list.

 In the Add-and-Remove idiom, ensure that the command buttons behave as described in Table 12.

 In the Add-and-Remove idiom, provide the Add All command only if you also provide the Remove All command. (You can provide the Remove All command without also providing the Add All command.)

 Assign the mnemonics in Table 12 to the command buttons of the Add- and-Remove idiom.

 When adding list items in the Add-and-Remove idiom, display at least the first newly added item, by scrolling the list if necessary.

Button Graphics in the Add-and-Remove Idiom

In the Add-and-Remove idiom, you can label command buttons with a graphic and text, or with just a graphic. The correct choice depends on the type of users and the amount of available space.

 In the Add-and-Remove idiom, label the command buttons with a graphic and text--especially if your application's users are inexperienced with computers. Label the command buttons with just a graphic only if there is no space for text and your application's users are experienced.

 In the Add-and-Remove idiom, provide tool tips for the command buttons if the buttons are labeled with just a graphic.

Layout of the Add-and-Remove Idiom

Typically, the command buttons of the Add-and-Remove idiom are between the original list and the chosen list. The buttons are spaced as shown in Figure 60. Measurements in the figure are in pixels.

Figure 60   Preferred Layout of the Add-and-Remove Idiom


In windows without enough vertical space for the typical layout, you can lay out the Add-and-Remove Idiom as shown in Figure 61. In the figure, the Move Up and Move Down buttons are to the right of the chosen list and apply only to that list.

Figure 61   Layout of the Add-and-Remove Idiom With Limited Vertical Space


 In the Add-and-Remove idiom, arrange and order the command buttons as shown in Figure 60. In windows without enough vertical space, use the layout shown in Figure 61.

 In the Add-and-Remove idiom, make the vertical space for the original list at least as long as the column of command buttons, as shown in Figure 61. Provide the same amount of vertical space for the chosen list as for the original list.

Java Look and Feel Design Guidelines: Advanced Topics.
Copyright 2001. Sun Microsystems, Inc. All Rights Reserved.
Previous Next Contents/Index/Search
Table 12   Command Buttons for the Add-and-Remove Idiom 
Left Curve
Java SDKs and Tools
Right Curve
Left Curve
Java Resources
Right Curve
Java 8 banner (182)