javax.swing
类 JList

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

所有已实现的接口：

ImageObserver, MenuContainer, Serializable, Accessible, Scrollable

public class JList
extends JComponent
implements Scrollable, Accessible

显示对象列表并且允许用户选择一个或多个项的组件。单独的模型 ListModel 维护列表的内容。

使用能自动构建只读 ListModel 实例的 JList 构造方法，可以方便地显示对象数组或对象 Vector：

 // Create a JList that displays strings from an array

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

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

 Vector superClasses = new Vector();
 Class rootClass = javax.swing.JList.class;
 for(Class cls = rootClass; cls != null; cls = cls.getSuperclass()) {
     superClasses.addElement(cls);
 }
 JList myList = new JList(superClasses);
 
 // The automatically created model is stored in JList's "model"
 // property, which you can retrieve

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

可通过构造方法或 setModel 方法向 JList 直接提供 ListModel。内容不需要是静态的，即项数和项值可以随时间而更改。正确的 ListModel 实现在每次发生更改时通知已添加到其中的 javax.swing.event.ListDataListener 集合。这些更改的特性由标识已修改、已添加或已移除的列表索引范围的 javax.swing.event.ListDataEvent 来描述。通过侦听该模型，JList 的 ListUI 负责保持可视化表示形式与更改一致。

简单的、动态内容的 JList 应用程序可以使用 DefaultListModel 类维护列表元素。此类实现 ListModel 接口，它还提供类似于 java.util.Vector 的 API。而需要自定义 ListModel 实现的应用程序可能希望子类化 AbstractListModel，它提供对管理和通知侦听器的基本支持。例如，AbstractListModel 的一个只读实现：

 // 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 的选择状态由另一个独立模型（ListSelectionModel 的一个实例）进行管理。JList 在构造时使用选择模型初始化，它还包含要查询或设置此选择模型的方法。此外，JList 提供了便捷的方法，可以很容易地管理选择。这些方法（如 setSelectedIndex 和 getSelectedValue）是维护与选择模型交互细节的覆盖方法。默认情况下，JList 的选择模型配置为允许一次选择项的任何组合；选择模式为 MULTIPLE_INTERVAL_SELECTION。选择模式可以在选择模型上进行直接更改，或者通过 JList 的覆盖方法更改。更新选择模型以响应用户动作的责任取决于列表的 ListUI。

正确的 ListSelectionModel 实现在每次选择发生更改时通知向其添加的 javax.swing.event.ListSelectionListener 集合。这些更改的特征由标识选择更改范围的 javax.swing.event.ListSelectionEvent 来描述。

侦听列表选择中更改的首选方法是向 JList 中直接添加 ListSelectionListener。然后，JList 负责侦听选择模型并向侦听器通知更改。

侦听选择更改以便使列表可视化表示形式保持最新的责任取决于列表的 ListUI。

