javax.swing

Class JComboBox

public class JComboBox extends JComponent implements ItemSelectable, ListDataListener, ActionListener, Accessible

A component that allows a user to select any item in its list and displays the selected item to the user. JComboBox also can show/hide a popup menu containing its list of item whenever the mouse is pressed over it.

Nested Class Summary
protected class	JComboBox.AccessibleJComboBox Accessibility support for `JComboBox`.
static interface	JComboBox.KeySelectionManager Classes implementing this interface are responsible for matching key characters typed by the user with combo box's items.

Field Summary
protected String	actionCommand This actionCommand is used in ActionEvent that is fired to JComboBox's ActionListeneres.
protected ComboBoxModel	dataModel Data model used by JComboBox to keep track of its list data and currently selected element in the list.
protected ComboBoxEditor	editor Editor that is responsible for editing an object in a combo box list.
protected boolean	isEditable This field indicates if textfield of this JComboBox is editable or not.
protected JComboBox.KeySelectionManager	keySelectionManager keySelectionManager
protected boolean	lightWeightPopupEnabled This property indicates if heavyweight popup or lightweight popup will be used to diplay JComboBox's elements.
protected int	maximumRowCount Number of rows that will be visible in the JComboBox's popup.
protected ListCellRenderer	renderer Renderer renders(paints) every object in the combo box list in its associated list cell.
protected Object	selectedItemReminder This field is reference to the current selection of the combo box.

Constructor Summary
	JComboBox(ComboBoxModel model) Constructs JComboBox object with specified data model for it.
	JComboBox(Object[] itemArray) Constructs JComboBox with specified list of items.
	JComboBox(Vector<?> itemVector) Constructs JComboBox object with specified list of items.
	JComboBox() Constructor.

