java.awt
Class List

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.List
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible

public class List
extends Component
implements ItemSelectable, Accessible

Class that implements a listbox widget

See Also:
Serialized Form

Nested Class Summary
protected  class List.AccessibleAWTList
           
 
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
 
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
List()
          Initializes a new instance of List with no visible lines and multi-select disabled.
List(int rows)
          Initializes a new instance of List with the specified number of visible lines and multi-select disabled.
List(int rows, boolean multipleMode)
          Initializes a new instance of List with the specified number of lines and the specified multi-select setting.
 
Method Summary
 void add(String item)
          This method adds the specified item to the end of the list.
 void add(String item, int index)
          Adds the specified item to the specified location in the list.
 void addActionListener(ActionListener listener)
          Adds the specified ActionListener to the list of registered listeners for this object.
 void addItem(String item)
          Deprecated. Use add() instead.
 void addItem(String item, int index)
          Deprecated. Use add() instead.
 void addItemListener(ItemListener listener)
          Adds the specified ItemListener to the list of registered listeners for this object.
 void addNotify()
          Notifies this object to create its native peer.
 boolean allowsMultipleSelections()
          Deprecated. This method is deprecated in favor of isMultipleMode().
 void clear()
          Deprecated. This method is deprecated in favor of removeAll().
 int countItems()
          Deprecated. This method is deprecated in favor of getItemCount()
 void delItem(int index)
          Deprecated.  
 void delItems(int start, int end)
          Deprecated. This method is deprecated for some unknown reason.
 void deselect(int index)
          Makes the item at the specified index not selected.
 AccessibleContext getAccessibleContext()
          Gets the AccessibleContext associated with this List.
 ActionListener[] getActionListeners()
          Returns all action listeners registered to this object.
 String getItem(int index)
          Returns the item at the specified index.
 int getItemCount()
          Returns the number of items in this list.
 ItemListener[] getItemListeners()
          Returns all action listeners registered to this object.
 String[] getItems()
          Returns the complete list of items.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
          Returns an array of all the objects currently registered as FooListeners upon this List.
 Dimension getMinimumSize()
          Returns the minimum size of this component.
 Dimension getMinimumSize(int rows)
          Returns the minimum size of this component assuming it had the specified number of rows.
 Dimension getPreferredSize()
          Returns the preferred size of this component.
 Dimension getPreferredSize(int rows)
          Returns the preferred size of this component assuming it had the specified number of rows.
 int getRows()
          Returns the number of visible rows in the list.
 int getSelectedIndex()
          Returns the index of the currently selected item
 int[] getSelectedIndexes()
          Returns an array containing the indexes of the rows that are currently selected.
 String getSelectedItem()
          Returns the item that is currently selected, or null if there is no item selected.
 String[] getSelectedItems()
          Returns the list of items that are currently selected in this list.
 Object[] getSelectedObjects()
          Returns the list of items that are currently selected in this list as an array of type Object[] instead of String[].
 int getVisibleIndex()
          Returns the index of the last item that was made visible via the makeVisible() method.
 boolean isIndexSelected(int index)
          Tests whether or not the specified index is selected.
 boolean isMultipleMode()
          Tests whether or not multi-select mode is enabled.
 boolean isSelected(int index)
          Deprecated. This method is deprecated in favor of isIndexSelected(int).
 void makeVisible(int index)
          This method ensures that the item at the specified index is visible.
 Dimension minimumSize()
          Deprecated. This method is deprecated in favor of getMinimumSize.
 Dimension minimumSize(int rows)
          Deprecated. This method is deprecated in favor of getMinimumSize(int)>
protected  String paramString()
          Returns a debugging string for this object.
 Dimension preferredSize()
          Deprecated. This method is deprecated in favor of getPreferredSize.
 Dimension preferredSize(int rows)
          Deprecated. This method is deprecated in favor of getPreferredSize(int)>
protected  void processActionEvent(ActionEvent event)
          This method processes the specified event by dispatching it to any registered listeners.
protected  void processEvent(AWTEvent event)
          Processes the specified event for this object.
