JList

Overview

Package

Class

Tree

Deprecated

Index

Help

Codase Click

search sample or example code,

search definition,

search google

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JList

java.lang.Object   
  java.awt.Component   
      java.awt.Container   
          javax.swing.JComponent   
              javax.swing.JList

All Implemented Interfaces:: ImageObserver , MenuContainer , Serializable , Accessible , Scrollable

public class JList
extends JComponent
implements Scrollable , Accessible
extends JComponent
implements Scrollable , Accessible

A component that allows the user to select one or more objects from a list. A separate model, ListModel, represents the contents of the list. It's easy to display an array or vector of objects, using a JList constructor that builds a ListModel instance for you:

 // Create a JList that displays the strings in data[]

 String[] data = {"one", "two", "three", "four"};
 JList dataList = new JList(data);
 
 // The value of the JList model property is an object that provides
 // a read-only view of the data.  It was constructed automatically.

 for(int i = 0; i < dataList.getModel().getSize(); i++) {
     System.out.println(dataList.getModel().getElementAt(i));
 }

 // Create a JList that displays the superclass of JList.class.
 // We store the superclasses in a java.util.Vector.

 Vector superClasses = new Vector();
 Class rootClass = javax.swing.JList.class;
 for(Class cls = rootClass; cls != null; cls = cls.getSuperclass()) {
     superClasses.addElement(cls);
 }
 JList classList = new JList(superClasses);

JList doesn't support scrolling directly. To create a scrolling list you make the JList the viewport view of a JScrollPane. For example:

 JScrollPane scrollPane = new JScrollPane(dataList);
 // Or in two steps:
 JScrollPane scrollPane = new JScrollPane();
 scrollPane.getViewport().setView(dataList);

By default the JList selection model allows any combination of items to be selected at a time, using the constant MULTIPLE_INTERVAL_SELECTION. The selection state is actually managed by a separate delegate object, an instance of ListSelectionModel. However JList provides convenient properties for managing the selection.

 String[] data = {"one", "two", "three", "four"};
 JList dataList = new JList(data);

 dataList.setSelectedIndex(1);  // select "two"
 dataList.getSelectedValue();   // returns "two"

The contents of a JList can be dynamic, in other words, the list elements can change value and the size of the list can change after the JList has been created. The JList observes changes in its model with a swing.event.ListDataListener implementation. A correct implementation of ListModel notifies it's listeners each time a change occurs. The changes are characterized by a swing.event.ListDataEvent, which identifies the range of list indices that have been modified, added, or removed. Simple dynamic-content JList applications can use the DefaultListModel class to store list elements. This class implements the ListModel interface and provides the java.util.Vector API as well. Applications that need to provide custom ListModel implementations can subclass AbstractListModel, which provides basic ListDataListener support. For example:

 // This list model has about 2^16 elements.  Enjoy scrolling.

 
 ListModel bigData = new AbstractListModel() {
     public int getSize() { return Short.MAX_VALUE; }
     public Object getElementAt(int index) { return "Index " + index; }
 };

 JList bigDataList = new JList(bigData);

 // We don't want the JList implementation to compute the width
 // or height of all of the list cells, so we give it a string
 // that's as big as we'll need for any cell.  It uses this to
 // compute values for the fixedCellWidth and fixedCellHeight
 // properties.

 bigDataList.setPrototypeCellValue("Index 1234567890");

JList uses a java.awt.Component, provided by a delegate called the cellRendererer, to paint the visible cells in the list. The cell renderer component is used like a "rubber stamp" to paint each visible row. Each time the JList needs to paint a cell it asks the cell renderer for the component, moves it into place using setBounds() and then draws it by calling its paint method. The default cell renderer uses a JLabel component to render the string value of each component. You can substitute your own cell renderer, using code like this:

  // Display an icon and a string for each object in the list.

 
 class MyCellRenderer extends JLabel implements ListCellRenderer {
     final static ImageIcon longIcon = new ImageIcon("long.gif");
     final static ImageIcon shortIcon = new ImageIcon("short.gif");

     // This is the only method defined by ListCellRenderer.
     // We just reconfigure the JLabel each time we're called.

     public Component getListCellRendererComponent(
       JList list,
       Object value,            // value to display
       int index,               // cell index
       boolean isSelected,      // is the cell selected
       boolean cellHasFocus)    // the list and the cell have the focus
     {
         String s = value.toString();
         setText(s);
         setIcon((s.length() > 10) ? longIcon : shortIcon);
           if (isSelected) {
             setBackground(list.getSelectionBackground());
               setForeground(list.getSelectionForeground());
           }
         else {
               setBackground(list.getBackground());
               setForeground(list.getForeground());
           }
           setEnabled(list.isEnabled());
           setFont(list.getFont());
         setOpaque(true);
         return this;
     }
 }

 String[] data = {"one", "two", "three", "four"};
 JList dataList = new JList(data);
 dataList.setCellRenderer(new MyCellRenderer());