Method Summary
void	actionPerformed(ActionEvent e) This method handles actionEvents fired by the ComboBoxEditor.
void	addActionListener(ActionListener listener) This methods adds specified ActionListener to this JComboBox.
void	addItem(Object element) This method adds given element to this JComboBox.
void	addItemListener(ItemListener listener) This method registers given ItemListener with this JComboBox
void	addPopupMenuListener(PopupMenuListener listener) Adds PopupMenuListener to combo box to listen to the events fired by the combo box's popup menu containing its list of items
void	configureEditor(ComboBoxEditor anEditor, Object anItem) This method initializes specified ComboBoxEditor to display given item.
protected void	configurePropertiesFromAction(Action a) Configure properties of the JComboBox by reading properties of specified action.
void	contentsChanged(ListDataEvent event) The part of implementation of ListDataListener interface.
protected PropertyChangeListener	createActionPropertyChangeListener(Action action) Creates PropertyChangeListener to listen for the changes in comboBox's action properties.
protected JComboBox.KeySelectionManager	createDefaultKeySelectionManager() createDefaultKeySelectionManager
protected void	fireActionEvent() This method fires ActionEvent to this JComboBox's registered ActionListeners.
protected void	fireItemStateChanged(ItemEvent e) This method fires ItemEvent to this JComboBox's registered ItemListeners.
void	firePopupMenuCanceled() Fires a popupMenuCanceled() event to all `PopupMenuListeners`.
void	firePopupMenuWillBecomeInvisible() Fires a popupMenuWillBecomeInvisible() event to all `PopupMenuListeners`.
void	firePopupMenuWillBecomeVisible() Fires a popupMenuWillBecomeVisible() event to all `PopupMenuListeners`.
AccessibleContext	getAccessibleContext() Returns the object that provides accessibility features for this `JComboBox` component.
Action	getAction() This method returns Action that is invoked when selected item is changed in the JComboBox.
String	getActionCommand() Returns actionCommand associated with the ActionEvent fired by the JComboBox to its registered ActionListeners.
ActionListener[]	getActionListeners() This method returns array of ActionListeners that are registered with this JComboBox.
ComboBoxEditor	getEditor() Returns editor component that is responsible for displaying/editing selected item in the combo box.
Object	getItemAt(int index) Returns elements located in the combo box at the given index.
int	getItemCount() This method returns number of elements in this JComboBox
ItemListener[]	getItemListeners() This method returns array of ItemListeners that are registered with this JComboBox.
JComboBox.KeySelectionManager	getKeySelectionManager() getKeySelectionManager
int	getMaximumRowCount() This method returns number of rows visible in the JComboBox's list of items.
ComboBoxModel	getModel() This method returns data model for this comboBox.
PopupMenuListener[]	getPopupMenuListeners() Returns array of PopupMenuListeners that are registered with combo box.
Object	getPrototypeDisplayValue() Returns an object that is used as the display value when calculating the preferred size for the combo box.
ListCellRenderer	getRenderer() This method returns renderer responsible for rendering selected item in the combo box
int	getSelectedIndex() Returns index of the item that is currently selected in the combo box.
Object	getSelectedItem() Returns currently selected item in the combo box.
Object[]	getSelectedObjects() Returns Object array of size 1 containing currently selected element in the JComboBox.
ComboBoxUI	getUI() This method returns the UI used to display the JComboBox.
String	getUIClassID() This method returns the String identifier for the UI class to the used with the JComboBox.
void	hidePopup() This method hides popup containing list of combo box's items
void	insertItemAt(Object element, int index) Inserts given element at the specified index to this JComboBox.
protected void	installAncestorListener()
void	intervalAdded(ListDataEvent event) The part of implementation of ListDataListener interface.
void	intervalRemoved(ListDataEvent event) The part of implementation of ListDataListener interface.
boolean	isEditable() This method returns true JComboBox is editable and false otherwise
boolean	isLightWeightPopupEnabled() This method returns whether popup menu that is used to display list of combo box's item is lightWeight or not.
boolean	isPopupVisible() Checks if popup is currently visible on the screen.
protected String	paramString() Returns an implementation-dependent string describing the attributes of this `JComboBox`.
void	processKeyEvent(KeyEvent e) This method is fired whenever a key is pressed with the combo box in focus
void	removeActionListener(ActionListener listener) This method removes specified ActionListener from this JComboBox.
void	removeAllItems() This method removes all elements from this JComboBox.
void	removeItem(Object element) This method removes given element from this JComboBox.
void	removeItemAt(int index) This method remove element location in the specified index in the JComboBox.
void	removeItemListener(ItemListener listener) This method unregisters given ItemListener from this JComboBox
void	removePopupMenuListener(PopupMenuListener listener) Removes PopupMenuListener to combo box to listen to the events fired by the combo box's popup menu containing its list of items
protected void	selectedItemChanged() This method is invoked whenever selected item changes in the combo box's data model.
boolean	selectWithKeyChar(char keyChar) This method selects item in this combo box that matches specified specified keyChar and returns true if such item is found.
void	setAction(Action a) setAction
void	setActionCommand(String aCommand) This method sets actionCommand to the specified string.
void	setEditable(boolean editable) This method sets editability of the combo box.
void	setEditor(ComboBoxEditor newEditor) Sets editor for this JComboBox
void	setEnabled(boolean enabled) This method disables or enables JComboBox.
void	setKeySelectionManager(JComboBox.KeySelectionManager aManager) setKeySelectionManager
void	setLightWeightPopupEnabled(boolean enabled) This method sets JComboBox's popup to be either lightweight or heavyweight.
void	setMaximumRowCount(int rowCount) Sets number of rows that should be visible in this JComboBox's popup.
void	setModel(ComboBoxModel newDataModel) Set the data model for this JComboBox.
void	setPopupVisible(boolean visible) This method either displayes or hides the popup containing list of combo box's items.
void	setPrototypeDisplayValue(Object value) Sets the object that is assumed to be the displayed item when calculating the preferred size for the combo box.
void	setRenderer(ListCellRenderer aRenderer) This method sets cell renderer for this JComboBox that will be used to paint combo box's items.
void	setSelectedIndex(int index) Forces JComboBox to select component located in the given index in the combo box.
void	setSelectedItem(Object item) Forces combo box to select given item
void	setUI(ComboBoxUI ui) Set the "UI" property of the combo box, which is a look and feel class responsible for handling comboBox's input events and painting it.
void	showPopup() This method displays popup with list of combo box's items on the screen
void	updateUI() This method sets this comboBox's UI to the UIManager's default for the current look and feel.

