Java AWT

Previous Chapter 19
java.awt Reference
Next
 

List

Name

List

[Graphic: Figure from the text]

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

Constructors

List

public List()

Description

Constructs a List object in single-selection mode.

public List (int rows) (New)

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) (New)

Parameters

item

Text for entry to add.

Description

Adds a new entry to the available choices.

public synchronized void add (String item, int index) (New)

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) (New)

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) (Deprecated)

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) (New)

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() (Deprecated)

Returns

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

clear

public synchronized void clear() (Deprecated)

Description

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

countItems

public int countItems() (Deprecated)

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) (Deprecated)

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() (New)

Returns

Number of items in the List.

getItems

public String[] getItems() (New)

Returns

The string items in the List.

getMinimumSize

public Dimension getMinimumSize() (New)

Returns

The minimum dimensions of the List.

public Dimension getMinimumSize (int rows) (New)

Parameters

rows

Number of rows within List to size.

Returns

The minimum dimensions of a List of the given size.

getPreferredSize

public Dimension getPreferredSize() (New)

Returns

The preferred dimensions of the List.

public Dimension getPreferredSize (int rows) (New)

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() (New)

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) (New)

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() (New)

Returns

true if multiple selection is allowed, false otherwise.

isSelected

public boolean isSelected (int index) (Deprecated)

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() (Deprecated)

Returns

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

public Dimension minimumSize (int rows) (Deprecated)

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() (Deprecated)

Returns

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

public Dimension preferredSize (int rows) (Deprecated)

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) (New)

Parameters

position

Position of item to remove.

Description

Removes a single entry from the List.

public synchronized void remove (String item) (New)

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) (New)

Parameters

l

One of this List's ActionListeners.

Description

Remove an action event listener.

removeAll

public synchronized removeAll() (New)

Description

Removes all items from the List.

removeItemListener

public void removeItemListener (ItemListener l) (New)

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) (New)

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) (Deprecated)

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) (New)

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) (New)

Parameters

e

The event to process.

Description

Low-level AWTEvents are passed to this method for processing.

processItemEvent

protected void processItemEvent(ItemEvent e) (New)

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


Previous Home Next
LayoutManager2 (New) Book Index MediaTracker

Java in a Nutshell Java Language Reference Java AWT Java Fundamental Classes Exploring Java