protected  void processItemEvent(ItemEvent event)
          This method processes the specified event by dispatching it to any registered listeners.
 void remove(int index)
          Deletes the item at the specified index.
 void remove(String item)
          Deletes the first occurrence of the specified item from the list.
 void removeActionListener(ActionListener listener)
          Removes the specified ActionListener from the list of registers listeners for this object.
 void removeAll()
          Deletes all of the items from the list.
 void removeItemListener(ItemListener listener)
          Removes the specified ItemListener from the list of registers listeners for this object.
 void removeNotify()
          Notifies this object to destroy its native peer.
 void replaceItem(String item, int index)
          Replaces the item at the specified index with the specified item.
 void select(int index)
          Makes the item at the specified index selected.
 void setMultipleMode(boolean multipleMode)
          This method enables or disables multiple selection mode for this list.
 void setMultipleSelections(boolean multipleMode)
          Deprecated.  
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paint, paintAll, postEvent, prepareImage, prepareImage, print, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, update, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

List

public List()
Initializes a new instance of List with no visible lines and multi-select disabled.

Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() is true.
Since:
1.1

List

public List(int rows)
Initializes a new instance of List with the specified number of visible lines and multi-select disabled.

Parameters:
rows - The number of visible rows in the list.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() is true.

List

public List(int rows,
            boolean multipleMode)
Initializes a new instance of List with the specified number of lines and the specified multi-select setting.

Parameters:
rows - The number of visible rows in the list.
multipleMode - true if multiple lines can be selected simultaneously, false otherwise.
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() is true.
Method Detail

getItemCount

public int getItemCount()
Returns the number of items in this list.

Returns:
The number of items in this list.
Since:
1.1

countItems

public int countItems()
Deprecated. This method is deprecated in favor of getItemCount()

Returns the number of items in this list.

Returns:
The number of items in this list.

getItems

public String[] getItems()
Returns the complete list of items.

Returns:
The complete list of items in the list.
Since:
1.1

getItem

public String getItem(int index)
Returns the item at the specified index.

Parameters:
index - The index of the item to retrieve.
Throws:
IndexOutOfBoundsException - If the index value is not valid.

getRows

public int getRows()
Returns the number of visible rows in the list.

Returns:
The number of visible rows in the list.

isMultipleMode

public boolean isMultipleMode()
Tests whether or not multi-select mode is enabled.

Returns:
true if multi-select mode is enabled, false otherwise.
Since:
1.1

allowsMultipleSelections

public boolean allowsMultipleSelections()
Deprecated. This method is deprecated in favor of isMultipleMode().

Tests whether or not multi-select mode is enabled.

Returns:
true if multi-select mode is enabled, false otherwise.

setMultipleMode

public void setMultipleMode(boolean multipleMode)
This method enables or disables multiple selection mode for this list.

Parameters:
multipleMode - true to enable multiple mode, false otherwise.
Since:
1.1

setMultipleSelections

public void setMultipleSelections(boolean multipleMode)
Deprecated. 

This method enables or disables multiple selection mode for this list.

Parameters:
multipleMode - true to enable multiple mode, false otherwise.

getMinimumSize

public Dimension getMinimumSize()
Returns the minimum size of this component.

Overrides:
getMinimumSize in class Component
Returns:
The minimum size of this component.
Since:
1.1
See Also:
Component.getPreferredSize(), Component.setMinimumSize(Dimension), LayoutManager

minimumSize

public Dimension minimumSize()
Deprecated. This method is deprecated in favor of getMinimumSize.

Returns the minimum size of this component.

Overrides:
minimumSize in class Component
Returns:
The minimum size of this component.

getMinimumSize

public Dimension getMinimumSize(int rows)
Returns the minimum size of this component assuming it had the specified number of rows.

Parameters:
rows - The number of rows to size for.
Returns:
The minimum size of this component.
Since:
1.1

minimumSize

public Dimension minimumSize(int rows)
Deprecated. This method is deprecated in favor of getMinimumSize(int)>

Returns the minimum size of this component assuming it had the specified number of rows.

Parameters:
rows - The number of rows to size for.
Returns:
The minimum size of this component.

getPreferredSize

public Dimension getPreferredSize()
Returns the preferred size of this component.

Overrides:
getPreferredSize in class Component
Returns:
The preferred size of this component.
Since:
1.1
See Also:
Component.getMinimumSize(), Component.setPreferredSize(Dimension), LayoutManager

preferredSize

public Dimension preferredSize()
Deprecated. This method is deprecated in favor of getPreferredSize.

Returns the preferred size of this component.

