模块 java.desktop
包 java.awt

类 List

java.lang.Object
java.awt.Component
java.awt.List
所有已实现的接口：
ImageObserver , ItemSelectable , MenuContainer , Serializable , Accessible
public class List extends Component implements ItemSelectable , Accessible
List 组件向用户呈现一个滚动的文本项列表。可以设置列表，以便用户可以选择一个项目或多个项目。

例如，代码 . . .

 List lst = new List(4, false);
 lst.add("Mercury");
 lst.add("Venus");
 lst.add("Earth");
 lst.add("JavaSoft");
 lst.add("Mars");
 lst.add("Jupiter");
 lst.add("Saturn");
 lst.add("Uranus");
 lst.add("Neptune");
 lst.add("Pluto");
 cnt.add(lst);

其中 cnt 是一个容器，产生以下滚动列表：

Shows a list containing: Venus, Earth, JavaSoft, and Mars. Javasoft is selected.

如果列表允许多项选择，则单击已选择的项目将取消选择它。在前面的示例中，一次只能从滚动列表中选择一个项目，因为创建新滚动列表时的第二个参数是 false 。如果列表不允许多项选择，则选择一个项目会导致取消选择任何其他选定项目。

请注意，示例中的列表是用四个可见行创建的。创建列表后，无法更改可见行数。创建一个默认的 List 有四行，所以 lst = new List() 等同于 list = new List(4, false) 。

从 Java 1.1 开始，Abstract Window Toolkit 向 List 对象发送发生在其上的所有鼠标、键盘和焦点事件。 （维护旧的 AWT 事件模型只是为了向后兼容，不鼓励使用它。）

当用户选择或取消选择一个项目时，AWT 将 ItemEvent 的实例发送到列表。当用户双击滚动列表中的项目时，AWT 会在项目事件之后将 ActionEvent 的实例发送到列表。当用户在选择列表中的项目时按下返回键时，AWT 也会生成一个动作事件。

如果应用程序想要根据用户选择或激活此list中的项目执行某些操作，它应该适当地实现 ItemListener 或 ActionListener 并注册新的监听器以接收来自此list的事件。

对于多选滚动列表，使用外部手势（例如单击按钮）来触发操作被认为是更好的用户界面。

