[Chapter 19] List
Author: John Zukowski
Date: Thu Jul 31 15:14:14 1997

#

| Chapter 19 java.awt Reference |

# List

## Name

List

##

## 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 `ActionListener`s.

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 `AWTEvent`s 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`

LayoutManager2 |  | MediaTracker