List

Name

Description

The List is a Component that provides a scrollable list of choices to select from. A List can be in one of two modes: single selection mode, in which only one item may be selected at a time; and multiple selection mode, in which several items may be selected at one time. A list does not necessarily display all of the choices at one time; one of the constructors lets you specify the number of choices to display simultaneously. Although the changes in 1.1 are extensive, almost all of them can be boiled down to (1) using the 1.1 event model, and (2) standardizing method names (e.g. set/get pairs).

Class Definition

public class java.awt.List extends java.awt.Component implements java.awt.ItemSelectable {
 // Constructors public List();
public List (int rows); public List (int rows, boolean multipleSelections); // Instance Methods public void add (String item); public synchronized void add (String item, int index); public void addActionListener (ActionListener l); public void addItem (String item);
public synchronized void addItem (String item, int index);  public void addItemListener (ItemListener l); public void addNotify();
public boolean allowsMultipleSelections();  public synchronized void clear();  public int countItems();  public synchronized void delItem (int position);
public synchronized void delItems (int start, int end);  public synchronized void deselect (int index);
public String getItem (int index);
public int getItemCount(); public synchronized String[] getItems(); public Dimension getMinimumSize(); public Dimension getMinimumSize (int rows); public Dimension getPreferredSize(); public Dimension getPreferredSize (int rows); public int getRows();
public synchronized int getSelectedIndex();
public synchronized int[] getSelectedIndexes();
public synchronized String getSelectedItem();
public synchronized String[] getSelectedItems();
public Object[] getSelectedObjects(); public int getVisibleIndex();
public boolean isIndexSelected(int index); public boolean isMultipleMode(); public boolean isSelected (int index);  public synchronized void makeVisible (int index);
public Dimension minimumSize();  public Dimension minimumSize (int rows);  public Dimension preferredSize();  public Dimension preferredSize (int rows);  public synchronized void remove (int position); public synchronized void remove (String item); public void removeActionListener (ActionListener l); public synchronized void removeAll(); public void removeItemListener (ItemListener l); public void removeNotify();
public synchronized void replaceItem (String newItem, int index);
public synchronized void select (int position);
public synchronized void setMultipleMode (boolean b); public synchronized void setMultipleSelections (boolean value);  // Protected Instance Methods protected String paramString(); protected void processActionEvent (ActionEvent e); protected void processEvent (AWTEvent e); protected void processItemEvent (ItemEvent e);
}

Constructors

List

public List()

• Description
• Constructs a List object in single-selection mode.

public List (int rows)

• Parameters
• • rows
  • Requested number of rows to display.
• Description
• Constructs a List object with the specified number of rows, in single-selection mode.

public List (int rows, boolean multipleSelections)

• Parameters
• • rows
  • Requested number of rows to display.
  • multipleSelections
  • true to allow multiple selections; false to select one item at a time.
• Description
• Constructs a List object.

Instance Methods

add

public void add (String item)

• Parameters
• • item
  • Text for entry to add.
• Description
• Adds a new entry to the available choices.

public synchronized void add (String item, int index)

• Parameters
• • item
  • Text for entry to add.
  • index
  • Position at which to add entry; the first entry has an index of zero.
• Description
• Adds a new entry to the available choices at the designated position.

addActionListener

public void addActionListener (ActionListener l)

• Parameters
• • l
  • An object that implements the ActionListener interface.
• Description
• Add a listener for the action event.

addItem

public void addItem (String item)

• Parameters
• • item
  • Text for entry to add.
• Description
• Replaced by add(String).

public synchronized void addItem (String item, int index)

• Parameters
• • item
  • Text for entry to add.
  • index
  • Position at which to add entry; the first entry has an index of zero.
• Description
• Replaced by add(String, int).

addItemListener

public void addItemListener (ItemListener l)

• Parameters
• • l
  • The listener to be added.
• Implements
• ItemSelectable.addItemListener(ItemListener l)
• Description
• Adds a listener for the ItemEvent objects this List fires off.

addNotify

public void addNotify()

• Overrides
• Component.addNotify()
• Description
• Creates List's peer.

allowsMultipleSelections

public boolean allowsMultipleSelections()

• Returns
• true if multi-selection active, false otherwise. Replaced by isMultipleMode().

clear

public synchronized void clear()

• Description
• Clears all the entries out of the List. Replaced by removeAll().

countItems

public int countItems()

• Returns
• Number of items in the List. Replaced by getItemCount().

delItem

public synchronized void delItem (int position)

• Parameters
• • position
  • Position of item to delete.
• Description
• Removes a single entry from the List. Replaced by remove(int) and remove(String).

delItems

public synchronized void delItems (int start, int end)

• Parameters
• • start
  • Starting position of entries to delete.
  • end
  • Ending position of entries to delete.
• Description
• Removes a set of entries from the List.

deselect

public synchronized void deselect (int index)

• Parameters
• • index
  • Position to deselect.
• Description
• Deselects the entry at the designated position, if selected.

getItem

public String getItem (int index)

• Parameters
• • index
  • Position of entry to get.
• Throws
• • ArrayIndexOutOfBoundsException
  • If index is invalid.
• Returns
• String for entry at given position.

getItemCount

public int getItemCount()

• Returns
• Number of items in the List.

getItems

public String[] getItems()

• Returns
• The string items in the List.

getMinimumSize

public Dimension getMinimumSize()