Field Detail

actionCommand

protected String actionCommand

This actionCommand is used in ActionEvent that is fired to JComboBox's ActionListeneres.

dataModel

protected ComboBoxModel dataModel

Data model used by JComboBox to keep track of its list data and currently selected element in the list.

editor

protected ComboBoxEditor editor

Editor that is responsible for editing an object in a combo box list.

isEditable

protected boolean isEditable

This field indicates if textfield of this JComboBox is editable or not.

keySelectionManager

protected JComboBox.KeySelectionManager keySelectionManager

keySelectionManager

lightWeightPopupEnabled

protected boolean lightWeightPopupEnabled

This property indicates if heavyweight popup or lightweight popup will be used to diplay JComboBox's elements.

maximumRowCount

protected int maximumRowCount

Number of rows that will be visible in the JComboBox's popup.

renderer

protected ListCellRenderer renderer

Renderer renders(paints) every object in the combo box list in its associated list cell. This ListCellRenderer is used only when this JComboBox is uneditable.

selectedItemReminder

protected Object selectedItemReminder

This field is reference to the current selection of the combo box.

Constructor Detail

JComboBox

public JComboBox(ComboBoxModel model)

Constructs JComboBox object with specified data model for it.

Note that the JComboBox will not change the value that is preselected by your ComboBoxModel implementation.

Parameters: model Data model that will be used by this JComboBox to keep track of its list of items.

JComboBox

public JComboBox(Object[] itemArray)

Constructs JComboBox with specified list of items.

Parameters: itemArray array containing list of items for this JComboBox

JComboBox

public JComboBox(Vector<?> itemVector)

Constructs JComboBox object with specified list of items.

Parameters: itemVector vector containing list of items for this JComboBox.

JComboBox

public JComboBox()

Constructor. Creates new empty JComboBox. ComboBox's data model is set to DefaultComboBoxModel.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)

This method handles actionEvents fired by the ComboBoxEditor. It changes this JComboBox's selection to the new value currently in the editor and hides list of combo box items.

Parameters: e the ActionEvent

addActionListener

public void addActionListener(ActionListener listener)

This methods adds specified ActionListener to this JComboBox.

Parameters: listener to add

addItem

public void addItem(Object element)

This method adds given element to this JComboBox.

A RuntimeException is thrown if the data model is not an instance of {@link MutableComboBoxModel}.

Parameters: element element to add

addItemListener

public void addItemListener(ItemListener listener)

This method registers given ItemListener with this JComboBox

Parameters: listener to remove

addPopupMenuListener

public void addPopupMenuListener(PopupMenuListener listener)

Adds PopupMenuListener to combo box to listen to the events fired by the combo box's popup menu containing its list of items

Parameters: listener to add

configureEditor

public void configureEditor(ComboBoxEditor anEditor, Object anItem)

This method initializes specified ComboBoxEditor to display given item.

Parameters: anEditor ComboBoxEditor to initialize anItem Item that should displayed in the specified editor

configurePropertiesFromAction

protected void configurePropertiesFromAction(Action a)

Configure properties of the JComboBox by reading properties of specified action. This method always sets the comboBox's "enabled" property to the value of the Action's "enabled" property.

Parameters: a An Action to configure the combo box from

contentsChanged

public void contentsChanged(ListDataEvent event)

The part of implementation of ListDataListener interface. This method is invoked when contents of the JComboBox's data model changed.

Parameters: event ListDataEvent describing the change

createActionPropertyChangeListener

protected PropertyChangeListener createActionPropertyChangeListener(Action action)

Creates PropertyChangeListener to listen for the changes in comboBox's action properties.

Parameters: action action to listen to for property changes

Returns: a PropertyChangeListener that listens to changes in action properties.