Overrides:
preferredSize in class Component
Returns:
The preferred size of this component.

getPreferredSize

public Dimension getPreferredSize(int rows)
Returns the preferred size of this component assuming it had the specified number of rows.

Parameters:
rows - The number of rows to size for.
Returns:
The preferred size of this component.
Since:
1.1

preferredSize

public Dimension preferredSize(int rows)
Deprecated. This method is deprecated in favor of getPreferredSize(int)>

Returns the preferred size of this component assuming it had the specified number of rows.

Parameters:
rows - The number of rows to size for.
Returns:
The preferred size of this component.

add

public void add(String item)
This method adds the specified item to the end of the list.

Parameters:
item - The item to add to the list.
Since:
1.1

addItem

public void addItem(String item)
Deprecated. Use add() instead.

This method adds the specified item to the end of the list.

Parameters:
item - The item to add to the list.

add

public void add(String item,
                int index)
Adds the specified item to the specified location in the list. If the desired index is -1 or greater than the number of rows in the list, then the item is added to the end.

Parameters:
item - The item to add to the list.
index - The location in the list to add the item, or -1 to add to the end.
Since:
1.1

addItem

public void addItem(String item,
                    int index)
Deprecated. Use add() instead.

Adds the specified item to the specified location in the list. If the desired index is -1 or greater than the number of rows in the list, then the item is added to the end.

Parameters:
item - The item to add to the list.
index - The location in the list to add the item, or -1 to add to the end.

delItem

public void delItem(int index)
             throws IllegalArgumentException
Deprecated. 

Deletes the item at the specified index.

Parameters:
index - The index of the item to delete.
Throws:
IllegalArgumentException - If the index is not valid

remove

public void remove(int index)
            throws IllegalArgumentException
Deletes the item at the specified index.

Parameters:
index - The index of the item to delete.
Throws:
IllegalArgumentException - If the index is not valid
Since:
1.1

delItems

public void delItems(int start,
                     int end)
              throws IllegalArgumentException
Deprecated. This method is deprecated for some unknown reason.

Deletes all items in the specified index range.

Parameters:
start - The beginning index of the range to delete.
end - The ending index of the range to delete.
Throws:
IllegalArgumentException - If the indexes are not valid

remove

public void remove(String item)
            throws IllegalArgumentException
Deletes the first occurrence of the specified item from the list.

Parameters:
item - The item to delete.
Throws:
IllegalArgumentException - If the specified item does not exist.
Since:
1.1

removeAll

public void removeAll()
Deletes all of the items from the list.

Since:
1.1

clear

public void clear()
Deprecated. This method is deprecated in favor of removeAll().

Deletes all of the items from the list.


replaceItem

public void replaceItem(String item,
                        int index)
                 throws ArrayIndexOutOfBoundsException
Replaces the item at the specified index with the specified item.

Parameters:
item - The new item value.
index - The index of the item to replace.
Throws:
ArrayIndexOutOfBoundsException - If the index is not valid.

getSelectedIndex

public int getSelectedIndex()
Returns the index of the currently selected item. -1 will be returned if there are no selected rows or if there are multiple selected rows.

Returns:
The index of the selected row.

getSelectedIndexes

public int[] getSelectedIndexes()
Returns an array containing the indexes of the rows that are currently selected.

Returns:
A list of indexes of selected rows.

getSelectedItem

public String getSelectedItem()
Returns the item that is currently selected, or null if there is no item selected. FIXME: What happens if multiple items selected?

Returns:
The selected item, or null if there is no selected item.

getSelectedItems

public String[] getSelectedItems()
Returns the list of items that are currently selected in this list.

Returns:
The list of currently selected items.

getSelectedObjects

public Object[] getSelectedObjects()
Returns the list of items that are currently selected in this list as an array of type Object[] instead of String[].

Specified by:
getSelectedObjects in interface ItemSelectable
Returns:
The list of currently selected items.

isIndexSelected

public boolean isIndexSelected(int index)
Tests whether or not the specified index is selected.

Parameters:
index - The index to test.
Returns:
true if the index is selected, false otherwise.
Since:
1.1

isSelected

public boolean isSelected(int index)
Deprecated. This method is deprecated in favor of isIndexSelected(int).

Tests whether or not the specified index is selected.

Parameters:
index - The index to test.
Returns:
true if the index is selected, false otherwise.

makeVisible

