public class List extends Component implements ItemSelectable, Accessible
List component presents the user with a
 scrolling list of text items. The list can be set up so that
 the user can choose either one item or multiple items.
 For example, the code . . .
 List lst = new List(4, false);
 lst.add("Mercury");
 lst.add("Venus");
 lst.add("Earth");
 lst.add("JavaSoft");
 lst.add("Mars");
 lst.add("Jupiter");
 lst.add("Saturn");
 lst.add("Uranus");
 lst.add("Neptune");
 lst.add("Pluto");
 cnt.add(lst);
 
 where cnt is a container, produces the following
 scrolling list:
 
  
 
 If the List allows multiple selections, then clicking on
 an item that is already selected deselects it. In the preceding
 example, only one item from the scrolling list can be selected
 at a time, since the second argument when creating the new scrolling
 list is false. If the List does not allow multiple
 selections, selecting an item causes any other selected item
 to be deselected.
 
 Note that the list in the example shown was created with four visible
 rows.  Once the list has been created, the number of visible rows
 cannot be changed.  A default List is created with
 four rows, so that lst = new List() is equivalent to
 list = new List(4, false).
 
 Beginning with Java 1.1, the Abstract Window Toolkit
 sends the List object all mouse, keyboard, and focus events
 that occur over it. (The old AWT event model is being maintained
 only for backwards compatibility, and its use is discouraged.)
 
 When an item is selected or deselected by the user, AWT sends an instance
 of ItemEvent to the list.
 When the user double-clicks on an item in a scrolling list,
 AWT sends an instance of ActionEvent to the
 list following the item event. AWT also generates an action event
 when the user presses the return key while an item in the
 list is selected.
 
 If an application wants to perform some action based on an item
 in this list being selected or activated by the user, it should implement
 ItemListener or ActionListener
 as appropriate and register the new listener to receive
 events from this list.
 
For multiple-selection scrolling lists, it is considered a better user interface to use an external gesture (such as clicking on a button) to trigger the action.
ItemEvent, 
ItemListener, 
ActionEvent, 
ActionListener, 
Serialized Form| Modifier and Type | Class and Description | 
|---|---|
| protected class  | List.AccessibleAWTListThis class implements accessibility support for the
  Listclass. | 
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategyaccessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENTABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH| Constructor and Description | 
|---|
| List()Creates a new scrolling list. | 
| List(int rows)Creates a new scrolling list initialized with the specified
 number of visible lines. | 
| List(int rows,
    boolean multipleMode)Creates a new scrolling list initialized to display the specified
 number of rows. | 
| Modifier and Type | Method and Description | 
|---|---|
| void | add(String item)Adds the specified item to the end of scrolling list. | 
| void | add(String item,
   int index)Adds the specified item to the the scrolling list
 at the position indicated by the index. | 
| void | addActionListener(ActionListener l)Adds the specified action listener to receive action events from
 this list. | 
| void | addItem(String item)Deprecated. 
 replaced by  add(String). | 
| void | addItem(String item,
       int index)Deprecated. 
 replaced by  add(String, int). | 
| void | addItemListener(ItemListener l)Adds the specified item listener to receive item events from
 this list. | 
| void | addNotify()Creates the peer for the list. | 
| boolean | allowsMultipleSelections()Deprecated. 
 As of JDK version 1.1,
 replaced by  isMultipleMode(). | 
| void | clear()Deprecated. 
 As of JDK version 1.1,
 replaced by  removeAll(). | 
| int | countItems()Deprecated. 
 As of JDK version 1.1,
 replaced by  getItemCount(). | 
| void | delItem(int position)Deprecated. 
 replaced by  remove(String)andremove(int). | 
| void | delItems(int start,
        int end)Deprecated. 
 As of JDK version 1.1,
 Not for public use in the future.
 This method is expected to be retained only as a package
 private method. | 
| void | deselect(int index)Deselects the item at the specified index. | 
| AccessibleContext | getAccessibleContext()Gets the  AccessibleContextassociated with thisList. | 
| ActionListener[] | getActionListeners()Returns an array of all the action listeners
 registered on this list. | 
| String | getItem(int index)Gets the item associated with the specified index. | 
| int | getItemCount()Gets the number of items in the list. | 
| ItemListener[] | getItemListeners()Returns an array of all the item listeners
 registered on this list. | 
| String[] | getItems()Gets the items in the list. | 
| <T extends EventListener> | getListeners(Class<T> listenerType)Returns an array of all the objects currently registered
 as  FooListeners
 upon thisList. | 