• Returns
• The minimum dimensions of the List.

public Dimension getMinimumSize (int rows)

• Parameters
• • rows
  • Number of rows within List to size.
• Returns
• The minimum dimensions of a List of the given size.

getPreferredSize

public Dimension getPreferredSize()

• Returns
• The preferred dimensions of the List.

public Dimension getPreferredSize (int rows)

• Parameters
• • rows
  • Number of rows within List to size.
• Returns
• The preferred dimensions of a List of the given size.

getRows

public int getRows()

• Returns
• Returns number of rows requested to be displayed in List.

getSelectedIndex

public synchronized int getSelectedIndex()

• Returns
• Position of currently selected entry, or -1 if nothing is selected, or if multiple entries are selected.

getSelectedIndexes

public synchronized int[] getSelectedIndexes()

• Returns
• An array whose elements are the indices of the currently selected entries.

getSelectedItem

public synchronized String getSelectedItem()

• Returns
• Currently selected entry as a String, or null if nothing is selected, or if multiple entries are selected.

getSelectedItems

public synchronized String[] getSelectedItems()

• Returns
• An array of strings whose elements are the labels of the currently selected entries.

getSelectedObjects

public Object[] getSelectedObjects()

• Implements
• ItemSelectable.getSelectedObjects()
• Returns
• An array of strings whose elements are the labels of the currently selected entries.

getVisibleIndex

public int getVisibleIndex()

• Returns
• The last index from a call to makeVisible().

isIndexSelected

public boolean isIndexSelected (int index)

• Parameters
• • index
  • Position to check.
• Returns
• true if index selected, false otherwise.
• Description
• Checks to see if a particular entry is currently selected.

isMultipleMode

public boolean isMultipleMode()

• Returns
• true if multiple selection is allowed, false otherwise.

isSelected

public boolean isSelected (int index)

• Parameters
• • index
  • Position to check.
• Returns
• true if index selected, false otherwise.
• Description
• Checks to see if a particular entry is currently selected. Replaced by isIndexSelected(int).

makeVisible

public synchronized void makeVisible (int index)

• Parameters
• • index
  • Position to make visible on screen.
• Description
• Ensures an item is displayed on the screen.

minimumSize

public Dimension minimumSize()

• Returns
• The minimum dimensions of the List. Replaced by getMinimumSize().

public Dimension minimumSize (int rows)

• Parameters
• • rows
  • Number of rows within List to size.
• Returns
• The minimum dimensions of a List of the given size. Replaced by getMinimumSize(int).

preferredSize

public Dimension preferredSize()

• Returns
• The preferred dimensions of the List. Replaced by getPreferredSize().

public Dimension preferredSize (int rows)

• Parameters
• • rows
  • Number of rows within List to size.
• Returns
• The preferred dimensions of a List of the given size. Replaced by getPreferredSize(int).

remove

public synchronized void remove (int position)

• Parameters
• • position
  • Position of item to remove.
• Description
• Removes a single entry from the List.

public synchronized void remove (String item)

• Parameters
• • item
  • Item to remove.
• Throws
• • IllegalArgumentException
  • If item is not in the List.
• Description
• Removes a single entry from the List.

removeActionListener

public void removeActionListener (ActionListener l)

• Parameters
• • l
  • One of this List's ActionListeners.
• Description
• Remove an action event listener.

removeAll

public synchronized removeAll()

• Description
• Removes all items from the List.

removeItemListener

public void removeItemListener (ItemListener l)

• Parameters
• • l
  • The listener to be removed.
• Implements
• ItemSelectable.removeItemListener (ItemListener l)
• Description
• Removes the specified ItemListener so it will not receive ItemEvent objects from this List.

removeNotify

public void removeNotify()

• Description
• Destroys the peer of the List.

replaceItem

public synchronized void replaceItem (String newItem, int index)

• Parameters
• • newItem
  • Label for entry to add.
  • index
  • Position of entry to replace.
• Description
• Replaces the contents at a particular position with a new entry.

select

public synchronized void select (int position)

• Parameters
• • position
  • Position to make selected entry.
• Description
• Makes the given entry the selected one for the List.

setMultipleMode

public synchronized void setMultipleMode (boolean b)

• Parameters
• • b
  • true to enable multiple selections; false to disable multiple selections.
• Description
• Changes List's selection mode based upon flag.

setMultipleSelections

public synchronized void setMultipleSelections (boolean value)

• Parameters
• • value
  • true to enable multiple selections; false to disable multiple selections.
• Description
• Changes List's selection mode based upon flag. Replaced by setMultipleMode(boolean).

Protected Instance Methods

paramString

protected String paramString()

• Returns
• String with current settings of List.
• Overrides
• Component.paramString()
• Description
• Helper method for toString() to generate string of current settings.

processActionEvent

protected void processActionEvent (ActionEvent e)

• Parameters
• • e
  • The action event to process.
• Description
• Action events are passed to this method for processing. Normally, this method is called by processEvent().

processEvent

protected void processEvent (AWTEvent e)

• Parameters
• • e
  • The event to process.
• Description
• Low-level AWTEvents are passed to this method for processing.

processItemEvent

protected void processItemEvent(ItemEvent e)

• Parameters
• • e
  • The item event to process.
• Description
• Item events are passed to this method for processing. Normally, this method is called by processEvent().

See Also

Component, Dimension, ItemSelectable, String