createDefaultKeySelectionManager

protected JComboBox.KeySelectionManager createDefaultKeySelectionManager()

createDefaultKeySelectionManager

Returns: KeySelectionManager

fireActionEvent

protected void fireActionEvent()

This method fires ActionEvent to this JComboBox's registered ActionListeners. This method is invoked when user explicitly changes currently selected item.

fireItemStateChanged

protected void fireItemStateChanged(ItemEvent e)

This method fires ItemEvent to this JComboBox's registered ItemListeners. This method is invoked when currently selected item in this combo box has changed.

Parameters: e the ItemEvent describing the change in the combo box's selection.

firePopupMenuCanceled

public void firePopupMenuCanceled()

Fires a popupMenuCanceled() event to all PopupMenuListeners. Note: This method is intended for use by plaf classes only.

firePopupMenuWillBecomeInvisible

public void firePopupMenuWillBecomeInvisible()

Fires a popupMenuWillBecomeInvisible() event to all PopupMenuListeners. Note: This method is intended for use by plaf classes only.

firePopupMenuWillBecomeVisible

public void firePopupMenuWillBecomeVisible()

Fires a popupMenuWillBecomeVisible() event to all PopupMenuListeners. Note: This method is intended for use by plaf classes only.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns the object that provides accessibility features for this JComboBox component.

Returns: The accessible context (an instance of {@link AccessibleJComboBox}).

getAction

public Action getAction()

This method returns Action that is invoked when selected item is changed in the JComboBox.

Returns: Action

getActionCommand

public String getActionCommand()

Returns actionCommand associated with the ActionEvent fired by the JComboBox to its registered ActionListeners.

Returns: String actionCommand for the ActionEvent

getActionListeners

public ActionListener[] getActionListeners()

This method returns array of ActionListeners that are registered with this JComboBox.

Since: 1.4

getEditor

public ComboBoxEditor getEditor()

Returns editor component that is responsible for displaying/editing selected item in the combo box.

Returns: ComboBoxEditor

getItemAt

public Object getItemAt(int index)

Returns elements located in the combo box at the given index.

Parameters: index index specifying location of the component to return.

Returns: component in the combo box that is located in the given index.

getItemCount

public int getItemCount()

This method returns number of elements in this JComboBox

Returns: int number of elements in this JComboBox

getItemListeners

public ItemListener[] getItemListeners()

This method returns array of ItemListeners that are registered with this JComboBox.

Since: 1.4

getKeySelectionManager

public JComboBox.KeySelectionManager getKeySelectionManager()

getKeySelectionManager

Returns: JComboBox.KeySelectionManager

getMaximumRowCount

public int getMaximumRowCount()

This method returns number of rows visible in the JComboBox's list of items.

Returns: int maximun number of visible rows in the JComboBox's list.

getModel

public ComboBoxModel getModel()

This method returns data model for this comboBox.

Returns: ComboBoxModel containing items for this combo box.

getPopupMenuListeners

public PopupMenuListener[] getPopupMenuListeners()

Returns array of PopupMenuListeners that are registered with combo box.

getPrototypeDisplayValue

public Object getPrototypeDisplayValue()

Returns an object that is used as the display value when calculating the preferred size for the combo box. This value is, of course, never displayed anywhere.

Returns: The prototype display value (possibly null).

Since: 1.4

getRenderer

public ListCellRenderer getRenderer()

This method returns renderer responsible for rendering selected item in the combo box

Returns: ListCellRenderer

getSelectedIndex

public int getSelectedIndex()

Returns index of the item that is currently selected in the combo box. If no item is currently selected, then -1 is returned.

Note: For performance reasons you should minimize invocation of this method. If the data model is not an instance of DefaultComboBoxModel the complexity is O(n) where n is the number of elements in the combo box.

Returns: int Index specifying location of the currently selected item in the combo box or -1 if nothing is selected in the combo box.

getSelectedItem

public Object getSelectedItem()

Returns currently selected item in the combo box. The result may be null to indicate that nothing is currently selected.