JList doesn't provide any special support for handling double or triple (or N) mouse clicks however it's easy to handle them using a MouseListener. Use the JList method locationToIndex() to determine what cell was clicked. For example:

 final JList list = new JList(dataModel);
 MouseListener mouseListener = new MouseAdapter() {
     public void mouseClicked(MouseEvent e) {
         if (e.getClickCount() == 2) {
             int index = list.locationToIndex(e.getPoint());
             System.out.println("Double clicked on Item " + index);
          }
     }
 };
 list.addMouseListener(mouseListener);

Note that in this example the dataList is final because it's referred to by the anonymous MouseListener class.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans^TM has been added to the java.beans package. Please see XMLEncoder .

See How to Use Lists in The Java Tutorial for further documentation. Also see the article Advanced JList Programming in The Swing Connection.

See Also:: ListModel , AbstractListModel , DefaultListModel , ListSelectionModel , DefaultListSelectionModel , ListCellRenderer , Serialized Form

Nested Class Summary
`protected class`	`JList.AccessibleJList` This class implements accessibility support for the `JList` class.

Nested classes/interfaces inherited from class javax.swing.JComponent
`JComponent.AccessibleJComponent`

Nested classes/interfaces inherited from class java.awt.Container
`Container.AccessibleAWTContainer`

Nested classes/interfaces inherited from class java.awt.Component
`Component.AccessibleAWTComponent , Component.BltBufferStrategy , Component.FlipBufferStrategy`

Field Summary
`static int`	`HORIZONTAL_WRAP` Indicates "newspaper style" with the cells flowing horizontally then vertically.
`static int`	`VERTICAL` Indicates the default layout: one column of cells.
`static int`	`VERTICAL_WRAP` Indicates "newspaper style" layout with the cells flowing vertically then horizontally.

Fields inherited from class javax.swing.JComponent
`accessibleContext , listenerList , TOOL_TIP_TEXT_KEY , ui , UNDEFINED_CONDITION , WHEN_ANCESTOR_OF_FOCUSED_COMPONENT , WHEN_FOCUSED , WHEN_IN_FOCUSED_WINDOW`

Fields inherited from class java.awt.Component
`BOTTOM_ALIGNMENT , CENTER_ALIGNMENT , LEFT_ALIGNMENT , RIGHT_ALIGNMENT , TOP_ALIGNMENT`

Fields inherited from interface java.awt.image.ImageObserver
`ABORT , ALLBITS , ERROR , FRAMEBITS , HEIGHT , PROPERTIES , SOMEBITS , WIDTH`

Constructor Summary
`JList ()` Constructs a `JList` with an empty model.
`JList (ListModel dataModel)` Constructs a `JList` that displays the elements in the specified, non-`null` model.
`JList (Object [] listData)` Constructs a `JList` that displays the elements in the specified array.
`JList (Vector <?> listData)` Constructs a `JList` that displays the elements in the specified `Vector`.