public void makeVisible(int index)
                 throws IllegalArgumentException
This method ensures that the item at the specified index is visible.

Parameters:
index - The index of the item to be made visible.
Throws:
IllegalArgumentException

getVisibleIndex

public int getVisibleIndex()
Returns the index of the last item that was made visible via the makeVisible() method.

Returns:
The index of the last item made visible via the makeVisible() method.

select

public void select(int index)
Makes the item at the specified index selected.

Parameters:
index - The index of the item to select.

deselect

public void deselect(int index)
Makes the item at the specified index not selected.

Parameters:
index - The index of the item to unselect.

addNotify

public void addNotify()
Notifies this object to create its native peer.

Overrides:
addNotify in class Component
See Also:
Component.isDisplayable(), Component.removeNotify()

removeNotify

public void removeNotify()
Notifies this object to destroy its native peer.

Overrides:
removeNotify in class Component
See Also:
Component.isDisplayable(), Component.addNotify()

addActionListener

public void addActionListener(ActionListener listener)
Adds the specified ActionListener to the list of registered listeners for this object.

Parameters:
listener - The listener to add.
Since:
1.1

removeActionListener

public void removeActionListener(ActionListener listener)
Removes the specified ActionListener from the list of registers listeners for this object.

Parameters:
listener - The listener to remove.
Since:
1.1

addItemListener

public void addItemListener(ItemListener listener)
Adds the specified ItemListener to the list of registered listeners for this object.

Specified by:
addItemListener in interface ItemSelectable
Parameters:
listener - The listener to add.
Since:
1.1

removeItemListener

public void removeItemListener(ItemListener listener)
Removes the specified ItemListener from the list of registers listeners for this object.

Specified by:
removeItemListener in interface ItemSelectable
Parameters:
listener - The listener to remove.
Since:
1.1

processEvent

protected void processEvent(AWTEvent event)
Processes the specified event for this object. If the event is an instance of ActionEvent then the processActionEvent() method is called. Similarly, if the even is an instance of ItemEvent then the processItemEvent() method is called. Otherwise the superclass method is called to process this event.

Overrides:
processEvent in class Component
Parameters:
event - The event to process.
Since:
1.1
See Also:
Component.processComponentEvent(ComponentEvent), Component.processFocusEvent(FocusEvent), Component.processKeyEvent(KeyEvent), Component.processMouseEvent(MouseEvent), Component.processMouseMotionEvent(MouseEvent), Component.processInputMethodEvent(InputMethodEvent), Component.processHierarchyEvent(HierarchyEvent), Component.processMouseWheelEvent(MouseWheelEvent)

processActionEvent

protected void processActionEvent(ActionEvent event)
This method processes the specified event by dispatching it to any registered listeners. Note that this method will only get called if action events are enabled. This will happen automatically if any listeners are added, or it can be done "manually" by calling the enableEvents() method.

Parameters:
event - The event to process.
Since:
1.1

processItemEvent

protected void processItemEvent(ItemEvent event)
This method processes the specified event by dispatching it to any registered listeners. Note that this method will only get called if item events are enabled. This will happen automatically if any listeners are added, or it can be done "manually" by calling the enableEvents() method.

Parameters:
event - The event to process.
Since:
1.1

paramString

protected String paramString()
Returns a debugging string for this object.

Overrides:
paramString in class Component
Returns:
A debugging string for this object.

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this List. FooListeners are registered using the addFooListener method.

Overrides:
getListeners in class Component
Parameters:
listenerType - the class of listeners to filter (null not permitted).
Returns:
An array of registered listeners.
Throws:
ClassCastException - If listenerType doesn't specify a class or interface that implements java.util.EventListener.
Since:
1.3
See Also:
Component.getComponentListeners(), Component.getFocusListeners(), Component.getHierarchyListeners(), Component.getHierarchyBoundsListeners(), Component.getKeyListeners(), Component.getMouseListeners(), Component.getMouseMotionListeners(), Component.getMouseWheelListeners(), Component.getInputMethodListeners(), Component.getPropertyChangeListeners()

getActionListeners

public ActionListener[] getActionListeners()
Returns all action listeners registered to this object.

Since:
1.4

getItemListeners

public ItemListener[] getItemListeners()
Returns all action listeners registered to this object.

Since:
1.4

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this List. The context is created, if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class Component
Returns:
the associated context