| Dimension | getMinimumSize()Determines the minimum size of this scrolling list. | 
| Dimension | getMinimumSize(int rows)Gets the minimum dimensions for a list with the specified
 number of rows. | 
| Dimension | getPreferredSize()Gets the preferred size of this scrolling list. | 
| Dimension | getPreferredSize(int rows)Gets the preferred dimensions for a list with the specified
 number of rows. | 
| int | getRows()Gets the number of visible lines in this list. | 
| int | getSelectedIndex()Gets the index of the selected item on the list, | 
| int[] | getSelectedIndexes()Gets the selected indexes on the list. | 
| String | getSelectedItem()Gets the selected item on this scrolling list. | 
| String[] | getSelectedItems()Gets the selected items on this scrolling list. | 
| Object[] | getSelectedObjects()Gets the selected items on this scrolling list in an array of Objects. | 
| int | getVisibleIndex()Gets the index of the item that was last made visible by
 the method  makeVisible. | 
| boolean | isIndexSelected(int index)Determines if the specified item in this scrolling list is
 selected. | 
| boolean | isMultipleMode()Determines whether this list allows multiple selections. | 
| boolean | isSelected(int index)Deprecated. 
 As of JDK version 1.1,
 replaced by  isIndexSelected(int). | 
| void | makeVisible(int index)Makes the item at the specified index visible. | 
| Dimension | minimumSize()Deprecated. 
 As of JDK version 1.1,
 replaced by  getMinimumSize(). | 
| Dimension | minimumSize(int rows)Deprecated. 
 As of JDK version 1.1,
 replaced by  getMinimumSize(int). | 
| protected String | paramString()Returns the parameter string representing the state of this
 scrolling list. | 
| Dimension | preferredSize()Deprecated. 
 As of JDK version 1.1,
 replaced by  getPreferredSize(). | 
| Dimension | preferredSize(int rows)Deprecated. 
 As of JDK version 1.1,
 replaced by  getPreferredSize(int). | 
| protected void | processActionEvent(ActionEvent e)Processes action events occurring on this component
 by dispatching them to any registered
  ActionListenerobjects. | 
| protected void | processEvent(AWTEvent e)Processes events on this scrolling list. | 
| protected void | processItemEvent(ItemEvent e)Processes item events occurring on this list by
 dispatching them to any registered
  ItemListenerobjects. | 
| void | remove(int position)Removes the item at the specified position
 from this scrolling list. | 
| void | remove(String item)Removes the first occurrence of an item from the list. | 
| void | removeActionListener(ActionListener l)Removes the specified action listener so that it no longer
 receives action events from this list. | 
| void | removeAll()Removes all items from this list. | 
| void | removeItemListener(ItemListener l)Removes the specified item listener so that it no longer
 receives item events from this list. | 
| void | removeNotify()Removes the peer for this list. | 
| void | replaceItem(String newValue,
           int index)Replaces the item at the specified index in the scrolling list
 with the new string. | 
| void | select(int index)Selects the item at the specified index in the scrolling list. | 
| void | setMultipleMode(boolean b)Sets the flag that determines whether this list
 allows multiple selections. | 
| void | setMultipleSelections(boolean b)Deprecated. 
 As of JDK version 1.1,
 replaced by  setMultipleMode(boolean). | 
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, getBaseline, getBaselineResizeBehavior, 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, revalidate, 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, validatepublic List()
     throws HeadlessException
List(0, false).  Also note that the number of visible
 lines in the list cannot be changed after it has been created.HeadlessException - if GraphicsEnvironment.isHeadless()
 returns true.GraphicsEnvironment.isHeadless()public List(int rows)
     throws HeadlessException
List(rows, false).  Also note that the number
 of visible rows in the list cannot be changed after it has
 been created.rows - the number of items to show.HeadlessException - if GraphicsEnvironment.isHeadless()
 returns true.GraphicsEnvironment.isHeadless()public List(int rows,
            boolean multipleMode)
     throws HeadlessException
multipleMode is
 true, then the user can select multiple items from
 the list. If it is false, only one item at a time
 can be selected.rows - the number of items to show.multipleMode - if true,
                     then multiple selections are allowed;
                     otherwise, only one item can be selected at a time.HeadlessException - if GraphicsEnvironment.isHeadless()
 returns true.GraphicsEnvironment.isHeadless()public void addNotify()