绘制 JList 中的单元由称为单元渲染器（以 cellRenderer 属性的形式安装在列表上）的委托进行处理。渲染器提供一个其用法类似 "rubber stamp" 的 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 {
     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,              // 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 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");
 

 JScrollPane scrollPane = new JScrollPane(myList);

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

 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's Threading Policy。

警告：此类的序列化对象与以后的 Swing 版本不兼容。当前序列化支持适用于短期存储，或适用于在运行相同 Swing 版本的应用程序之间进行 RMI（Remote Method Invocation，远程方法调用）。从 1.4 版本开始，已在 java.beans 包中添加了支持所有 JavaBeans^TM 长期存储的功能。请参见 XMLEncoder。

有关更多文档，请参阅 The Java Tutorial 中的 How to Use Lists。另请参见 The Swing Connection 中的文章 Advanced JList Programming。 　

另请参见：

ListModel, AbstractListModel, DefaultListModel, ListSelectionModel, DefaultListSelectionModel, ListCellRenderer, DefaultListCellRenderer

VERTICAL

public static final int VERTICAL

指示单个列中单元的垂直布局；默认布局。

从以下版本开始：

1.4

另请参见：

setLayoutOrientation(int), 常量字段值

VERTICAL_WRAP

public static final int VERTICAL_WRAP

指示“报纸样式”布局，单元按先垂直后水平排列。

从以下版本开始：

1.4

另请参见：

setLayoutOrientation(int), 常量字段值

HORIZONTAL_WRAP

public static final int HORIZONTAL_WRAP

指示“报纸样式”布局，单元按先水平后垂直排列。

从以下版本开始：

1.4

另请参见：

setLayoutOrientation(int), 常量字段值

JList

public JList(ListModel dataModel)

根据指定的非 null 模型构造一个显示元素的 JList。所有 JList 构造方法都委托给此方法。

此构造方法向 ToolTipManager 注册列表，允许工具提示由单元渲染器提供。

参数：

dataModel - 该列表的模型

抛出：

IllegalArgumentException - 如果模型为 null

JList

public JList(Object[] listData)

构造一个 JList，使其显示指定数组中的元素。此构造方法为给定数组创建一个只读模型，然后委托给带有 ListModel　的构造方法。

如果试图将一个 null 值传递给此方法，则会导致不确定的行为，最有可能导致异常。创建的模型直接引用给定的数组。如果试图在构造列表之后修改该数组，则会导致不确定的行为。

参数：

listData - 要加载到数据模型中的 Object 的数组（为非 null）

JList

public JList(Vector<?> listData)

构造一个 JList，使其显示指定 Vector 中的元素。此构造方法为给定 Vector 创建一个只读模型，然后委托给带有 ListModel 的构造方法。

如果试图将一个 null 值传递给此方法，则会导致不确定的行为，最有可能导致异常。创建的模型直接引用给定的 Vector。如果试图在构造列表之后修改该 Vector，则会导致不确定的行为。

参数：

listData - 要加载到数据模型中的 Vector（为非 null）

JList

public JList()

构造一个具有空的、只读模型的 JList。

getUI

public ListUI getUI()

返回呈现此组件的外观对象 ListUI。

返回：

呈现此组件的 ListUI 对象

setUI

public void setUI(ListUI ui)

设置呈现此组件的外观对象 ListUI。

参数：

ui - ListUI 对象

另请参见：

UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()

重置 ListUI 属性，将其设置为当前外观所提供的值。如果当前单元渲染器由开发人员（而不是外观本身）安装，则这还会导致单元渲染器及其子单元渲染器被更新（通过在其上调用 SwingUtilities.updateComponentTreeUI）。

覆盖：

类 JComponent 中的 updateUI

另请参见：

UIManager.getUI(javax.swing.JComponent), SwingUtilities.updateComponentTreeUI(java.awt.Component)

getUIClassID

public String getUIClassID()

返回 "ListUI"，它是用于查找定义此组件外观的 javax.swing.plaf.ListUI 类名称的 UIDefaults 键。

覆盖：

类 JComponent 中的 getUIClassID

返回：

字符串 "ListUI"

另请参见：

JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getPrototypeCellValue

public Object getPrototypeCellValue()

返回“原型的”单元值，即用于计算单元的固定宽度和高度的值。如果没有这样的值，则可以返回 null。

返回：

prototypeCellValue 属性的值

另请参见：

setPrototypeCellValue(java.lang.Object)

setPrototypeCellValue

public void setPrototypeCellValue(Object prototypeCellValue)

设置 prototypeCellValue 属性，然后（如果新值为非 null）计算 fixedCellWidth 和 fixedCellHeight 属性：请求单元渲染器组件提供单元渲染器的给定值（及索引 0），并使用该组件的首选大小。

当由于列表过长而不允许 ListUI 计算每个单元的宽度/高度，并且已知某个单元值（所谓的原型）所占用的空间与任何其他单元一样多时，此方法很有用。

尽管 prototypeCellValue、fixedCellHeight 和 fixedCellWidth 三个属性都可以由此方法进行修改时，但只有 prototypeCellValue 属性更改时才发送 PropertyChangeEvent 通知。

要查看设置此属性的示例，请参见上述类描述。

此属性的默认值为 null。

这是一个 JavaBeans 绑定属性。

参数：

prototypeCellValue - 作为 fixedCellWidth 和 fixedCellHeight 的基础的值

另请参见：

getPrototypeCellValue(), setFixedCellWidth(int), setFixedCellHeight(int), Container.addPropertyChangeListener(java.beans.PropertyChangeListener)

getFixedCellWidth

public int getFixedCellWidth()

返回 fixedCellWidth 属性的值。

返回：

固定单元宽度

另请参见：

setFixedCellWidth(int)

setFixedCellWidth

public void setFixedCellWidth(int width)

设置一个固定值，将用于列表中每个单元的宽度。如果 width 为 -1，则可以通过将 getPreferredSize 应用到每个列表元素的单元渲染器组件来计算 ListUI 的单元宽度。

此属性的默认值为 -1。

这是一个 JavaBeans 绑定属性。

参数：

width - 将用于该列表中所有单元的宽度

另请参见：

setPrototypeCellValue(java.lang.Object), setFixedCellWidth(int), Container.addPropertyChangeListener(java.beans.PropertyChangeListener)

getFixedCellHeight

public int getFixedCellHeight()

返回 fixedCellHeight 属性的值。

返回：

固定单元高度

另请参见：

setFixedCellHeight(int)

setFixedCellHeight

public void setFixedCellHeight(int height)

设置一个固定值，将用于列表中每个单元的高度。如果 height 为 -1，则可以通过将 getPreferredSize 应用到每个列表元素的单元渲染器组件来计算 ListUI 的单元高度。

此属性的默认值为 -1。

这是一个 JavaBeans 绑定属性。

参数：

height - 将用于该列表中所有单元的高度

另请参见：

setPrototypeCellValue(java.lang.Object), setFixedCellWidth(int), Container.addPropertyChangeListener(java.beans.PropertyChangeListener)

getCellRenderer

public ListCellRenderer getCellRenderer()

返回负责绘制列表项的对象。

返回：

cellRenderer 属性的值

另请参见：

setCellRenderer(javax.swing.ListCellRenderer)

setCellRenderer

public void setCellRenderer(ListCellRenderer cellRenderer)

设置用于绘制列表中每个单元的委托。类级别文档中更加详细地讨论了单元渲染器的工作。

如果 prototypeCellValue 属性为非 null，则设置单元渲染器还导致重新计算 fixedCellWidth 和 fixedCellHeight 属性。但是只对 cellRenderer 属性生成一个 PropertyChangeEvent。

此属性的默认值由 ListUI 委托（即外观实现）提供。

这是一个 JavaBeans 绑定属性。

参数：

cellRenderer - 绘制列表单元的 ListCellRenderer

另请参见：

getCellRenderer()

getSelectionForeground

public Color getSelectionForeground()

返回用于绘制选定项的前景的颜色。DefaultListCellRenderer 使用此颜色来绘制选定状态中的项的前景，就像大多数 ListUI 实现安装的渲染器所做的一样。

返回：

用于绘制选定项的前景的颜色

另请参见：

setSelectionForeground(java.awt.Color), DefaultListCellRenderer

setSelectionForeground

public void setSelectionForeground(Color selectionForeground)

设置用于绘制选定项的前景的颜色，单元渲染器可以使用此颜色呈现文本和图形。DefaultListCellRenderer 使用此颜色来绘制选定状态中的项的前景，就像大多数 ListUI 实现安装的渲染器所做的一样。

此属性的默认值由外观实现定义。

这是一个 JavaBeans 绑定属性。

参数：

selectionForeground - 在所选列表项的前景中使用的 Color

另请参见：

getSelectionForeground(), setSelectionBackground(java.awt.Color), JComponent.setForeground(java.awt.Color), JComponent.setBackground(java.awt.Color), JComponent.setFont(java.awt.Font), DefaultListCellRenderer

getSelectionBackground

public Color getSelectionBackground()

返回用于绘制选定项的背景的颜色。DefaultListCellRenderer 使用此颜色来绘制选定状态中的项的背景，就像大多数 ListUI 实现安装的渲染器所做的一样。

返回：

用于绘制选定项的背景的颜色

另请参见：

setSelectionBackground(java.awt.Color), DefaultListCellRenderer

setSelectionBackground

public void setSelectionBackground(Color selectionBackground)

设置用于绘制选定项的背景的颜色，单元渲染器可以使用此颜色填充所选单元。DefaultListCellRenderer 使用此颜色来填充选定状态中的项的背景，就像大多数 ListUI 实现安装的渲染器所做的一样。

此属性的默认值由外观实现定义。

这是一个 JavaBeans 绑定属性。

参数：

selectionBackground - 用于所选单元的背景的 Color

另请参见：

getSelectionBackground(), setSelectionForeground(java.awt.Color), JComponent.setForeground(java.awt.Color), JComponent.setBackground(java.awt.Color), JComponent.setFont(java.awt.Font), DefaultListCellRenderer

getVisibleRowCount

public int getVisibleRowCount()

返回 visibleRowCount 属性的值。有关如何解释此值的详细信息，请参阅 setVisibleRowCount(int) 的文档。

返回：

visibleRowCount 属性的值。

另请参见：

setVisibleRowCount(int)

setVisibleRowCount

public void setVisibleRowCount(int visibleRowCount)

设置 visibleRowCount 属性，对于不同的布局方向，此方法有不同的含义：对于 VERTICAL 布局方向，此方法设置要显示的首选行数（不要求滚动）；对于其他方向，它影响单元的包装。

在 VERTICAL 方向上：
设置此属性将影响 getPreferredScrollableViewportSize() 方法（它用于计算封闭视口的首选大小）的返回值。有关更多信息，请参阅该方法的文档。

在 HORIZONTAL_WRAP 和 VERTICAL_WRAP 方向上：
这将影响如何包装单元。有关更多信息，请参阅 setLayoutOrientation(int) 的文档。

此属性的默认值为 8。

使用负值调用此方法将导致该属性被设置为 0。

这是一个 JavaBeans 绑定属性。

参数：

visibleRowCount - 一个整数值，指示要显示的首选行数（不要求滚动）

另请参见：

getVisibleRowCount(), getPreferredScrollableViewportSize(), setLayoutOrientation(int), JComponent.getVisibleRect(), JViewport

getLayoutOrientation

public int getLayoutOrientation()

返回列表的布局方向属性：如果布局是单列单元，则返回 VERTICAL；如果布局是“报纸样式”并且内容按先垂直后水平排列， 则返回 VERTICAL_WRAP；如果布局是“报纸样式”并且内容按先水平后垂直排列，则返回 HORIZONTAL_WRAP。

返回：

layoutOrientation 属性的值

从以下版本开始：

1.4

另请参见：

setLayoutOrientation(int)

setLayoutOrientation

public void setLayoutOrientation(int layoutOrientation)

定义布置列表单元的方式。考虑一个具有五个单元的 JList。单元的布局可以采用以下方式之一：

 VERTICAL:          0
                    1
                    2
                    3
                    4

 HORIZONTAL_WRAP:   0  1  2
                    3  4

 VERTICAL_WRAP:     0  3
                    1  4
                    2
 

这些布局的描述遵循如下内容：

值	描述
VERTICAL	在单个列中垂直布置单元。
HORIZONTAL_WRAP	水平布置单元，根据需要将单元包装到新行中。如果 visibleRowCount 属性小于等于 0，则包装由该列表的宽度确定；否则，以确保列表中 visibleRowCount 行的方式进行包装。
VERTICAL_WRAP	垂直布置单元，根据需要将单元包装到新列中。如果 visibleRowCount 属性小于等于 0，则包装由该列表的宽度确定；否则，在 visibleRowCount 行进行包装。

此属性的默认值为 VERTICAL。

参数：

layoutOrientation - 新的布局方向，VERTICAL、HORIZONTAL_WRAP 或 VERTICAL_WRAP 之一

抛出：

IllegalArgumentException - 如果 layoutOrientation 不是所允许的值之一

从以下版本开始：

1.4

另请参见：

getLayoutOrientation(), setVisibleRowCount(int), getScrollableTracksViewportHeight(), getScrollableTracksViewportWidth()

getFirstVisibleIndex

public int getFirstVisibleIndex()

返回当前可见的最小的列表索引。在从左到右的 componentOrientation 中，第一个可见单元最接近列表的左上角。在从右到左方向上，它最接近右上角。如果任何单元都不可见或者列表为空，则返回 -1。注意，返回的单元可能只有部分可见。

返回：

第一个可见单元的索引

另请参见：

getLastVisibleIndex(), JComponent.getVisibleRect()

getLastVisibleIndex

public int getLastVisibleIndex()

返回当前可见的最大列表索引。如果任何单元都不可见或者列表为空，则返回 -1。注意，返回的单元可能只有部分可见。

返回：

最后一个可见单元的索引

另请参见：

getFirstVisibleIndex(), JComponent.getVisibleRect()

ensureIndexIsVisible

public void ensureIndexIsVisible(int index)

滚动封闭视口中的列表，使指定单元完全可见。此方法使用指定单元的边界调用 scrollRectToVisible。要让此方法生效，JList 必须在 JViewport 中。

如果给定索引超出列表中单元的范围，则此方法不起任何作用。

参数：

index - 要变得可见的单元的索引

另请参见：

JComponent.scrollRectToVisible(java.awt.Rectangle), JComponent.getVisibleRect()

setDragEnabled

public void setDragEnabled(boolean b)

打开或关闭自动拖动处理。要启用自动拖动处理，此属性应该设置为 true，列表的 TransferHandler 需要为非 null。dragEnabled 属性的默认值为 false。

遵守此属性的作业以及识别用户拖动动作取决于外观实现，尤其是列表的 ListUI。启用自动拖动处理时，只要用户在项上按下鼠标按键，然后将鼠标移动几个像素，大多数外观（包括子类化 BasicLookAndFeel 的外观）就开始拖放操作了。因此，将此属性设置为 true 可以对选择的行为方式产生微妙的影响。

如果使用忽略此属性的外观，则仍然可以通过在列表的 TransferHandler 上调用 exportAsDrag 开始一个拖动操作。

参数：

b - 是否启用自动拖动处理

抛出：

HeadlessException - 如果 b 为 true 并且 GraphicsEnvironment.isHeadless() 返回 true

从以下版本开始：

1.4

另请参见：

GraphicsEnvironment.isHeadless(), getDragEnabled(), JComponent.setTransferHandler(javax.swing.TransferHandler), TransferHandler

getDragEnabled

public boolean getDragEnabled()

返回是否启用自动拖动处理。

返回：

dragEnabled 属性的值

从以下版本开始：

1.4

另请参见：

setDragEnabled(boolean)

setDropMode

public final void setDropMode(DropMode dropMode)

设置此组件的放置模式。为了向后兼容性，此属性的默认值为 DropMode.USE_SELECTION。但是，为了方便用户使用，建议使用其他模式。例如，DropMode.ON 提供与选择相似的显示项的行为，但执行此操作不会影响列表中的实际选择。

JList 支持下列放置模式：

• DropMode.USE_SELECTION
• DropMode.ON
• DropMode.INSERT
• DropMode.ON_OR_INSERT

只有此组件具有接受放置的 TransferHandler 时，放置模式才有意义。

参数：

dropMode - 要使用的放置模式

抛出：

IllegalArgumentException - 如果放置模式不受支持或为 null

从以下版本开始：

1.6

另请参见：

getDropMode(), getDropLocation(), JComponent.setTransferHandler(javax.swing.TransferHandler), TransferHandler

getDropMode

public final DropMode getDropMode()

返回此组件的放置模式。

返回：

此组件的放置模式

从以下版本开始：

1.6

另请参见：

setDropMode(javax.swing.DropMode)

getDropLocation

public final JList.DropLocation getDropLocation()

返回在该组件上执行 DnD 操作期间此组件应该视觉上指示为放置位置的位置；如果当前没有任何显示的位置，则返回 null。

此方法不用于查询 TransferHandler 的放置位置，因为只有在 TransferHandler 的 canImport 已返回并允许显示放置位置之后才设置了放置位置。

此属性更改时，带有 "dropLocation" 名称的属性更改事件由该组件触发。

默认情况下，负责侦听对此属性的更改以及视觉上指示放置位置的是列表的 ListUI，它可以直接绘制该位置和/或安装一个用来执行此操作的渲染器。希望实现自定义放置操作绘制和/或替换默认单元渲染器的开发人员可能需要遵守此属性。

返回：

放置操作

从以下版本开始：

1.6

另请参见：

setDropMode(javax.swing.DropMode), TransferHandler.canImport(TransferHandler.TransferSupport)

getNextMatch

public int getNextMatch(String prefix,
                        int startIndex,
                        Position.Bias bias)

返回其 toString 值以给定前缀开头的下一个列表元素。

参数：

prefix - 要测试是否匹配的字符串

startIndex - 开始搜索的索引

bias - 搜索方向，Position.Bias.Forward 或 Position.Bias.Backward。

返回：

以 prefix 开头的下一个列表元素的索引；否则返回 -1

抛出：

IllegalArgumentException - 如果 prefix 为 null 或者 startIndex 超出范围

从以下版本开始：

1.4

getToolTipText

public String getToolTipText(MouseEvent event)

返回用于给定事件的工具提示文本。此方法重写 JComponent 的 getToolTipText，首先检查其上发生事件的单元的单元渲染器组件，并返回其工具提示文本（如果有）。此实现允许使用单元渲染器组件上的 setToolTipText 在单元层上指定工具提示文本。

注：要让 JList 以此方式正确地显示其渲染器的工具提示，JList 必须是已向 ToolTipManager 注册的组件。此注册可以在构造方法中自动完成。但是，如果之后通过调用 setToolTipText(null) 注销了 JList，则渲染器的提示将不再显示。

覆盖：

类 JComponent 中的 getToolTipText

参数：

event - 用于获取工具提示文本的 MouseEvent

另请参见：

JComponent.setToolTipText(java.lang.String), JComponent.getToolTipText()

locationToIndex

public int locationToIndex(Point location)

返回最接近列表的坐标系统中给定位置的单元索引。要确定单元是否实际包含指定的位置，需要将该点与单元的边界进行比较，边界由 getCellBounds 提供。如果模型为空，则此方法返回 -1

此方法是委托给列表的 ListUI 中同名方法的覆盖方法。如果列表没有 ListUI，则它返回 -1。

参数：

location - 点的坐标

返回：

接近给定位置的单元索引或 -1

indexToLocation

public Point indexToLocation(int index)

返回列表的坐标系统中指定项的原点。如果索引无效，则此方法返回 null。

此方法是委托给列表的 ListUI 中同名方法的覆盖方法。如果列表没有 ListUI，则它返回 null。

参数：

index - 单元索引

返回：

单元的原点或 null

getCellBounds

public Rectangle getCellBounds(int index0,
                               int index1)

返回列表的坐标系统中两个索引所指定单元范围内的边界矩形。索引可以按任意顺序提供。

如果较小索引超出单元的列表范围，则此方法返回 null。如果较小索引有效，但较大索引超出列表范围，则只返回第一个索引的边界。否则，返回有效范围的边界。

此方法是委托给列表的 ListUI 中同名方法的覆盖方法。如果列表没有 ListUI，则它返回 null。

参数：

index0 - 范围中的第一个索引

index1 - 范围中的第二个索引

返回：

单元范围的边界矩形或 null

getModel

public ListModel getModel()

返回保存由 JList 组件显示的项列表的数据模型。

返回：

提供显示的项列表的 ListModel

另请参见：

setModel(javax.swing.ListModel)

setModel

public void setModel(ListModel model)

设置表示列表内容或列表“值”的模型，通知属性更改侦听器，然后清除列表选择。

这是一个 JavaBeans 绑定属性。

参数：

model - 提供要显示的项列表的 ListModel

抛出：

IllegalArgumentException - 如果 model 为 null

另请参见：

getModel(), clearSelection()

setListData

public void setListData(Object[] listData)

根据一个对象数组构造只读 ListModel，然后对此模型调用 setModel。

试图将 null 值传递给此方法将导致不确定的行为，很有可能是异常。创建的模型直接引用给定数组。试图在调用此方法之后修改该数组将导致不确定的行为。

参数：

listData - 包含要在列表中显示的项的 Object 数组

另请参见：

setModel(javax.swing.ListModel)

setListData

public void setListData(Vector<?> listData)

根据一个 Vector 构造只读 ListModel，然后对此模型调用 setModel。

试图将 null 值传递给此方法将导致不确定的行为，很有可能是异常。创建的模型直接引用给定 Vector。试图在调用此方法之后修改该 Vector 将导致不确定的行为。

参数：

listData - 包含要在列表中显示的项的 Vector

另请参见：

setModel(javax.swing.ListModel)

createSelectionModel

protected ListSelectionModel createSelectionModel()

返回一个 DefaultListSelectionModel 实例；在构造期间调用此方法初始化列表的选择模型属性。

返回：

一个 DefaultListSelecitonModel，用于在构造期间初始化列表的选择模型属性

另请参见：

setSelectionModel(javax.swing.ListSelectionModel), DefaultListSelectionModel

getSelectionModel

public ListSelectionModel getSelectionModel()

返回当前选择模型。选择模型维护列表的选择状态。有关更多信息，请参阅类级别文档。

返回：

维护列表的选择的 ListSelectionModel

另请参见：

setSelectionModel(javax.swing.ListSelectionModel), ListSelectionModel

fireSelectionValueChanged

protected void fireSelectionValueChanged(int firstIndex,
                                         int lastIndex,
                                         boolean isAdjusting)

通知直接添加到列表的 ListSelectionListener 对列表模型做出了选择更改。JList 侦听选择模型中对选择所做的更改，并通过调用此方法将通知转发到直接添加到列表的侦听器。

此方法以此列表作为源，使用指定的参数构造 ListSelectionEvent，并将其发送到已注册的 ListSelectionListener。

参数：

firstIndex - 范围内的第一个索引（<= lastIndex）

lastIndex - 范围内的最后一个索引（>= firstIndex）

isAdjusting - 此事件是否是多个连续事件之一，其中更改仍然在进行

另请参见：

addListSelectionListener(javax.swing.event.ListSelectionListener), removeListSelectionListener(javax.swing.event.ListSelectionListener), ListSelectionEvent, EventListenerList

addListSelectionListener

public void addListSelectionListener(ListSelectionListener listener)

将侦听器添加到列表，每次选择发生更改时将获得通知；这是侦听选择状态更改的首选方式。JList 负责侦听选择模型中选择状态更改，并通知每个更改的给定侦听器。发送到侦听器的 ListSelectionEvent 具有设置为此列表的 source 属性。

参数：

listener - 要添加的 ListSelectionListener

另请参见：

getSelectionModel(), getListSelectionListeners()

removeListSelectionListener

public void removeListSelectionListener(ListSelectionListener listener)

从列表中移除一个选择侦听器。

参数：

listener - 要移除的 ListSelectionListener

另请参见：

getSelectionModel(), getListSelectionListeners()

getListSelectionListeners

public ListSelectionListener[] getListSelectionListeners()

返回通过 addListSelectionListener 添加到此 JList 中的所有 ListSelectionListener 所组成的数组。

返回：

此列表上的所有 ListSelectionListener；如果没有添加任何侦听器，则返回空数组

从以下版本开始：

1.4

另请参见：

addListSelectionListener(javax.swing.event.ListSelectionListener)

setSelectionModel

public void setSelectionModel(ListSelectionModel selectionModel)

将列表的 selectionModel 设置为非 null 的 ListSelectionModel 实现。选择模型可以完成单个选择、连续范围选择和非连续范围选择等任务。

这是一个 JavaBeans 绑定属性。

参数：

selectionModel - 实现选择的 ListSelectionModel

抛出：

IllegalArgumentException - 如果 selectionModel 为 null

另请参见：

getSelectionModel()

setSelectionMode

public void setSelectionMode(int selectionMode)

设置列表的选择模式。此方法是在选择模型上直接设置选择模式的覆盖方法。

以下列表描述了可接受的选择模式：

• ListSelectionModel.SINGLE_SELECTION - 一次只能选择一个列表索引。在此模式中，setSelectionInterval 和 addSelectionInterval 是等效的，两者都使用第二个参数（“lead”）所表示的索引来替换当前选择。
• ListSelectionModel.SINGLE_INTERVAL_SELECTION - 一次只能选择一个连续间隔。在此模式中，如果给定间隔没有紧邻着现有选择或与现有选择重叠，则 addSelectionInterval 与 setSelectionInterval 完全相同（替换当前选择），并可用于生成选择。
• ListSelectionModel.MULTIPLE_INTERVAL_SELECTION - 在此模式中，不存在对选择的限制。此模式是默认设置。

参数：

selectionMode - 选择模式

抛出：

IllegalArgumentException - 如果选择模式不是那些允许的模式之一

另请参见：

getSelectionMode()

getSelectionMode

public int getSelectionMode()

返回列表的当前选择模式。此方法是委托给列表的选择模型上同名方法的覆盖方法。

返回：

当前选择模式

另请参见：

setSelectionMode(int)

getAnchorSelectionIndex

public int getAnchorSelectionIndex()

返回定位选择索引。此方法是委托给列表的选择模型上同名方法的覆盖方法。

返回：

定位选择索引

另请参见：

ListSelectionModel.getAnchorSelectionIndex()

getLeadSelectionIndex

public int getLeadSelectionIndex()

返回前导选择索引。此方法是委托给列表的选择模型上同名方法的覆盖方法。

返回：

前导选择索引

另请参见：

ListSelectionModel.getLeadSelectionIndex()

getMinSelectionIndex

public int getMinSelectionIndex()

返回选择的最小单元索引；如果选择为空，则返回 -1。此方法是委托给列表的选择模型上同名方法的覆盖方法。

返回：

选择的最小单元索引或 -1

另请参见：

ListSelectionModel.getMinSelectionIndex()

getMaxSelectionIndex

public int getMaxSelectionIndex()

返回选择的最大单元索引；如果选择为空，则返回 -1。此方法是委托给列表的选择模型上同名方法的覆盖方法。

返回：

选择的最大单元索引

另请参见：

ListSelectionModel.getMaxSelectionIndex()

isSelectedIndex

public boolean isSelectedIndex(int index)

如果选择了指定的索引，则返回 true；否则返回 false。此方法是委托给列表的选择模型上同名方法的覆盖方法。

参数：

index - 要查询其选择状态的索引

返回：

如果选择了指定的索引，则返回 true；否则返回 false

另请参见：

ListSelectionModel.isSelectedIndex(int), setSelectedIndex(int)

isSelectionEmpty

public boolean isSelectionEmpty()

如果什么也没有选择，则返回 true；否则返回 false。此方法是委托给列表的选择模型上同名方法的覆盖方法。

返回：

如果什么也没有选择，则返回 true；否则返回 false

另请参见：

ListSelectionModel.isSelectionEmpty(), clearSelection()

clearSelection

public void clearSelection()

清除选择；调用此方法后，isSelectionEmpty 将返回 true。此方法是委托给列表的选择模型上同名方法的覆盖方法。

另请参见：

ListSelectionModel.clearSelection(), isSelectionEmpty()

setSelectionInterval

public void setSelectionInterval(int anchor,
                                 int lead)

选择指定的间隔。包括 anchor 和 lead 两个索引。anchor 不必小于等于 lead。此方法是委托给列表的选择模型上同名方法的覆盖方法。

有关如何处理小于 0 的值的详细信息，请参阅所用选择模型类的文档。

参数：

anchor - 要选择的第一个索引

lead - 要选择的最后一个索引

另请参见：

ListSelectionModel.setSelectionInterval(int, int), DefaultListSelectionModel.setSelectionInterval(int, int), createSelectionModel(), addSelectionInterval(int, int), removeSelectionInterval(int, int)

addSelectionInterval

public void addSelectionInterval(int anchor,
                                 int lead)

将选择设置为指定间隔与当前选择的并集。包括 anchor 和 lead 两个索引。anchor 不必小于等于 lead。此方法是委托给列表的选择模型上同名方法的覆盖方法。

有关如何处理小于 0 的值的详细信息，请参阅所用选择模型类的文档。

参数：

anchor - 要添加到选择的第一个索引

lead - 要添加到选择的最后一个索引

另请参见：

ListSelectionModel.addSelectionInterval(int, int), DefaultListSelectionModel.addSelectionInterval(int, int), createSelectionModel(), setSelectionInterval(int, int), removeSelectionInterval(int, int)

removeSelectionInterval

public void removeSelectionInterval(int index0,
                                    int index1)

将选择设置为指定间隔和当前选择的差集。两个索引 index0 和 index1 都要移除。index0 不必小于等于 index1。此方法是委托给列表的选择模型上同名方法的覆盖方法。

有关如何处理小于 0 的值的详细信息，请参阅所用选择模型类的文档。

参数：

index0 - 要从选择移除的第一个索引

index1 - 要从选择移除的最后一个索引

另请参见：

ListSelectionModel.removeSelectionInterval(int, int), DefaultListSelectionModel.removeSelectionInterval(int, int), createSelectionModel(), setSelectionInterval(int, int), addSelectionInterval(int, int)

setValueIsAdjusting

public void setValueIsAdjusting(boolean b)

设置选择模型的 valueIsAdjusting 属性。当为 true 时，即将进行的选择更改应该被视为单个更改的一部分。此属性供内部使用，开发人员通常不要调用此方法。例如，模型正被更新以响应用户拖动时，如果拖动已经开始，那么该属性值被设置为 true；如果拖动已经结束，则被设置为 false。此属性允许侦听器只在更改结束时进行更新，而不是处理所有的中间值。

如果所做的一系列更改都应该被视为单个更改的一部分，则可能需要直接使用此方法。

此方法是委托给列表的选择模型上同名方法的覆盖方法。有关更多信息，请参阅 ListSelectionModel.setValueIsAdjusting(boolean) 的文档。

参数：

b - 属性的新值

另请参见：

ListSelectionModel.setValueIsAdjusting(boolean), ListSelectionEvent.getValueIsAdjusting(), getValueIsAdjusting()

getValueIsAdjusting

public boolean getValueIsAdjusting()

返回选择模型的 isAdjusting 属性的值。

此方法是委托给列表的选择模型上同名方法的覆盖方法。

返回：

选择模型的 isAdjusting 属性的值。

另请参见：

setValueIsAdjusting(boolean), ListSelectionModel.getValueIsAdjusting()

getSelectedIndices

public int[] getSelectedIndices()

返回所选的全部索引的数组（按升序排列）。

返回：

所选的全部索引（按升序排列）；如果什么也没有选择，则返回一个空数组

另请参见：

removeSelectionInterval(int, int), addListSelectionListener(javax.swing.event.ListSelectionListener)

setSelectedIndex

public void setSelectedIndex(int index)

选择单个单元。如果给定索引大于等于模型大小，则不执行任何操作。此方法是在选择模型上使用 setSelectionInterval 的便捷方法。有关如何处理小于 0 的值的详细信息，请参阅所用选择模型类的文档。

参数：

index - 要选择的单元的索引

另请参见：

ListSelectionModel.setSelectionInterval(int, int), isSelectedIndex(int), addListSelectionListener(javax.swing.event.ListSelectionListener)

setSelectedIndices

public void setSelectedIndices(int[] indices)

将选择更改为给定数组所指定的索引的集合。忽略大于等于模型大小的索引。此方法是清除选择、然后在选择模型上使用 addSelectionInterval 添加索引的便捷方法。有关如何处理小于 0 的值的详细信息，请参阅所用选择模型类的文档。

参数：

indices - 要选择的单元的索引数组（为非 null）

抛出：

NullPointerException - 如果给定数组为 null

另请参见：

ListSelectionModel.addSelectionInterval(int, int), isSelectedIndex(int), addListSelectionListener(javax.swing.event.ListSelectionListener)

getSelectedValues

public Object[] getSelectedValues()

返回所有选择值的数组，根据其列表中的索引顺序按升序排序。

返回：

所选值；如果什么也没有选择，则返回一个空数组

另请参见：

isSelectedIndex(int), getModel(), addListSelectionListener(javax.swing.event.ListSelectionListener)

getSelectedIndex

public int getSelectedIndex()

返回最小的选择单元索引；只选择了列表中单个项时，返回该选择。选择了多项时，则只返回最小的选择索引。如果什么也没有选择，则返回 -1。

此方法是委托给 getMinSelectionIndex 的覆盖方法。

返回：

最小的选择的单元索引

另请参见：

getMinSelectionIndex(), addListSelectionListener(javax.swing.event.ListSelectionListener)

getSelectedValue

public Object getSelectedValue()

返回最小的选择单元索引的值；只选择了列表中单个项时，返回所选值。选择了多项时，返回最小的选择索引的值。如果什么也没有选择，则返回 null。

此方法是返回 getMinSelectionIndex 的模型值的便捷方法。

返回：

所选的第一个值

另请参见：

getMinSelectionIndex(), getModel(), addListSelectionListener(javax.swing.event.ListSelectionListener)

setSelectedValue

public void setSelectedValue(Object anObject,
                             boolean shouldScroll)

从列表中选择指定的对象。

参数：

anObject - 要选择的对象

shouldScroll - 如果所选对象存在，但列表需要滚动才能显示，则为 true；否则为 false

getPreferredScrollableViewportSize

public Dimension getPreferredScrollableViewportSize()

计算显示 visibleRowCount 行所需的视口的大小。此方法所返回的值取决于布局方向：

VERTICAL:
如果已（显式地或通过指定一个原型单元值）设置了 fixedCellWidth 和 fixedCellHeight，则此操作无足轻重。宽度是 fixedCellWidth 加上列表的水平 insets。高度是 fixedCellHeight 乘以 visibleRowCount 再加上列表的垂直 insets。

如果尚未指定 fixedCellWidth 或 fixedCellHeight，则使用直观推断。模型为空时，如果 fixedCellWidth 大于 0，则宽度为 fixedCellWidth，否则为 256 的固定编码 (hard coded) 值。如果 fixedCellHeight 大于 0，则高度为 fixedCellHeight 乘以 visibleRowCount；否则它是固定编码 (hard coded) 值 16 乘以 visibleRowCount。

如果模型不为空，则宽度为首选大小的宽度，通常是最宽的列表元素的宽度。高度是 fixedCellHeight 乘以 visibleRowCount 再加上列表的垂直 insets。

VERTICAL_WRAP 或 HORIZONTAL_WRAP：
此方法只返回 getPreferredSize 的返回值。期望列表的 ListUI 重写 getPreferredSize 以返回适当的值。

指定者：

接口 Scrollable 中的 getPreferredScrollableViewportSize

返回：

包含显示 visibleRowCount 行所需视口大小的 dimension

另请参见：

getPreferredScrollableViewportSize(), setPrototypeCellValue(java.lang.Object)

getScrollableUnitIncrement

public int getScrollableUnitIncrement(Rectangle visibleRect,
                                      int orientation,
                                      int direction)

返回为显露上一个或下一个行（垂直滚动）或列（水平滚动）而滚动的距离。

对于水平滚动，如果布局方向为 VERTICAL，则返回列表的字体大小（如果字体为 null，则返回 1）。

指定者：

接口 Scrollable 中的 getScrollableUnitIncrement

参数：

visibleRect - 视口中可见的视图区域

orientation - SwingConstants.HORIZONTAL 或 SwingConstants.VERTICAL

direction - 小于等于 0 表示向上滚动/后退，大于 0 表示向下滚动/前进

返回：

沿指定方向滚动的“单位”增量；永远为正数

抛出：

IllegalArgumentException - 如果 visibleRect 为 null，或者 orientation 不为 SwingConstants.VERTICAL 或 SwingConstants.HORIZONTAL

另请参见：

getScrollableBlockIncrement(java.awt.Rectangle, int, int), Scrollable.getScrollableUnitIncrement(java.awt.Rectangle, int, int)

getScrollableBlockIncrement

public int getScrollableBlockIncrement(Rectangle visibleRect,
                                       int orientation,
                                       int direction)

返回为显露上一个或下一个块而滚动的距离。

对于垂直滚动，使用以下规则：

• 如果向下滚动，则返回使最后一个可见元素就成为第一个完全可见元素的滚动距离
• 如果向上滚动，则返回使第一个可见元素就成为最后一个完全可见元素的滚动距离
• 如果列表为空，则返回 visibleRect.height

对于水平滚动，当布局方向为 VERTICAL_WRAP 或 HORIZONTAL_WRAP 时：

• 如果向右滚动，则返回使最后一个可见元素就成为第一个完全可见元素的滚动距离
• 如果向左滚动，则返回使第一个可见元素就成为最后一个完全可见元素的滚动距离
• 如果列表为空，则返回 visibleRect.width

对于水平滚动和 VERTICAL 方向，则返回 visibleRect.width。

注意，visibleRect 的值必须等于 this.getVisibleRect()。

指定者：

接口 Scrollable 中的 getScrollableBlockIncrement

参数：

visibleRect - 视口中可见的视图区域

orientation - SwingConstants.HORIZONTAL 或 SwingConstants.VERTICAL

direction - 小于等于 0 表示向上滚动/后退，大于 0 表示向下滚动/前进

返回：

沿指定方向滚动的“块”增量；永远为负数

抛出：

IllegalArgumentException - 如果 visibleRect 为 null，或者 orientation 不为 SwingConstants.VERTICAL 或 SwingConstants.HORIZONTAL

另请参见：

getScrollableUnitIncrement(java.awt.Rectangle, int, int), Scrollable.getScrollableBlockIncrement(java.awt.Rectangle, int, int)

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()

如果此 JList 在 JViewport 中显示并且视口的宽度大于列表的首选宽度，或者布局方向为 HORIZONTAL_WRAP 和 visibleRowCount <= 0，则返回 true；否则返回 false。

如果返回 false，则不跟踪视口宽度。如果 JViewport 本身嵌入在 JScrollPane 中，则此操作允许水平滚动。

指定者：

接口 Scrollable 中的 getScrollableTracksViewportWidth

返回：

封闭视口是否强制列表的宽度与其自身宽度匹配

另请参见：

Scrollable.getScrollableTracksViewportWidth()

getScrollableTracksViewportHeight

public boolean getScrollableTracksViewportHeight()

如果此 JList 在 JViewport 中显示并且视口的高度大于列表的首选高度，或者布局方向为 VERTICAL_WRAP 或 visibleRowCount <= 0，则返回 true；否则返回 false。

如果返回 false，则不跟踪视口高度。如果 JViewport 本身嵌入在 JScrollPane 中，则此操作允许垂直滚动。

指定者：

接口 Scrollable 中的 getScrollableTracksViewportHeight

返回：

封闭视口是否强制列表的高度与其自身高度匹配

另请参见：

Scrollable.getScrollableTracksViewportHeight()

paramString

protected String paramString()

返回此 JList 的 String 表示形式。此方法仅在进行调试的时候使用，对于各个实现，所返回 String 的内容和格式可能有所不同。返回的 String 可以为空，但不可以为 null。

覆盖：

类 JComponent 中的 paramString

返回：

此 JList 的 String 表示形式。

getAccessibleContext

public AccessibleContext getAccessibleContext()

获取与此 JList 关联的 AccessibleContext。对于 JList，AccessibleContext 采取 AccessibleJList 的形式。

如有必要，可以创建一个新的 AccessibleJList 实例。

指定者：

接口 Accessible 中的 getAccessibleContext

覆盖：

类 JComponent 中的 getAccessibleContext

返回：

一个 AccessibleJList，它充当此 JList 的 AccessibleContext

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。