Returns: element that is currently selected in this combo box.

getSelectedObjects

public Object[] getSelectedObjects()

Returns Object array of size 1 containing currently selected element in the JComboBox.

Returns: Object[] Object array of size 1 containing currently selected element in the JComboBox.

getUI

public ComboBoxUI getUI()

This method returns the UI used to display the JComboBox.

Returns: The UI used to display the JComboBox.

getUIClassID

public String getUIClassID()

This method returns the String identifier for the UI class to the used with the JComboBox.

Returns: The String identifier for the UI class.

hidePopup

public void hidePopup()

This method hides popup containing list of combo box's items

insertItemAt

public void insertItemAt(Object element, int index)

Inserts given element at the specified index to this JComboBox.

A RuntimeException is thrown if the data model is not an instance of {@link MutableComboBoxModel}.

Parameters: element element to insert index position where to insert the element

installAncestorListener

protected void installAncestorListener()

intervalAdded

public void intervalAdded(ListDataEvent event)

The part of implementation of ListDataListener interface. This method is invoked when some items where added to the JComboBox's data model.

Parameters: event ListDataEvent describing the change

intervalRemoved

public void intervalRemoved(ListDataEvent event)

The part of implementation of ListDataListener interface. This method is invoked when some items where removed from the JComboBox's data model.

Parameters: event ListDataEvent describing the change.

isEditable

public boolean isEditable()

This method returns true JComboBox is editable and false otherwise

Returns: boolean true if JComboBox is editable and false otherwise

isLightWeightPopupEnabled

public boolean isLightWeightPopupEnabled()

This method returns whether popup menu that is used to display list of combo box's item is lightWeight or not.

Returns: boolean true if popup menu is lightweight and false otherwise.

isPopupVisible

public boolean isPopupVisible()

Checks if popup is currently visible on the screen.

Returns: boolean true if popup is visible and false otherwise

paramString

protected String paramString()

Returns an implementation-dependent string describing the attributes of this JComboBox.

Returns: A string describing the attributes of this JComboBox (never null).

processKeyEvent

public void processKeyEvent(KeyEvent e)

This method is fired whenever a key is pressed with the combo box in focus

Parameters: e The KeyEvent indicating which key was pressed.

removeActionListener

public void removeActionListener(ActionListener listener)

This method removes specified ActionListener from this JComboBox.

Parameters: listener ActionListener

removeAllItems

public void removeAllItems()

This method removes all elements from this JComboBox.

A RuntimeException is thrown if the data model is not an instance of {@link MutableComboBoxModel}.

removeItem

public void removeItem(Object element)

This method removes given element from this JComboBox.

A RuntimeException is thrown if the data model is not an instance of {@link MutableComboBoxModel}.

Parameters: element element to remove

removeItemAt

public void removeItemAt(int index)

This method remove element location in the specified index in the JComboBox.

A RuntimeException is thrown if the data model is not an instance of {@link MutableComboBoxModel}.

Parameters: index index specifying position of the element to remove

removeItemListener

public void removeItemListener(ItemListener listener)

This method unregisters given ItemListener from this JComboBox

Parameters: listener to remove

removePopupMenuListener

public void removePopupMenuListener(PopupMenuListener listener)

Removes PopupMenuListener to combo box to listen to the events fired by the combo box's popup menu containing its list of items

Parameters: listener to add

selectedItemChanged

protected void selectedItemChanged()

This method is invoked whenever selected item changes in the combo box's data model. It fires ItemEvent and ActionEvent to all registered ComboBox's ItemListeners and ActionListeners respectively, indicating the change.

selectWithKeyChar

public boolean selectWithKeyChar(char keyChar)

This method selects item in this combo box that matches specified specified keyChar and returns true if such item is found. Otherwise false is returned.

Parameters: keyChar character indicating which item in the combo box should be selected.

Returns: boolean true if item corresponding to the specified keyChar exists in the combo box. Otherwise false is returned.

setAction

public void setAction(Action a)

setAction

Parameters: a action to set

