Previous
Java API
Index
Next
| Package java.awt |
Previous |
Java API |
Index |
Next |
public class java.awt.List
extends java.awt.Component
{
// Constructors
public List();
public List(int rows, boolean multipleSelections);
// Methods
public void addItem(String item);
public void addItem(String item, int index);
public void addNotify();
public boolean allowsMultipleSelections();
public void clear();
public int countItems();
public void delItem(int position);
public void delItems(int start, int end);
public void deselect(int index);
public String getItem(int index);
public int getRows();
public int getSelectedIndex();
public int[] getSelectedIndexes();
public String getSelectedItem();
public String[] getSelectedItems();
public int getVisibleIndex();
public boolean isSelected(int index);
public void makeVisible(int index);
public Dimension minimumSize();
public Dimension minimumSize(int rows);
protected String paramString();
public Dimension preferredSize();
public Dimension preferredSize(int rows);
public void removeNotify();
public void replaceItem(String newValue, int index);
public void select(int index);
public void setMultipleSelections(boolean v);
}
The List component presents the user with a scrolling list of text items. The list can be set up either so that the user can pick one item or to pick multiple items.
For example, the code:
List l = new List(4, false);
l.addItem("Mercury");
l.addItem("Venus");
l.addItem("Earth");
l.addItem("JavaSoft");
l.addItem("Mars");
l.addItem("Jupiter");
l.addItem("Saturn");
l.addItem("Uranus");
l.addItem("Neptune");
l.addItem("Pluto");
add(l);
produces the following scrolling list:
Clicking(1) on an item that isn't selected selects it. Clicking on an item that is already selected deselects it. In the above example, since the second argument when creating the new scrolling list is false, only one item can be selected at a time from the scrolling list. Selecting any item causes any other selected item to be automatically deselected.
When an item is clicked and becomes selected, AWT sends a list select event to the scrolling list. When an item is clicked and becomes deselected, AWT sends a list deselect event to the scrolling list. The event's target is the scrolling list, and its object is an Integer giving the index of the item in the list.
When the user double clicks on an item in a scrolling list, AWT sends an action event to the scrolling list after the list select or deselect event. The event's target is the scrolling list, and its object is the string label of the item selected or deselected.
When the user hits return inside a scrolling list, AWT also sends an action event to the scrolling list. The event's target is the scrolling list, and its object is the string label of the last item selected or deselected in the scrolling list.
If an application wants to perform some action based on an item being selected or deselected, it must override the handleEvent method of the scrolling list or of one of its containing windows. The code to perform that should be of the form:
public boolean handleEvent(Event event) {
switch(event.id) {
case Event.LIST_SELECT:
<do something if event.target is scrolling list>
case Event.LIST_DESELECT:
<do something if event.target is scrolling list>
default:
return super.handleEvent(event);
}
}
If the application wants to perform some action based on the user double clicking or hitting the return key, it should override the action method of the scrolling list or of one of its containing windows. Alternatively, it can override the handleEvent method as above and check to see if the event's id field is Event.ACTION_EVENT.
For multiple-selection scrolling lists, it is considered a better user interface to use an external event (such as clicking on a button) to trigger the action.
public List()Creates a new scrolling list. Initially there are no visible lines, and only one item can be selected from the list.
public List(int rows, boolean multipleSelections)Creates a new scrolling list initialized to display the specified number of rows. If the multipleSelections argument is true, then the user can select multiple items at a time from the list. If it is false, only one item at a time can be selected.
Parameter Description rows the number of items to show. multipleSelections if true then multiple selections are allowed; otherwise, only one item can be selected at a time.
public void addItem(String item)Adds the specified string to the end of this scrolling list.
Parameter Description item the string to be added
public void addItem(String item, int index)Adds the specified string to this scrolling list at the specified position.
The index argument is 0-based. If the index is -1, or greater than or equal to the number of items already in the list, then the item is added at the end of this list.
Parameter Description item the string to be added index the position at which to put in the item
public void addNotify()This method calls the createList method of this object's toolkit in order to create a ListPeer for this scrolling list. This peer allows the application to change the look of a scrolling list without changing its functionality.
Most applications do not call this method directly.
Overrides:
addNotify in class Component .
public boolean allowsMultipleSelections()Return Value:
Returns true if this scrolling list allows multiple selections; false otherwise.
See Also: setMultipleSelections .
public void clear()Removes all items from this scrolling list.
public int countItems()Return Value:
Returns the number of items in this list.
See Also: getItem .
public void delItem(int position)Deletes the item at the specified position from this scrolling list.
Parameter Description position the index of the item to delete
public void delItems(int start, int end)Deletes the items in the range start £ item £ end from this scrolling list.
Parameter Description start the index of the first element to delete end the index of the last element to delete
public void deselect(int index)Deselects the item at the specified index of this scrolling list.
If the item at the specified index is not selected, or if the index is out of range, then the operation is ignored.
Parameter Description index the position of the item to deselect See Also: select getSelectedItem isSelected .
public String getItem(int index)Return Value:
Returns the string of this scrolling list at the specified index.
Parameter Description index the position of the item See Also: countItems .
public int getRows()Return Value:
Returns the number of visible lines in this scrolling list.
public int getSelectedIndex()Return Value:
Returns the index of the selected item on this scrolling list, or -1 if either no items are selected or more than one item is selected.
See Also: select deselect isSelected .
public int[] getSelectedIndexes()Return Value:
Returns an array of the selected indexes of this scrolling list.
See Also: select deselect isSelected .
public String getSelectedItem()Return Value:
Returns the selected item on this scrolling list, or null if either no items are selected or more than one item is selected.
See Also: select deselect isSelected .
public String[] getSelectedItems()Return Value:
Returns an array of the selected items on this scrolling list.
See Also: select deselect isSelected .
public int getVisibleIndex()Return Value:
Returns the index of the item in this scrolling list that was last made visible by the make-Visible method .
public boolean isSelected(int index)Determines if a specified item in this scrolling list is selected. No error occurs if the index argument is less than 0 or greater than or equal to the number of items in this scrolling list.
Return Value:
Returns true if the item at the specified index has been selected; false otherwise.
Parameter Description index the item to be checked
public void makeVisible(int index)Forces the item at the specified index in this scrolling list to be visible.
No error occurs if the index argument is less than 0 or greater than or equal to the number of items in this scrolling list.
Parameter Description index the position of the item See Also: getVisibleIndex .
public Dimension minimumSize()Determines the minimum size of this scrolling list. If the application has specified the number of visible rows, and that number is greater than 0, the peer's minimumSize method is called with the number of rows in order to determine the minimum size.
If this scrolling list does not have a peer, or if the number of visible rows is less than or equal to zero, the superclass's minimumSize method is called to determine the minimum size.
Return Value:
Returns the minimum dimensions needed to display this scrolling list.
Overrides:
minimumSize in class Component .
public Dimension minimumSize(int rows)Determines the minimum size of a scrolling list with the specified number of rows. This scrolling lists's peer's minimumSize method is called with the number of rows in order to determine the minimum size.
If this scrolling list does not have a peer the superclass's minimumSize method is called to determine the minimum size.
Return Value:
Returns the minimum dimensions needed to display the specified number of rows in a scrolling list.
Parameter Description rows number of rows
protected String paramString()Returns the parameter string representing the state of this scrolling list. This string is useful for debugging.
Return Value:
Returns the parameter string of this scrolling list.
Overrides:
paramString in class Component .
public Dimension preferredSize()Determines the preferred size of this scrolling list. If the application has specified the number of visible rows, and that number is greater than 0, the peer's preferredSize method is called with the number of rows in order to determine the preferred size.
If this scrolling list does not have a peer, or if the number of visible rows is less than or equal to zero, the superclass's preferredSize method is called to determine the preferred size.
Return Value:
Returns the preferred dimensions for displaying this scrolling list.
Overrides:
preferredSize in class Component .
public Dimension preferredSize(int rowsn)Determines the preferred size of a scrolling list with the specified number of rows. This scrolling lists's peer's preferredSize method is called with the number of rows in order to determine the preferred size.
If this scrolling list does not have a peer the superclass's preferredSize method is called to determine the preferred size.
Return Value:
Returns the preferred dimensions for displaying the specified number of rows.
Parameter Description rows number of rows
public void removeNotify()Notifies this scrolling list to destroy its peer.
Overrides:
removeNotify in class Component .
public void replaceItem(String newValue, int index)Replaces the item at the given index in the scrolling list with the new string.
Parameter Description newValue the new value index the position
public void select(int index)Selects the item at the specified index in the scrolling list.
Parameter Description index the position of the item to select See Also: getSelectedItem deselect isSelected .
public void setMultipleSelections(boolean v)Sets whether this scolling list allows multiple selections.
Parameter Description v if true then multiple selections are allowed; otherwise, only one item can be selected at a time. See Also: allowsMultipleSelections . (
1)In Java 1.0, the AWT does not send mouse, keyboard, or focus events to a scrolling list. In Java 1.1, the AWT sends to the scrolling list all mouse, keyboard, and focus events that occur over it.
© 1996 Sun Microsystems, Inc. All rights reserved.