addNotify in class ComponentComponent.isDisplayable(), 
Component.removeNotify(), 
Component.invalidate()public void removeNotify()
removeNotify in class ComponentComponent.isDisplayable(), 
Component.addNotify()public int getItemCount()
getItem(int)@Deprecated public int countItems()
getItemCount().public String getItem(int index)
index - the position of the itemgetItemCount()public String[] getItems()
select(int), 
deselect(int), 
isIndexSelected(int)public void add(String item)
item - the item to be added@Deprecated public void addItem(String item)
add(String).public void add(String item, int index)
item - the item to be added;
              if this parameter is null then the item is
              treated as an empty string, ""index - the position at which to add the item@Deprecated public void addItem(String item, int index)
add(String, int).public void replaceItem(String newValue, int index)
newValue - a new string to replace an existing itemindex - the position of the item to replaceArrayIndexOutOfBoundsException - if index
          is out of rangepublic void removeAll()
remove(java.lang.String), 
delItems(int, int)@Deprecated public void clear()
removeAll().public void remove(String item)
item - the item to remove from the listIllegalArgumentException - if the item doesn't exist in the listpublic void remove(int position)
position - the index of the item to deleteArrayIndexOutOfBoundsException - if the position is less than 0 or
               greater than getItemCount()-1add(String, int)@Deprecated public void delItem(int position)
remove(String)
                         and remove(int).public int getSelectedIndex()
-1 is returned.select(int), 
deselect(int), 
isIndexSelected(int)public int[] getSelectedIndexes()
select(int), 
deselect(int), 
isIndexSelected(int)public String getSelectedItem()
null is returned.select(int), 
deselect(int), 
isIndexSelected(int)public String[] getSelectedItems()
select(int), 
deselect(int), 
isIndexSelected(int)public Object[] getSelectedObjects()
getSelectedObjects in interface ItemSelectableObjects representing the
                selected items on this scrolling list;
                if no item is selected, a zero-length array is returned.getSelectedItems(), 
ItemSelectablepublic void select(int index)
Note that passing out of range parameters is invalid, and will result in unspecified behavior.
Note that this method should be primarily used to
 initially select an item in this component.
 Programmatically calling this method will not trigger
 an ItemEvent.  The only way to trigger an
 ItemEvent is by user interaction.
index - the position of the item to selectgetSelectedItem(), 
deselect(int), 
isIndexSelected(int)public void deselect(int index)
Note that passing out of range parameters is invalid, and will result in unspecified behavior.
If the item at the specified index is not selected, then the operation is ignored.
index - the position of the item to deselectselect(int), 
getSelectedItem(), 
isIndexSelected(int)public boolean isIndexSelected(int index)
index - the item to be checkedtrue if the specified item has been
                       selected; false otherwiseselect(int), 
deselect(int)@Deprecated public boolean isSelected(int index)
isIndexSelected(int).public int getRows()
List has been created, this number
 will never change.public boolean isMultipleMode()
true if this list allows multiple
                 selections; otherwise, falsesetMultipleMode(boolean)@Deprecated public boolean allowsMultipleSelections()
isMultipleMode().public void setMultipleMode(boolean b)
b - if true then multiple selections
                      are allowed; otherwise, only one item from
                      the list can be selected at onceisMultipleMode()@Deprecated public void setMultipleSelections(boolean b)
setMultipleMode(boolean).public int getVisibleIndex()
makeVisible.makeVisible(int)public void makeVisible(int index)
index - the position of the itemgetVisibleIndex()public Dimension getPreferredSize(int rows)
rows - number of rows in the listComponent.getPreferredSize()@Deprecated public Dimension preferredSize(int rows)
getPreferredSize(int).public Dimension getPreferredSize()
getPreferredSize in class ComponentComponent.getPreferredSize()@Deprecated public Dimension preferredSize()
getPreferredSize().preferredSize in class Componentpublic Dimension getMinimumSize(int rows)
rows - number of rows in the listComponent.getMinimumSize()@Deprecated public Dimension minimumSize(int rows)
getMinimumSize(int).public Dimension getMinimumSize()
getMinimumSize in class ComponentComponent.getMinimumSize()@Deprecated public Dimension minimumSize()
getMinimumSize().minimumSize in class Componentpublic void addItemListener(ItemListener l)
select or deselect.
 If listener l is null,
 no exception is thrown and no action is performed.
 Refer to AWT Threading Issues for details on AWT's threading model.