setActionCommand

public void setActionCommand(String aCommand)

This method sets actionCommand to the specified string. ActionEvent fired to this JComboBox registered ActionListeners will contain this actionCommand.

Parameters: aCommand new action command for the JComboBox's ActionEvent

setEditable

public void setEditable(boolean editable)

This method sets editability of the combo box. If combo box is editable the user can choose component from the combo box list by typing component's name in the editor(JTextfield by default). Otherwise if not editable, the user should use the list to choose the component. This method fires PropertyChangeEvents to JComboBox's registered PropertyChangeListeners to indicate that 'editable' property of the JComboBox has changed.

Parameters: editable indicates if the JComboBox's textfield should be editable or not.

setEditor

public void setEditor(ComboBoxEditor newEditor)

Sets editor for this JComboBox

Parameters: newEditor ComboBoxEditor for this JComboBox. This method fires PropertyChangeEvent when 'editor' property is changed.

setEnabled

public void setEnabled(boolean enabled)

This method disables or enables JComboBox. If the JComboBox is enabled, then user is able to make item choice, otherwise if JComboBox is disabled then user is not able to make a selection.

Parameters: enabled if 'enabled' is true then enable JComboBox and disable it

setKeySelectionManager

public void setKeySelectionManager(JComboBox.KeySelectionManager aManager)

setKeySelectionManager

Parameters: aManager

setLightWeightPopupEnabled

public void setLightWeightPopupEnabled(boolean enabled)

This method sets JComboBox's popup to be either lightweight or heavyweight. If 'enabled' is true then lightweight popup is used and heavyweight otherwise. By default lightweight popup is used to display this JComboBox's elements.

Parameters: enabled indicates if lightweight popup or heavyweight popup should be used to display JComboBox's elements.

setMaximumRowCount

public void setMaximumRowCount(int rowCount)

Sets number of rows that should be visible in this JComboBox's popup. If this JComboBox's popup has more elements that maximum number or rows then popup will have a scroll pane to allow users to view other elements.

Parameters: rowCount number of rows that will be visible in JComboBox's popup.

setModel

public void setModel(ComboBoxModel newDataModel)

Set the data model for this JComboBox. This un-registers all listeners associated with the current model, and re-registers them with the new model.

Parameters: newDataModel The new data model for this JComboBox

setPopupVisible

public void setPopupVisible(boolean visible)

This method either displayes or hides the popup containing list of combo box's items.

Parameters: visible show popup if 'visible' is true and hide it otherwise

setPrototypeDisplayValue

public void setPrototypeDisplayValue(Object value)

Sets the object that is assumed to be the displayed item when calculating the preferred size for the combo box. A {@link PropertyChangeEvent} (with the name prototypeDisplayValue) is sent to all registered listeners.

Parameters: value the new value (null permitted).

Since: 1.4

setRenderer

public void setRenderer(ListCellRenderer aRenderer)

This method sets cell renderer for this JComboBox that will be used to paint combo box's items. The Renderer should only be used only when JComboBox is not editable. In the case when JComboBox is editable the editor must be used. This method also fires PropertyChangeEvent when cellRendered for this JComboBox has changed.

Parameters: aRenderer cell renderer that will be used by this JComboBox to paint its elements.

setSelectedIndex

public void setSelectedIndex(int index)

Forces JComboBox to select component located in the given index in the combo box.

If the index is below -1 or exceeds the upper bound an IllegalArgumentException is thrown.

If the index is -1 then no item gets selected.

Parameters: index index specifying location of the component that should be selected.

setSelectedItem

public void setSelectedItem(Object item)

Forces combo box to select given item

Parameters: item element in the combo box to select.

setUI

public void setUI(ComboBoxUI ui)

Set the "UI" property of the combo box, which is a look and feel class responsible for handling comboBox's input events and painting it.

Parameters: ui The new "UI" property

showPopup

public void showPopup()

This method displays popup with list of combo box's items on the screen

updateUI

public void updateUI()

This method sets this comboBox's UI to the UIManager's default for the current look and feel.