Packages  This Package  Prev  Next  Index  

public  class  java.awt.List
    extends  java.awt.Component  (II-§1.10)
{
        // Constructors
    public List();	§1.27.1
    public List(int  rows, boolean  multipleSelections);	§1.27.2

        // Methods
    public void addItem(String  item);	§1.27.3
    public void addItem(String  item, int  index);	§1.27.4
    public void addNotify();	§1.27.5
    public boolean allowsMultipleSelections();	§1.27.6
    public void clear();	§1.27.7
    public int countItems();	§1.27.8
    public void delItem(int  position);	§1.27.9
    public void delItems(int  start, int  end);	§1.27.10
    public void deselect(int  index);	§1.27.11
    public String getItem(int  index);	§1.27.12
    public int getRows();	§1.27.13
    public int getSelectedIndex();	§1.27.14
    public int[] getSelectedIndexes();	§1.27.15
    public String getSelectedItem();	§1.27.16
    public String[] getSelectedItems();	§1.27.17
    public int getVisibleIndex();	§1.27.18
    public boolean isSelected(int  index);	§1.27.19
    public void makeVisible(int  index);	§1.27.20
    public Dimension minimumSize();	§1.27.21
    public Dimension minimumSize(int  rows);	§1.27.22
    protected String paramString();	§1.27.23
    public Dimension preferredSize();	§1.27.24
    public Dimension preferredSize(int  rows);	§1.27.25
    public void removeNotify();	§1.27.26
    public void replaceItem(String  newValue, int  index);	§1.27.27
    public void select(int  index);	§1.27.28
    public void setMultipleSelections(boolean  v);	§1.27.29
}

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¹ 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 (II-§1.14.18) to the scrolling list. When an item is clicked and becomes deselected, AWT sends a list deselect event (II-§1.14.17) to the scrolling list. The event's target is the scrolling list, and its object is an Integer (I-§1.8) 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 (II-§1.14.11) 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 (II-§1.14.11) 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);
    }
}    

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.

Creates a new scrolling list. Initially there are no visible lines, and only one item can be selected from the list.

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.

Parameters:

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.

Adds the specified string to the end of this scrolling list.

Parameters:

item - the string to be added

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.

Parameters:

item - the string to be added

index - the position at which to put in the item

This method calls the createList method (II-§1.41.13) of this object's toolkit (II-§1.10.20) in order to create a ListPeer (II-§3.12) 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 (II-§1.10.2).

Returns:

true if this scrolling list allows multiple selections; false otherwise.

See Also:

setMultipleSelections (II-§1.27.29).

Removes all items from this scrolling list.

See Also:

delItem (II-§1.27.9)
delItems (II-§1.27.10).

Returns:

the number of items in this list.

See Also:

getItem (II-§1.27.12).

Deletes the item at the specified position from this scrolling list.

Parameters:

position - the index of the item to delete

Deletes the items in the range from this scrolling list.

Parameters:

start - the index of the first element to delete

end - the index of the last element to delete

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.

Parameters:

index - the position of the item to deselect

See Also:

select (II-§1.27.28)
getSelectedItem (II-§1.27.16)
isSelected (II-§1.27.19).

Parameters:

index - the position of the item

Returns:

the string of this scrolling list at the specified index.

See Also:

countItems (II-§1.27.8).

Returns:

the number of visible lines in this scrolling list.

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 (II-§1.27.28)
deselect (II-§1.27.11)
isSelected (II-§1.27.19).

Returns:

an array of the selected indexes of this scrolling list.

See Also:

select (II-§1.27.28)
deselect (II-§1.27.11)
isSelected (II-§1.27.19).

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 (II-§1.27.28)
deselect (II-§1.27.11)
isSelected (II-§1.27.19).

Returns:

an array of the selected items on this scrolling list.

See Also:

select (II-§1.27.28)
deselect (II-§1.27.11)
isSelected (II-§1.27.19).

Returns:

the index of the item in this scrolling list that was last made visible by the make-Visible method (II-§1.27.20).

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.

Parameters:

index - the item to be checked

Returns:

true if the item at the specified index has been selected; false otherwise.

See Also:

select (II-§1.27.28)
deselect (II-§1.27.11)
isSelected (II-§1.27.19).

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.

Parameters:

index - the position of the item

See Also:

getVisibleIndex (II-§1.27.18).

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 (II-§3.12.7) 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 (II-§1.10.40) is called to determine the minimum size.

Returns:

the minimum dimensions needed to display this scrolling list.

Overrides:

minimumSize in class Component (II-§1.10.40).

Determines the minimum size of a scrolling list with the specified number of rows. This scrolling lists's peer's minimumSize method (II-§3.12.7) 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 (II-§1.10.40) is called to determine the minimum size.

Parameters:

rows - number of rows

Returns:

the minimum dimensions needed to display the specified number of rows in a scrolling list.

Returns the parameter string representing the state of this scrolling list. This string is useful for debugging.

Returns:

the parameter string of this scrolling list.

Overrides:

paramString in class Component (II-§1.10.51).

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 (II-§3.12.8) 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 (II-§1.10.40) is called to determine the preferred size.

Returns:

the preferred dimensions for displaying this scrolling list.

Overrides:

preferredSize in class Component (II-§1.10.53).

Determines the preferred size of a scrolling list with the specified number of rows. This scrolling lists's peer's preferredSize method (II-§3.12.8) 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 (II-§1.10.40) is called to determine the preferred size.

Parameters:

rows - number of rows

Returns:

the preferred dimensions for displaying the specified number of rows.

Notifies this scrolling list to destroy its peer.

Overrides:

removeNotify in class Component (II-§1.10.58).

Replaces the item at the given index in the scrolling list with the new string.

Parameters:

newValue - the new value

index - the position

Selects the item at the specified index in the scrolling list.

Parameters:

index - the position of the item to select

See Also:

getSelectedItem (II-§1.27.16)
deselect (II-§1.27.11)
isSelected (II-§1.27.19).

Sets whether this scolling list allows multiple selections.

Parameters:

v - if true then multiple selections are allowed; otherwise, only one item can be selected at a time.

See Also:

allowsMultipleSelections (II-§1.27.6).

Packages  This Package  Prev  Next  Index