Using the JFC/Swing Packages

How to Use Combo Boxes

An editable JComboBox is a combination button, drop-down list, and a text field. The user can type in a value or choose the value from a list. An editable combo box saves data-entry time by providing short-cuts to commonly entered values.

An uneditable combo box disables typing but still allows the user to select a value from the list. This provides a space-conserving alternative to a group of radio buttons or a list. See Using an Uneditable Combo Box for an example.

Here's a picture of a demo application that uses an editable combo box to enter a pattern with which to format dates.

Try this: Compile and run the example: ComboBoxDemo.java. Enter a new pattern by choosing one from the drop-down list. The program reformats the current date and time. Enter a new pattern by typing one in and entering return. Again the program reformats the current date and time.

Below is the code from ComboBoxDemo.java that creates and sets up the combo box:

String[] patternExamples = {
	 "dd MMMMM yyyy",
	 "dd.MM.yy",
	 "MM/dd/yy",
	 "yyyy.MM.dd G 'at' hh:mm:ss z",
	 "EEE, MMM d, ''yy",
	 "h:mm a",
	 "H:mm:ss:SSS",
	 "K:mm a,z",
	 "yyyy.MMMMM.dd GGG hh:mm aaa"
};

currentPattern = patternExamples[0];
. . .
JComboBox patternList = new JComboBox(patternExamples);
patternList.setEditable(true);
patternList.setSelectedIndex(0);
patternList.setAlignmentX(Component.LEFT_ALIGNMENT);
PatternListener patternListener = new PatternListener();
patternList.addActionListener(patternListener);

This program provides the values for the combo box's drop-down list with an array of strings. However, the values in the list can be any Object, in which case the Object's toString method provides the text to display. To put an image or other non-text value in the combo box's list, you must provide a custom cell renderer with setRenderer.

Notice that the code explicitly turns on editing to allow the user to type values in by hand. This is necessary because, by default, a combo box is not editable. This particular example allows editing on the combo box because its list does not provide all possible date formatting patterns.

The code also registers an action listener with the combo box. When a user selects an item from the combo box, this method is called:

public void actionPerformed(ActionEvent e) {
    JComboBox cb = (JComboBox)e.getSource();
    String newSelection = (String)cb.getSelectedItem();
    currentPattern = newSelection;
    reformat();
}

The method calls getSelectedItem to get the new pattern chosen by the user, and uses that pattern to reformat the current date and time.

---

Warning: A combo box is a compound component: it is comprised of a button, a pull-down menu, and when editable, a text field. The combo box fires high-level events such as action events. Its subcomponents fire low-level events such as mouse, key, and focus events. Typically, for compound components such as the combo box, you should provide listeners for high-level events because the low-level events and the subcomponent that fires them are system-dependent. For information about events, including a discussion about high- and low-level events, refer to: .

---

Using an Uneditable Combo Box

Here's a picture of an application that uses an uneditable combo box to let the user choose a pet picture from a list:

Try this: Compile and run the program: ComboBoxDemo2.java. You will also need 5 image files: Bird.gif, Cat.gif, Dog.gif, Rabbit.gif, and Pig.gif. Choose a pet from the drop-down list to view its picture. How to Use Radio Buttons provides a version of this program, RadioButtonDemo.java, that uses a group of radio buttons instead of a combo box. Compile and run that program. Compare the source code and operation of the two programs.

Below is the code from ComboBoxDemo2.java that creates and sets up the combo box:

...
//in the ComboBoxDemo2 constructor
String[] petStrings = { "Bird",
                        "Cat",
                        "Dog",
                        "Rabbit",
                        "Pig" };

// Create the combo box, turn off editing, and select the first one
JComboBox petList = new JComboBox(petStrings);
petList.setSelectedIndex(0);

This code is similar to the code from ComboBoxDemo. However, this program leaves the combo box uneditable (the default).

Use an uneditable combo box instead of a group of radio buttons to display one-of-many choices in these situations:

• when space is limited
• when the number of choices is large
• when the list is computed at run-time

The Combo Box API

The following tables list the commonly used JComboBox constructors and methods. Other methods you're likely to call are defined by the JComponent and Component classes and include [PENDING: anything in particular for JComboBox?]. [Link to JComponent and Component discussions.]

The API for using combo boxes falls into two categories:

• Setting or Getting the Items in the Combo Boxes's List
• Customizing the Combo Box's Operation

Setting or Getting the Items in the Combo Boxes's List

Method	Purpose
JComboBox(ComboBoxModel) JComboBox(Object[]) JComboBox(Vector)	Create a combo box with a pre-determined list.
void addItem(Object) void insertItemAt(Object, int)	Add or insert an item in the list.
Object getItemAt(int) Object getSelectedItem()	Get an item from the list.
void removeAllItems() void removeItemAt(int) void removeItem(Object)	Remove one or more items from the list.
int getItemCount()	Get the number of items in the list.
void setModel(ComboBoxModel) ComboBoxModel getModel()	Set or get the data model that provides the items in the list.

Customizing the Combo Box's Operation

Method	Purpose
void setEditabe(boolean) boolean isEditable()	Set or get whether the user can type in the combo box.
void setRenderer(ListCellRenderer) ListCellRenderer getRenderer()	Set or get the object responsible for rendering the selected item in the combo box. Used when the combo box is uneditable.
void setEditor(ComboBoxEditor) ComboBoxEditor getEditor()	Set or get the object responsible for painting and editing the selected item in the combo box. Used only when the combo box is editable.

Examples that Use JComboBox

This table shows the examples that use JComboBox and where those examples are described.

Example	Where Described	Notes
ComboBoxDemo.java	This page.	An editable combo box.
ComboBoxDemo2.java	This page.	An uneditable combo box.
LayeredPaneDemo.java	How to Use Layered Panes	An uneditable combo box.
TableRenderDemo.java	How to Use Tables	Shows how to use a combo box as a table cell editor.

Using the JFC/Swing Packages