自从：
1.0
参见：

  • 构造方法详细信息

    • List

      public List() throws HeadlessException
      创建一个新的滚动列表。默认情况下，有四行可见，并且不允许多选。请注意，这是 List(0, false) 的便捷方法。另请注意，列表中可见行的数量在创建后无法更改。
      抛出：
      HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true。
      参见：

    • List

      public List(int rows) throws HeadlessException
      创建一个新的滚动列表，用指定数量的可见行初始化。默认情况下，不允许多选。请注意，这是 List(rows, false) 的便捷方法。另请注意，列表中的可见行数在创建后无法更改。
      参数：
      rows - 要显示的项目数。
      抛出：
      HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true。
      自从：
      1.1
      参见：

    • List

      public List(int rows, boolean multipleMode) throws HeadlessException
      创建一个新的滚动列表，初始化为显示指定的行数。请注意，如果指定了零行，则将创建默认为四行的列表。另请注意，列表中的可见行数在创建后无法更改。如果 multipleMode 的值为 true ，则用户可以从列表中选择多项。如果是 false ，一次只能选择一项。
      参数：
      rows - 要显示的项目数。
      multipleMode - 如果是 true ，则允许多选；否则，一次只能选择一项。
      抛出：
      HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true。
      参见：

  • 方法详情

    • addNotify

      public void addNotify()
      为列表创建对等体。对等点允许我们修改列表的外观而不改变其功能。
      重写：
      addNotify 在类 Component 中
      参见：

    • removeNotify

      public void removeNotify()
      删除此list的对等方。对等点允许我们修改列表的外观而不改变其功能。
      重写：
      removeNotify 在类 Component 中
      参见：

    • getItemCount

      public int getItemCount()
      获取列表中的项目数。
      返回：
      列表中的项目数
      自从：
      1.1
      参见：

    • countItems

      @Deprecated public int countItems()
      已弃用。
      从 JDK 1.1 版开始，由 getItemCount() 取代。
      返回列表中的项目数。
      返回：
      列表中的项目数

    • getItem

      public String  getItem(int index)
      获取与指定索引关联的项目。
      参数：
      index - 项目的位置
      返回：
      与指定索引关联的项
      参见：

    • getItems

      public String [] getItems()
      获取列表中的项目。
      返回：
      包含列表项的字符串数组
      自从：
      1.1
      参见：

    • add

      public void add(String  item)
      将指定的项目添加到滚动列表的末尾。
      参数：
      item - 要添加的项目
      自从：
      1.1

    • addItem

      @Deprecated public void addItem(String  item)
      已弃用。
      替换为 add(String) 。
      将指定的项目添加到列表的末尾。
      参数：
      item - 要添加的项目

    • add

      public void add(String  item, int index)
      将指定项目添加到滚动列表中索引指示的位置。该指数是从零开始的。如果索引的值小于零，或者索引的值大于或等于列表中的项目数，则将该项目添加到列表的末尾。
      参数：
      item - 要添加的项目；如果此参数为 null，则该项目被视为空字符串，""
      index - 添加项目的位置
      自从：
      1.1

    • addItem

      @Deprecated public void addItem(String  item, int index)
      已弃用。
      替换为 add(String, int) 。
      将指定项添加到列表中索引指示的位置。
      参数：
      item - 要添加的项目
      index - 添加项目的位置

    • replaceItem

      public void replaceItem(String  newValue, int index)
      用新字符串替换滚动列表中指定索引处的项目。
      参数：
      newValue - 用于替换现有项目的新字符串
      index - 要替换的项目的位置
      抛出：
      ArrayIndexOutOfBoundsException - 如果 index 超出范围

    • removeAll

      public void removeAll()
      从此list中删除所有项目。
      自从：
      1.1
      参见：

    • clear

      @Deprecated public void clear()
      已弃用。
      从 JDK 1.1 版开始，由 removeAll() 取代。

    • remove

      public void remove(String  item)
      从列表中删除第一次出现的项目。如果指定的项目被选中，并且是列表中唯一被选中的项目，则列表被设置为没有选择。
      参数：
      item - 要从列表中删除的项目
      抛出：
      IllegalArgumentException - 如果该项目不存在于列表中
      自从：
      1.1

    • remove

      public void remove(int position)
      从此滚动列表中移除指定位置的项目。如果指定位置的项目被选中，并且是列表中唯一被选中的项目，则列表设置为无选择。
      参数：
      position - 要删除的项目的索引
      抛出：
      ArrayIndexOutOfBoundsException - 如果 position 小于 0 或大于 getItemCount()-1
      自从：
      1.1
      参见：

    • delItem

      @Deprecated public void delItem(int position)
      已弃用。
      被 remove(String) 和 remove(int) 取代。
      删除指定位置的项目。
      参数：
      position - 要删除的项目的索引

    • getSelectedIndex

      public int getSelectedIndex()
      获取列表中所选项目的索引，
      返回：
      所选项目的索引；如果没有选择任何项目，或者如果选择了多个项目，则返回 -1。
      参见：

    • getSelectedIndexes

      public int[] getSelectedIndexes()
      获取列表中的选定索引。
      返回：
      此滚动列表中选定索引的数组；如果未选择任何项目，则返回零长度数组。
      参见：

    • getSelectedItem

      public String  getSelectedItem()
      获取此滚动列表中的选定项。
      返回：
      列表中的选定项目；如果没有选择任何项目，或者如果选择了多个项目，则返回 null。
      参见：

    • getSelectedItems

      public String [] getSelectedItems()
      获取此滚动列表中的选定项。
      返回：
      此滚动列表中选定项目的数组；如果未选择任何项目，则返回零长度数组。
      参见：

    • getSelectedObjects

      public Object [] getSelectedObjects()
      在对象数组中获取此滚动列表中的选定项。
      指定者：
      getSelectedObjects 在接口 ItemSelectable 中
      返回：
      一个 Object 数组，表示此滚动列表中的选定项目；如果未选择任何项目，则返回零长度数组。
      参见：

    • select

      public void select(int index)
      选择滚动列表中指定索引处的项目。

      请注意，传递超出范围的参数是无效的，并且会导致未指定的行为。

      请注意，此方法应该主要用于初始选择此组件中的项目。以编程方式调用此方法将not触发 ItemEvent 。触发 ItemEvent 的唯一方法是通过用户交互。

      参数：
      index - 要选择的项目的位置
      参见：

    • deselect

      public void deselect(int index)
      取消选择指定索引处的项目。

      请注意，传递超出范围的参数是无效的，并且会导致未指定的行为。

      如果未选择指定索引处的项目，则忽略该操作。

      参数：
      index - 要取消选择的项目的位置
      参见：

    • isIndexSelected

      public boolean isIndexSelected(int index)
      确定是否选择了此滚动列表中的指定项。
      参数：
      index - 要检查的项目
      返回：
      true 如果指定的项目已被选中； false否则
      自从：
      1.1
      参见：

    • isSelected

      @Deprecated public boolean isSelected(int index)
      已弃用。
      从 JDK 1.1 版开始，由 isIndexSelected(int) 取代。
      确定是否选择了列表中的指定项。
      参数：
      index - 指定要检查的项目
      返回：
      true 如果项目被选中；否则false

    • getRows

      public int getRows()
      获取此list中的可见行数。请注意，一旦创建了List，这个数字就永远不会改变。
      返回：
      此滚动列表中的可见行数

    • isMultipleMode

      public boolean isMultipleMode()
      确定此list是否允许多项选择。
      返回：
      true 如果此list允许多项选择；否则，false
      自从：
      1.1
      参见：

    • allowsMultipleSelections

      @Deprecated public boolean allowsMultipleSelections()
      已弃用。
      从 JDK 1.1 版开始，由 isMultipleMode() 取代。
      确定此list是否允许多项选择。
      返回：
      true 如果此list允许多项选择；否则false

    • setMultipleMode

      public void setMultipleMode(boolean b)
      设置确定此list是否允许多项选择的标志。当选择模式由多选变为单选时，选中的项目会发生如下变化： 如果选中的项目有定位光标，则只有该项目保持选中状态。如果没有选定的项目具有位置光标，则所有项目都将被取消选择。
      参数：
      b - 如果 true 则允许多项选择；否则，一次只能从列表中选择一项
      自从：
      1.1
      参见：

    • setMultipleSelections

      @Deprecated public void setMultipleSelections(boolean b)
      已弃用。
      从 JDK 1.1 版开始，由 setMultipleMode(boolean) 取代。
      为此list启用或禁用多选模式。
      参数：
      b - true 启用多模式，false 否则

    • getVisibleIndex

      public int getVisibleIndex()
      获取上次通过方法 makeVisible 使其可见的项目的索引。
      返回：
      最后可见的项目的索引
      参见：

    • makeVisible

      public void makeVisible(int index)
      使指定索引处的项目可见。
      参数：
      index - 项目的位置
      参见：

    • getPreferredSize

      public Dimension  getPreferredSize(int rows)
      获取具有指定行数的列表的首选维度。
      参数：
      rows - 列表中的行数
      返回：
      鉴于指定的行数必须可见，显示此滚动列表的首选尺寸
      自从：
      1.1
      参见：

    • preferredSize

      @Deprecated public Dimension  preferredSize(int rows)
      已弃用。
      从 JDK 1.1 版开始，由 getPreferredSize(int) 取代。
      返回此组件的首选大小，假设它具有指定的行数。
      参数：
      rows - 行数
      返回：
      显示此list的首选尺寸

    • getPreferredSize

      public Dimension  getPreferredSize()
      获取此滚动列表的首选大小。
      重写：
      getPreferredSize 在类 Component 中
      返回：
      显示此滚动列表的首选尺寸
      自从：
      1.1
      参见：

    • preferredSize

      @Deprecated public Dimension  preferredSize()
      已弃用。
      从 JDK 1.1 版开始，由 getPreferredSize() 取代。
      从类复制的描述：Component
      返回组件的首选大小。
      重写：
      preferredSize 在类 Component 中
      返回：
      组件的首选大小

    • getMinimumSize

      public Dimension  getMinimumSize(int rows)
      获取具有指定行数的列表的最小维度。
      参数：
      rows - 列表中的行数
      返回：
      在指定的行数必须可见的情况下，显示此滚动列表的最小尺寸
      自从：
      1.1
      参见：

    • minimumSize

      @Deprecated public Dimension  minimumSize(int rows)
      已弃用。
      从 JDK 1.1 版开始，由 getMinimumSize(int) 取代。
      返回具有指定行数的列表的最小维度。
      参数：
      rows - 列表中的行数
      返回：
      显示此list的最小尺寸

    • getMinimumSize

      public Dimension  getMinimumSize()
      确定此滚动列表的最小大小。
      重写：
      getMinimumSize 在类 Component 中
      返回：
      显示此滚动列表所需的最小尺寸
      自从：
      1.1
      参见：

    • minimumSize

      @Deprecated public Dimension  minimumSize()
      已弃用。
      从 JDK 1.1 版开始，由 getMinimumSize() 取代。
      从类复制的描述：Component
      返回此组件的最小尺寸。
      重写：
      minimumSize 在类 Component 中
      返回：
      该组件的最小尺寸

    • addItemListener

      public void addItemListener(ItemListener  l)
      添加指定的项目监听器以接收来自此list的项目事件。发送项目事件以响应用户输入，但不响应对 select 或 deselect 的调用。如果监听器 l 是 null，则不会抛出任何异常并且不会执行任何操作。

      有关 AWT 线程模型的详细信息，请参阅 AWT 线程问题。

      指定者：
      addItemListener 在接口 ItemSelectable 中
      参数：
      l - 项目监听器
      自从：
      1.1
      参见：

    • removeItemListener

      public void removeItemListener(ItemListener  l)
      删除指定的项目监听器，以便它不再接收来自此list的项目事件。如果监听器 l 是 null，则不会抛出任何异常并且不会执行任何操作。

      有关 AWT 线程模型的详细信息，请参阅 AWT 线程问题。

      指定者：
      removeItemListener 在接口 ItemSelectable 中
      参数：
      l - 项目监听器
      自从：
      1.1
      参见：

    • getItemListeners

      public ItemListener [] getItemListeners()
      返回在此list中注册的所有项目监听的数组。
      返回：
      此list的所有 ItemListener s 或一个空数组（如果当前没有注册项目监听器）
      自从：
      1.4
      参见：

    • addActionListener

      public void addActionListener(ActionListener  l)
      添加指定的动作监听以从此list接收动作事件。当用户双击列表项或在列表具有键盘焦点时键入 Enter 时发生操作事件。

      如果监听器 l 是 null，则不会抛出任何异常并且不会执行任何操作。

      有关 AWT 线程模型的详细信息，请参阅 AWT 线程问题。

      参数：
      l - 动作监听器
      自从：
      1.1
      参见：

    • removeActionListener

      public void removeActionListener(ActionListener  l)
      删除指定的动作监听器，以便它不再接收来自此list的动作事件。当用户双击列表项时发生操作事件。如果监听器 l 是 null，则不会抛出任何异常并且不会执行任何操作。

      有关 AWT 线程模型的详细信息，请参阅 AWT 线程问题。

      参数：
      l - 动作监听器
      自从：
      1.1
      参见：

    • getActionListeners

      public ActionListener [] getActionListeners()
      返回在此list中注册的所有动作监听的数组。
      返回：
      此list的所有 ActionListener s 或空数组（如果当前未注册任何动作监听器）
      自从：
      1.4
      参见：

    • getListeners

      public <T extends EventListener > T[] getListeners(Class <T> listenerType)
      返回当前在此 List 上注册为 FooListener 的所有对象的数组。 FooListener 是使用 addFooListener 方法注册的。

      您可以使用类文字指定 listenerType 参数，例如 FooListener.class 。例如，您可以使用以下代码查询 List l 的项目监听器：

      ItemListener[] ils = (ItemListener[])(l.getListeners(ItemListener.class));
      如果不存在这样的监听器，则此方法返回一个空数组。
      重写：
      getListeners 在类 Component 中
      类型参数：
      T - 监听器的类型
      参数：
      listenerType - 请求的监听器类型；此参数应指定从 java.util.EventListener 派生的接口
      返回：
      在此list中注册为 FooListener 的所有对象的数组，如果没有添加此类监听器，则为空数组
      抛出：
      ClassCastException - 如果 listenerType 没有指定实现 java.util.EventListener 的类或接口
      自从：
      1.3
      参见：

    • processEvent

      protected void processEvent(AWTEvent  e)
      处理此滚动列表上的事件。如果事件是 ItemEvent 的实例，它会调用 processItemEvent 方法。否则，如果事件是 ActionEvent 的实例，它会调用 processActionEvent 。如果事件不是项目事件或动作事件，它会在超类上调用 processEvent。

      请注意，如果事件参数为 null，则行为未指定且可能导致异常。

      重写：
      processEvent 在类 Component 中
      参数：
      e - 事件
      自从：
      1.1
      参见：

    • processItemEvent

      protected void processItemEvent(ItemEvent  e)
      通过将事件分配给任何已注册的 ItemListener 对象来处理此list中发生的项目事件。

      除非为此组件启用项目事件，否则不会调用此方法。当发生以下情况之一时，将启用项目事件：

      • ItemListener 对象通过 addItemListener 注册。
      • 项目事件通过 enableEvents 启用。

      请注意，如果事件参数为 null，则行为未指定且可能导致异常。

      参数：
      e - 项目事件
      自从：
      1.1
      参见：

    • processActionEvent

      protected void processActionEvent(ActionEvent  e)
      通过将发生在该组件上的动作事件分派给任何已注册的 ActionListener 对象来处理它们。

      除非为此组件启用动作事件，否则不会调用此方法。当发生以下情况之一时，将启用操作事件：

      • ActionListener 对象通过 addActionListener 注册。
      • 动作事件通过 enableEvents 启用。

      请注意，如果事件参数为 null，则行为未指定且可能导致异常。

      参数：
      e - 动作事件
      自从：
      1.1
      参见：

    • paramString

      protected String  paramString()
      返回表示此滚动列表状态的参数字符串。此字符串对调试很有用。
      重写：
      paramString 在类 Component 中
      返回：
      此滚动列表的参数字符串

    • delItems

      @Deprecated public void delItems(int start, int end)
      已弃用。
      从 JDK 1.1 版开始，以后不再公开使用。此方法预计仅作为包私有方法保留。
      删除指定索引范围内的列表项。
      参数：
      start - 要删除的范围的起始索引
      end - 要删除的范围的结束索引

    • getAccessibleContext

      public AccessibleContext  getAccessibleContext()
      获取与此 List 关联的 AccessibleContext。对于列表， AccessibleContext 采用 AccessibleAWTList 的形式。如有必要，将创建一个新的 AccessibleAWTList 实例。
      指定者：
      getAccessibleContext 在接口 Accessible 中
      重写：
      getAccessibleContext 在类 Component 中
      返回：
      一个 AccessibleAWTList 作为这个 List 的 AccessibleContext
      自从：
      1.3