Method Summary
`void`	`addListSelectionListener (ListSelectionListener listener)` Adds a listener to the list that's notified each time a change to the selection occurs.
`void`	`addSelectionInterval (int anchor, int lead)` Sets the selection to be the union of the specified interval with current selection.
`void`	`clearSelection ()` Clears the selection - after calling this method `isSelectionEmpty` will return true.
`protected ListSelectionModel`	`createSelectionModel ()` Returns an instance of `DefaultListSelectionModel`.
`void`	`ensureIndexIsVisible (int index)` Scrolls the viewport to make the specified cell completely visible.
`protected void`	`fireSelectionValueChanged (int firstIndex, int lastIndex, boolean isAdjusting)` Notifies `JList` `ListSelectionListener`s that the selection model has changed.
`AccessibleContext`	`getAccessibleContext ()` Gets the AccessibleContext associated with this JList.
`int`	`getAnchorSelectionIndex ()` Returns the first index argument from the most recent `addSelectionModel` or `setSelectionInterval` call.
`Rectangle`	`getCellBounds (int index0, int index1)` Returns the bounds of the specified range of items in `JList` coordinates.
`ListCellRenderer`	`getCellRenderer ()` Returns the object that renders the list items.
`boolean`	`getDragEnabled ()` Gets the `dragEnabled` property.
`int`	`getFirstVisibleIndex ()` Returns the index of the first visible cell.
`int`	`getFixedCellHeight ()` Returns the fixed cell height value -- the value specified by setting the `fixedCellHeight` property, rather than that calculated from the list elements.
`int`	`getFixedCellWidth ()` Returns the fixed cell width value -- the value specified by setting the `fixedCellWidth` property, rather than that calculated from the list elements.
`int`	`getLastVisibleIndex ()` Returns the index of the last visible cell.
`int`	`getLayoutOrientation ()` Returns `JList.VERTICAL` if the layout is a single column of cells, or `JList.VERTICAL_WRAP` if the layout is "newspaper style" with the content flowing vertically then horizontally or `JList.HORIZONTAL_WRAP` if the layout is "newspaper style" with the content flowing horizontally then vertically.
`int`	`getLeadSelectionIndex ()` Returns the second index argument from the most recent `addSelectionInterval` or `setSelectionInterval` call.
`ListSelectionListener []`	`getListSelectionListeners ()` Returns an array of all the `ListSelectionListener`s added to this JList with addListSelectionListener().
`int`	`getMaxSelectionIndex ()` Returns the largest selected cell index.
`int`	`getMinSelectionIndex ()` Returns the smallest selected cell index.
`ListModel`	`getModel ()` Returns the data model that holds the list of items displayed by the `JList` component.
`int`	`getNextMatch (String prefix, int startIndex, Position.Bias bias)` Returns the next list element that starts with a prefix.
`Dimension`	`getPreferredScrollableViewportSize ()` Computes the size of the viewport needed to display `visibleRowCount` rows.
`Object`	`getPrototypeCellValue ()` Returns the cell width of the "prototypical cell" -- a cell used for the calculation of cell widths, because it has the same value as all other list items.
`int`	`getScrollableBlockIncrement (Rectangle visibleRect, int orientation, int direction)` Returns the distance to scroll to expose the next or previous block.
`boolean`	`getScrollableTracksViewportHeight ()` Returns true if this `JList` is displayed in a `JViewport` and the viewport is taller than `JList`'s preferred height, or if the layout orientation is `VERTICAL_WRAP` and the number of visible rows is <= 0; otherwise returns false.
`boolean`	`getScrollableTracksViewportWidth ()` Returns true if this `JList` is displayed in a `JViewport` and the viewport is wider than `JList`'s preferred width; or if the layout orientation is `HORIZONTAL_WRAP` and the visible row count is <= 0; otherwise returns false.
`int`	`getScrollableUnitIncrement (Rectangle visibleRect, int orientation, int direction)` Returns the distance to scroll to expose the next or previous row (for vertical scrolling) or column (for horizontal scrolling).
`int`	`getSelectedIndex ()` Returns the first selected index; returns -1 if there is no selected item.
`int[]`	`getSelectedIndices ()` Returns an array of all of the selected indices in increasing order.
`Object`	`getSelectedValue ()` Returns the first selected value, or `null` if the selection is empty.
`Object []`	`getSelectedValues ()` Returns an array of the values for the selected cells.
`Color`	`getSelectionBackground ()` Returns the background color for selected cells.
`Color`	`getSelectionForeground ()` Returns the selection foreground color.
`int`	`getSelectionMode ()` Returns whether single-item or multiple-item selections are allowed.
`ListSelectionModel`	`getSelectionModel ()` Returns the value of the current selection model.
`String`	`getToolTipText (MouseEvent event)` Overrides `JComponent`'s `getToolTipText` method in order to allow the renderer's tips to be used if it has text set.
`ListUI`	`getUI ()` Returns the look and feel (L&F) object that renders this component.
`String`	`getUIClassID ()` Returns the suffix used to construct the name of the look and feel (L&F) class used to render this component.
`boolean`	`getValueIsAdjusting ()` Returns the value of the data model's `isAdjusting` property.
`int`	`getVisibleRowCount ()` Returns the preferred number of visible rows.
`Point`	`indexToLocation (int index)` Returns the origin of the specified item in `JList` coordinates.
`boolean`	`isSelectedIndex (int index)` Returns true if the specified index is selected.
`boolean`	`isSelectionEmpty ()` Returns true if nothing is selected.
`int`	`locationToIndex (Point location)` Convert a point in `JList` coordinates to the closest index of the cell at that location.
`protected String`	`paramString ()` Returns a string representation of this `JList`.
`void`	`removeListSelectionListener (ListSelectionListener listener)` Removes a listener from the list that's notified each time a change to the selection occurs.
`void`	`removeSelectionInterval (int index0, int index1)` Sets the selection to be the set difference of the specified interval and the current selection.
`void`	`setCellRenderer (ListCellRenderer cellRenderer)` Sets the delegate that's used to paint each cell in the list.
`void`	`setDragEnabled (boolean b)` Sets the `dragEnabled` property, which must be `true` to enable automatic drag handling (the first part of drag and drop) on this component.
`void`	`setFixedCellHeight (int height)` Sets the height of every cell in the list.
`void`	`setFixedCellWidth (int width)` Sets the width of every cell in the list.
`void`	`setLayoutOrientation (int layoutOrientation)` Defines the way list cells are layed out.
`void`	`setListData (Object [] listData)` Constructs a `ListModel` from an array of objects and then applies `setModel` to it.
`void`	`setListData (Vector`

javax.swing Class JList

javax.swing
Class JList