|
JavaTM 2 Platform Std. Ed. v1.3 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--java.awt.Component | +--java.awt.Container | +--javax.swing.JComponent | +--javax.swing.JComboBox
A component that combines a button or text field and a drop-down list. The user can select a value from the drop-down list, which appears at the user's request. If you make the combo box editable, then the combo box includes a text field into which the user can type a value. For examples and information on using combo boxes see How to Use Combo Boxes, a section in The Java Tutorial.
For the keyboard keys used by this component in the standard Look and Feel (L&F) renditions, see the JComboBox key assignments.
Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. A future release of Swing will provide support for long term persistence.
Inner Class Summary | |
protected class |
JComboBox.AccessibleJComboBox
This class implements accessibility support for the JComboBox class. |
static interface |
JComboBox.KeySelectionManager
The interface that defines a KeySelectionManager . |
Inner classes inherited from class javax.swing.JComponent |
JComponent.AccessibleJComponent |
Inner classes inherited from class java.awt.Container |
Container.AccessibleAWTContainer |
Inner classes inherited from class java.awt.Component |
Component.AccessibleAWTComponent |
Field Summary | |
protected String |
actionCommand
|
protected ComboBoxModel |
dataModel
|
protected ComboBoxEditor |
editor
|
protected boolean |
isEditable
|
protected JComboBox.KeySelectionManager |
keySelectionManager
|
protected boolean |
lightWeightPopupEnabled
|
protected int |
maximumRowCount
|
protected ListCellRenderer |
renderer
|
protected Object |
selectedItemReminder
|
Fields inherited from class javax.swing.JComponent |
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW |
Fields inherited from class java.awt.Component |
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT |
Fields inherited from interface java.awt.image.ImageObserver |
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH |
Constructor Summary | |
JComboBox()
Creates a JComboBox with a default data model. |
|
JComboBox(ComboBoxModel aModel)
Creates a JComboBox that takes it's items from an
existing ComboBoxModel . |
|
JComboBox(Object[] items)
Creates a JComboBox that contains the elements
in the specified array. |
|
JComboBox(Vector items)
Creates a JComboBox that contains the elements
in the specified Vector. |
Method Summary | |
void |
actionPerformed(ActionEvent e)
This method is public as an implementation side effect. |
void |
addActionListener(ActionListener l)
Adds an ActionListener . |
void |
addItem(Object anObject)
Adds an item to the item list. |
void |
addItemListener(ItemListener aListener)
Adds an ItemListener . |
void |
configureEditor(ComboBoxEditor anEditor,
Object anItem)
Initializes the editor with the specified item. |
protected void |
configurePropertiesFromAction(Action a)
Factory method which sets the ActionEvent source's
properties according to values from the Action instance. |
void |
contentsChanged(ListDataEvent e)
This method is public as an implementation side effect. |
protected PropertyChangeListener |
createActionPropertyChangeListener(Action a)
Factory method which creates the PropertyChangeListener
used to update the ActionEvent source as properties change
on its Action instance. |
protected JComboBox.KeySelectionManager |
createDefaultKeySelectionManager()
Returns an instance of the default key-selection manager. |
protected void |
fireActionEvent()
Notifies all listeners that have registered interest for notification on this event type. |
protected void |
fireItemStateChanged(ItemEvent e)
Notifies all listeners that have registered interest for notification on this event type. |
AccessibleContext |
getAccessibleContext()
Gets the AccessibleContext associated with this JComboBox. |
Action |
getAction()
Returns the currently set Action for this
ActionEvent source, or null if no
Action is set. |
String |
getActionCommand()
Returns the action command that is included in the event sent to action listeners. |
ComboBoxEditor |
getEditor()
Returns the editor used to paint and edit the selected item in the JComboBox field. |
Object |
getItemAt(int index)
Returns the list item at the specified index. |
int |
getItemCount()
Returns the number of items in the list. |
JComboBox.KeySelectionManager |
getKeySelectionManager()
Returns the list's key-selection manager. |
int |
getMaximumRowCount()
Returns the maximum number of items the combo box can display without a scrollbar |
ComboBoxModel |
getModel()
Returns the data model currently used by the JComboBox . |
ListCellRenderer |
getRenderer()
Returns the renderer used to display the selected item in the JComboBox field. |
int |
getSelectedIndex()
Returns the first item in the list that matches the given item. |
Object |
getSelectedItem()
Returns the currently selected item. |
Object[] |
getSelectedObjects()
Returns an array containing the selected item. |
ComboBoxUI |
getUI()
Returns the L&F object that renders this component. |
String |
getUIClassID()
Returns the name of the L&F class that renders this component. |
void |
hidePopup()
Causes the combo box to close its popup window. |
void |
insertItemAt(Object anObject,
int index)
Inserts an item into the item list at a given index. |
protected void |
installAncestorListener()
|
void |
intervalAdded(ListDataEvent e)
Invoked items have been added to the internal data model. |
void |
intervalRemoved(ListDataEvent e)
Invoked when values have been removed from the data model. |
boolean |
isEditable()
Returns true if the JComboBox is editable. |
boolean |
isFocusTraversable()
Returns true if the component can receive the focus. |
boolean |
isLightWeightPopupEnabled()
Returns true if lightweight (all-Java) popups are in use, or false if heavyweight (native peer) popups are being used. |
boolean |
isPopupVisible()
Determines the visibility of the popup. |
protected String |
paramString()
Returns a string representation of this JComboBox . |
void |
processKeyEvent(KeyEvent e)
Handles KeyEvent s, looking for the Tab key. |
void |
removeActionListener(ActionListener l)
Removes an ActionListener . |
void |
removeAllItems()
Removes all items from the item list. |
void |
removeItem(Object anObject)
Removes an item from the item list. |
void |
removeItemAt(int anIndex)
Removes the item at anIndex
This method works only if the JComboBox uses the
default data model. |
void |
removeItemListener(ItemListener aListener)
Removes an ItemListener . |
protected void |
selectedItemChanged()
This method is called when the selected item changes. |
boolean |
selectWithKeyChar(char keyChar)
Selects the list item that correponds to the specified keyboard character and returns true, if there is an item corresponding to that character. |
void |
setAction(Action a)
Sets the Action for the ActionEvent source. |
void |
setActionCommand(String aCommand)
Sets the action commnand that should be included in the event sent to action listeners. |
void |
setEditable(boolean aFlag)
Determines whether the JComboBox field is editable. |
void |
setEditor(ComboBoxEditor anEditor)
Sets the editor used to paint and edit the selected item in the JComboBox field. |
void |
setEnabled(boolean b)
Enables the combo box so that items can be selected. |
void |
setKeySelectionManager(JComboBox.KeySelectionManager aManager)
Sets the object that translates a keyboard character into a list selection. |
void |
setLightWeightPopupEnabled(boolean aFlag)
When displaying the popup, JComboBox choose to use
a light weight popup if it fits. |
void |
setMaximumRowCount(int count)
Sets the maximum number of rows the JComboBox displays. |
void |
setModel(ComboBoxModel aModel)
Sets the data model that the JComboBox uses to obtain
the list of items. |
void |
setPopupVisible(boolean v)
Sets the visibility of the popup. |
void |
setRenderer(ListCellRenderer aRenderer)
Sets the renderer that paints the item selected from the list in the JComboBox field. |
void |
setSelectedIndex(int anIndex)
Selects the item at index anIndex . |
void |
setSelectedItem(Object anObject)
Sets the selected item in the JComboBox by
specifying the object in the list. |
void |
setUI(ComboBoxUI ui)
Sets the L&F object that renders this component. |
void |
showPopup()
Causes the combo box to display its popup window. |
void |
updateUI()
Notification from the UIFactory that the L&F has changed. |
Methods inherited from class java.awt.Container |
add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setLayout, validate, validateTree |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
protected ComboBoxModel dataModel
protected ListCellRenderer renderer
protected ComboBoxEditor editor
protected int maximumRowCount
protected boolean isEditable
protected Object selectedItemReminder
protected JComboBox.KeySelectionManager keySelectionManager
protected String actionCommand
protected boolean lightWeightPopupEnabled
Constructor Detail |
public JComboBox(ComboBoxModel aModel)
JComboBox
that takes it's items from an
existing ComboBoxModel
. Since the
ComboBoxModel
is provided, a combo box created using
this constructor does not create a default combo box model and
may impact how the insert, remove and add methods behave.aModel
- the ComboBoxModel
that provides the
displayed list of itemsDefaultComboBoxModel
public JComboBox(Object[] items)
JComboBox
that contains the elements
in the specified array. By default the first item in the array
(and therefore the data model) becomes selected.items
- an array of objects to insert into the combo boxDefaultComboBoxModel
public JComboBox(Vector items)
JComboBox
that contains the elements
in the specified Vector. By default the first item in the vector
and therefore the data model) becomes selected.items
- an array of vectors to insert into the combo boxDefaultComboBoxModel
public JComboBox()
JComboBox
with a default data model.
The default data model is an empty list of objects.
Use addItem
to add items. By default the first item
in the data model becomes selected.DefaultComboBoxModel
Method Detail |
protected void installAncestorListener()
public void setUI(ComboBoxUI ui)
ui
- the ComboBoxUI
L&F objectUIDefaults.getUI(javax.swing.JComponent)
public void updateUI()
UIFactory
that the L&F has changed.updateUI
in class JComponent
JComponent.updateUI()
public String getUIClassID()
getUIClassID
in class JComponent
JComponent.getUIClassID()
,
UIDefaults.getUI(javax.swing.JComponent)
public ComboBoxUI getUI()
public void setModel(ComboBoxModel aModel)
JComboBox
uses to obtain
the list of items.aModel
- the ComboBoxModel
that provides the
displayed list of itemspublic ComboBoxModel getModel()
JComboBox
.ComboBoxModel
that provides the displayed
list of itemspublic void setLightWeightPopupEnabled(boolean aFlag)
JComboBox
choose to use
a light weight popup if it fits.
This method allows you to disable this feature. You have to do disable
it if your application mixes light weight and heavy weights components.public boolean isLightWeightPopupEnabled()
public void setEditable(boolean aFlag)
JComboBox
field is editable.
An editable JComboBox
allows the user to type into the
field or selected an item from the list to initialize the field,
after which it can be edited. (The editing affects only the field,
the list item remains intact.) A non editable JComboBox
displays the selected item in the field,
but the selection cannot be modified.aFlag
- a boolean value, where true indicates that the
field is editablepublic boolean isEditable()
JComboBox
is editable.
By default, a combo box is not editable.JComboBox
is editable, else falsepublic void setMaximumRowCount(int count)
JComboBox
displays.
If the number of objects in the model is greater than count,
the combo box uses a scrollbar.count
- an integer specifying the maximum number of items to
display in the list before using a scrollbarpublic int getMaximumRowCount()
public void setRenderer(ListCellRenderer aRenderer)
The default renderer displays a string, obtained
by calling the selected object's toString
method.
Other renderers can handle graphic images and composite items.
To display the selected item,
aRenderer.getListCellRendererComponent
is called, passing the list object and an index of -1.
aRenderer
- the ListCellRenderer
that
displays the selected itemsetEditor(javax.swing.ComboBoxEditor)
public ListCellRenderer getRenderer()
JComboBox
field.ListCellRenderer
that displays
the selected item.public void setEditor(ComboBoxEditor anEditor)
JComboBox
field. The editor is used only if the
receiving JComboBox
is editable. If not editable,
the combo box uses the renderer to paint the selected item.anEditor
- the ComboBoxEditor
that
displays the selected itemsetRenderer(javax.swing.ListCellRenderer)
public ComboBoxEditor getEditor()
JComboBox
field.ComboBoxEditor
that displays the selected itempublic void setSelectedItem(Object anObject)
JComboBox
by
specifying the object in the list.
If anObject
is in the list, the list displays with
anObject
selected.anObject
- the list object to selectpublic Object getSelectedItem()
public void setSelectedIndex(int anIndex)
anIndex
.anIndex
- an integer specifying the list item to select,
where 0 specifies
the first item in the listIllegalArgumentException
- if anIndex
< -1 or
anIndex
is greater than or equal to sizepublic int getSelectedIndex()
JComboBox
allows selected items that are not in the list.
Returns -1 if there is no selected item or if the user specified
an item which is not in the list.public void addItem(Object anObject)
JComboBox
uses the
default data model. JComboBox
uses the default data model when created with the
empty constructor and no other model has been set.
Warning: Focus and keyboard navigation problems may arise if you add duplicate String objects. A workaround is to add new objects instead of String objects and make sure that the toString() method is defined. For example:
comboBox.addItem(makeObj("Item 1")); comboBox.addItem(makeObj("Item 1")); ... private Object makeObj(final String item) { return new Object() { public String toString() { return item; } }; }
anObject
- the Object to add to the listpublic void insertItemAt(Object anObject, int index)
JComboBox
uses the
default data model. JComboBox
uses the default data model when created with the
empty constructor and no other model has been set.anObject
- the Object
to add to the listindex
- an integer specifying the position at which
to add the itempublic void removeItem(Object anObject)
JComboBox
uses the
default data model. JComboBox
uses the default data model when created with the empty constructor
and no other model has been set.anObject
- the object to remove from the item listpublic void removeItemAt(int anIndex)
anIndex
This method works only if the JComboBox
uses the
default data model. JComboBox
uses the default data model when created with the
empty constructor and no other model has been set.anIndex
- an int specifying the idex of the item to remove,
where 0
indicates the first item in the listpublic void removeAllItems()
public void showPopup()
setPopupVisible(boolean)
public void hidePopup()
setPopupVisible(boolean)
public void setPopupVisible(boolean v)
public boolean isPopupVisible()
public void addItemListener(ItemListener aListener)
ItemListener
.
aListener
will receive an event when
the selected item changes.addItemListener
in interface ItemSelectable
aListener
- the ItemListener
that is to be notifiedpublic void removeItemListener(ItemListener aListener)
ItemListener
.removeItemListener
in interface ItemSelectable
aListener
- the ItemListener
to removepublic void addActionListener(ActionListener l)
ActionListener
. The listener will
receive an action event
the user finishes making a selection.l
- the ActionListener
that is to be notifiedpublic void removeActionListener(ActionListener l)
ActionListener
.l
- the ActionListener
to removepublic void setActionCommand(String aCommand)
aCommand
- a string containing the "command" that is sent
to action listeners; the same listener can then
do different things depending on the command it
receivespublic String getActionCommand()
public void setAction(Action a)
Action
for the ActionEvent
source.
The new Action
replaces any previously set
Action
but does not affect ActionListeners
independantly added with addActionListener
.
If the Action
is already a registered
ActionListener
for the ActionEvent
source,
it is not re-registered.
A side-effect of setting the Action
is that the
ActionEvent
source's properties are immedately set
from the values in the Action
(performed by the method
configurePropertiesFromAction
) and subsequently
updated as the Action
's properties change (via a
PropertyChangeListener
created by the method
createActionPropertyChangeListener
.
a
- the Action
for the JComboBox
,
or null
.Action
,
getAction()
,
configurePropertiesFromAction(javax.swing.Action)
,
createActionPropertyChangeListener(javax.swing.Action)
public Action getAction()
Action
for this
ActionEvent
source, or null
if no
Action
is set.Action
for this ActionEvent
source; or null
Action
,
setAction(javax.swing.Action)
protected void configurePropertiesFromAction(Action a)
ActionEvent
source's
properties according to values from the Action
instance.
The properties which are set may differ for subclasses.
By default, the properties which get set are
Enabled
and ToolTipText
.a
- the Action
from which to get the properties,
or null
Action
,
setAction(javax.swing.Action)
protected PropertyChangeListener createActionPropertyChangeListener(Action a)
PropertyChangeListener
used to update the ActionEvent
source as properties change
on its Action
instance.
Subclasses may override this in order to provide their own
PropertyChangeListener
if the set of
properties which should be kept up to date differs from the
default properties (Text, Icon, Enabled, ToolTipText).
Note that PropertyChangeListeners
should avoid holding
strong references to the ActionEvent
source,
as this may hinder garbage collection of the ActionEvent
source and all components in its containment hierarchy.Action
,
setAction(javax.swing.Action)
protected void fireItemStateChanged(ItemEvent e)
e
- the event of interestEventListenerList
protected void fireActionEvent()
e
- the event of interestEventListenerList
protected void selectedItemChanged()
public Object[] getSelectedObjects()
ItemSelectable
.getSelectedObjects
in interface ItemSelectable
public void actionPerformed(ActionEvent e)
actionPerformed
in interface ActionListener
public void contentsChanged(ListDataEvent e)
contentsChanged
in interface ListDataListener
ListDataListener
public boolean selectWithKeyChar(char keyChar)
keyChar
- a char, typically this is a keyboard key
typed by the userpublic void intervalAdded(ListDataEvent e)
intervalAdded
in interface ListDataListener
ListDataListener
public void intervalRemoved(ListDataEvent e)
intervalRemoved
in interface ListDataListener
ListDataListener
public void setEnabled(boolean b)
setEnabled
in class JComponent
b
- a boolean value, where true enables the component and
false disables itpublic void configureEditor(ComboBoxEditor anEditor, Object anItem)
anEditor
- the ComboBoxEditor
that displays
the list item in the
combo box field and allows it to be editedanItem
- the object to display and edit in the fieldpublic void processKeyEvent(KeyEvent e)
KeyEvent
s, looking for the Tab key.
If the Tab key is found, the popup window is closed.processKeyEvent
in class JComponent
e
- the KeyEvent
containing the keyboard
key that was pressedpublic boolean isFocusTraversable()
Editor
object receives the focus,
instead of the component.isFocusTraversable
in class JComponent
public void setKeySelectionManager(JComboBox.KeySelectionManager aManager)
public JComboBox.KeySelectionManager getKeySelectionManager()
KeySelectionManager
currently in usepublic int getItemCount()
public Object getItemAt(int index)
index
is out of range (less than zero or greater than or equal to size)
it will return null
.index
- an integer indicating the list position, where the first
item starts at zeroObject
at that list position; or
null
if out of rangeprotected JComboBox.KeySelectionManager createDefaultKeySelectionManager()
KeySelectionManager
currently used by the listsetKeySelectionManager(javax.swing.JComboBox.KeySelectionManager)
protected String paramString()
JComboBox
.
This method is intended to be used only for debugging purposes,
and the content and format of the returned string may vary between
implementations. The returned string may be empty but may not
be null
.paramString
in class JComponent
JComboBox
public AccessibleContext getAccessibleContext()
getAccessibleContext
in interface Accessible
getAccessibleContext
in class JComponent
|
JavaTM 2 Platform Std. Ed. v1.3 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.