Класс JList<E>

@JavaBean(defaultProperty="UI",
          description="A component which allows for the selection of one or more objects from a list.")
public class JList<E>
extends JComponent
implements Scrollable, Accessible

Компонент, отображающий список объектов и позволяющий пользователю выбрать один или несколько элементов. Отдельный модель, ListModel, поддерживает содержимое списка.

Легко отобразить массив или вектор объектов, используя конструктор JList, который автоматически создаёт для вас экземпляр read-only ListModel:

// Create a JList that displays strings from an array

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

 // Create a JList that displays the superclasses of JList.class, by
 // creating it with a Vector populated with this data

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

 // The automatically created model is stored in JList's "model"
 // property, which you can retrieve

 ListModel<Class<?>> model = myList.getModel();
 for(int i = 0; i < model.getSize(); i++) {
     System.out.println(model.getElementAt(i));
 }

Модель ListModel может быть предоставлена непосредственно в JList с помощью конструктора или метода setModel. Содержимое не обязательно статическое — количество элементов и их значения могут изменяться со временем. Правильная реализация ListModel уведомляет набор javax.swing.event.ListDataListener, которые были добавлены к ней, каждый раз, когда происходит изменение. Эти изменения характеризуются javax.swing.event.ListDataEvent, который определяет диапазон индексов списка, которые были изменены, добавлены или удалены. JList's ListUI отвечает за поддержание визуального представления в актуальном состоянии с помощью прослушивания изменений модели.

Простые приложения с динамическим содержимым, JList, могут использовать класс DefaultListModel для управления элементами списка. Этот класс реализует интерфейс ListModel и также предоставляет API, подобный java.util.Vector. Приложения, которым нужна более настраиваемая реализация ListModel, могут вместо этого наследоваться от AbstractListModel, который обеспечивает базовую поддержку управления и уведомления слушателей. Например, read-only реализация AbstractListModel:

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

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

Состояние выбора JList управляется другой отдельной моделью, экземпляром ListSelectionModel. JList инициализируется моделью выбора при создании и также содержит методы для запроса или установки этой модели выбора. Кроме того, JList предоставляет удобные методы для лёгкого управления выбором. Эти методы, такие как setSelectedIndex и getSelectedValue, являются обёртками, которые заботятся о деталях взаимодействия с моделью выбора. По умолчанию, модель выбора JList настроена так, чтобы разрешать любой комбинацию выбранных элементов одновременно; режим выбора MULTIPLE_INTERVAL_SELECTION. Режим выбора может быть изменён непосредственно в модели выбора или через обёртку JList. Ответственность за обновление модели выбора в ответ на жесты пользователя лежит на ListUI списка.

Правильная реализация ListSelectionModel уведомляет набор javax.swing.event.ListSelectionListener, которые были добавлены к ней, каждый раз, когда происходит изменение выбора. Эти изменения характеризуются javax.swing.event.ListSelectionEvent, который определяет диапазон изменения выбора.

Предпочтительный способ прослушивания изменений выбора в списке — добавление ListSelectionListener напрямую к JList. JList затем следит за моделью выбора и уведомляет ваших слушателей о изменениях.

Ответственность за прослушивание изменений выбора для поддержания визуального представления списка в актуальном состоянии лежит на ListUI списка.

Отрисовка ячеек в JList обрабатывается делегатом, называемым рендерером ячеек, установленным в списке как свойство cellRenderer. Рендерер предоставляет java.awt.Component, который используется как "штамп" для отрисовки ячеек. Каждый раз, когда ячейка нуждается в отрисовке, ListUI списка запрашивает у рендерера ячейки компонент, помещает его на место и заставляет его отрисовать содержимое ячейки с помощью метода paint. По умолчанию рендерер ячеек, использующий компонент JLabel для отрисовки, устанавливается ListUI списка. Вы можете заменить свой собственный рендерер, используя код такого рода:

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

 class MyCellRenderer extends JLabel implements ListCellRenderer<Object> {
     static final ImageIcon longIcon = new ImageIcon("long.gif");
     static final 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,           // the list
       Object value,            // value to display
       int index,               // cell index
       boolean isSelected,      // is the cell selected
       boolean cellHasFocus)    // does the cell have 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;
     }
 }

 myList.setCellRenderer(new MyCellRenderer());

Ещё одна задача рендерера ячеек — помощь в определении информации о размере. По умолчанию, ListUI списка определяет размер ячеек, запрашивая предпочтительный размер для каждого элемента списка. Это может быть дорого для больших списков. Чтобы избежать этих вычислений, вы можете установить fixedCellWidth и fixedCellHeight в списке или иметь эти значения автоматически рассчитанными на основе одного прототипа:

JList<String> bigDataList = new JList<String>(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 не реализует прокрутку напрямую. Чтобы создать список с прокруткой, сделайте его областью просмотра JScrollPane. Например:

JScrollPane scrollPane = new JScrollPane(myList);

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

JList не предоставляет специальной обработки двойных или тройных (или N) щелчков мышью, но легко добавить MouseListener, если вы хотите предпринять действия при этих событиях. Используйте метод locationToIndex, чтобы определить, какая ячейка была нажата. Например:

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);

Предупреждение: Swing не потокобезопасен. Дополнительную информацию см. в Политике потоков Swing.

Предупреждение: Сериализованные объекты этого класса не будут совместимы с будущими версиями Swing. Текущая поддержка сериализации подходит для кратковременного хранения или RMI между приложениями, использующими ту же версию Swing. Начиная с 1.4, поддержка долгосрочного хранения всех JavaBeans™ добавлена в пакет java.beans. Пожалуйста, обратитесь к XMLEncoder.

См. Как использовать списки в Java Tutorial для дополнительной документации.