addItemListener in interface ItemSelectablel - the item listenerremoveItemListener(java.awt.event.ItemListener), 
getItemListeners(), 
select(int), 
deselect(int), 
ItemEvent, 
ItemListenerpublic void removeItemListener(ItemListener l)
l is null,
 no exception is thrown and no action is performed.
 Refer to AWT Threading Issues for details on AWT's threading model.
removeItemListener in interface ItemSelectablel - the item listeneraddItemListener(java.awt.event.ItemListener), 
getItemListeners(), 
ItemEvent, 
ItemListenerpublic ItemListener[] getItemListeners()
ItemListeners
         or an empty array if no item
         listeners are currently registeredaddItemListener(java.awt.event.ItemListener), 
removeItemListener(java.awt.event.ItemListener), 
ItemEvent, 
ItemListenerpublic void addActionListener(ActionListener l)
 If listener l is null,
 no exception is thrown and no action is performed.
 
Refer to AWT Threading Issues for details on AWT's threading model.
l - the action listenerremoveActionListener(java.awt.event.ActionListener), 
getActionListeners(), 
ActionEvent, 
ActionListenerpublic void removeActionListener(ActionListener l)
l is null,
 no exception is thrown and no action is performed.
 Refer to AWT Threading Issues for details on AWT's threading model.
l - the action listeneraddActionListener(java.awt.event.ActionListener), 
getActionListeners(), 
ActionEvent, 
ActionListenerpublic ActionListener[] getActionListeners()
ActionListeners
         or an empty array if no action
         listeners are currently registeredaddActionListener(java.awt.event.ActionListener), 
removeActionListener(java.awt.event.ActionListener), 
ActionEvent, 
ActionListenerpublic <T extends EventListener> T[] getListeners(Class<T> listenerType)
FooListeners
 upon this List.
 FooListeners are registered using the
 addFooListener method.
 
 You can specify the listenerType argument
 with a class literal, such as
 FooListener.class.
 For example, you can query a
 List l
 for its item listeners with the following code:
 
ItemListener[] ils = (ItemListener[])(l.getListeners(ItemListener.class));If no such listeners exist, this method returns an empty array.
getListeners in class ComponentlistenerType - the type of listeners requested; this parameter
          should specify an interface that descends from
          java.util.EventListenerFooListeners on this list,
          or an empty array if no such
          listeners have been addedClassCastException - if listenerType
          doesn't specify a class or interface that implements
          java.util.EventListenergetItemListeners()protected void processEvent(AWTEvent e)
ItemEvent, it invokes the
 processItemEvent method. Else, if the
 event is an instance of ActionEvent,
 it invokes processActionEvent.
 If the event is not an item event or an action event,
 it invokes processEvent on the superclass.
 Note that if the event parameter is null
 the behavior is unspecified and may result in an
 exception.
processEvent in class Componente - the eventActionEvent, 
ItemEvent, 
processActionEvent(java.awt.event.ActionEvent), 
processItemEvent(java.awt.event.ItemEvent)protected void processItemEvent(ItemEvent e)
ItemListener objects.
 This method is not called unless item events are enabled for this component. Item events are enabled when one of the following occurs:
ItemListener object is registered
 via addItemListener.
 enableEvents.
 Note that if the event parameter is null
 the behavior is unspecified and may result in an
 exception.
e - the item eventItemEvent, 
ItemListener, 
addItemListener(java.awt.event.ItemListener), 
Component.enableEvents(long)protected void processActionEvent(ActionEvent e)
ActionListener objects.
 This method is not called unless action events are enabled for this component. Action events are enabled when one of the following occurs:
ActionListener object is registered
 via addActionListener.
 enableEvents.
 Note that if the event parameter is null
 the behavior is unspecified and may result in an
 exception.
e - the action eventActionEvent, 
ActionListener, 
addActionListener(java.awt.event.ActionListener), 
Component.enableEvents(long)protected String paramString()
paramString in class Component@Deprecated public void delItems(int start, int end)
public AccessibleContext getAccessibleContext()
AccessibleContext associated with this
 List. For lists, the AccessibleContext
 takes the form of an AccessibleAWTList.
 A new AccessibleAWTList instance is created, if necessary.getAccessibleContext in interface AccessiblegetAccessibleContext in class ComponentAccessibleAWTList that serves as the
         AccessibleContext of this List Submit a bug or feature 
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
 Copyright © 1993, 2025, Oracle and/or its affiliates.  All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.