Module java.desktop
Package java.awt

Class 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是一个容器，产生以下滚动列表:

显示包含：Venus、Earth、JavaSoft 和 Mars 的列表。JavaSoft 已选择。

如果列表允许多选，则单击已选择的项会取消选择。在上面的示例中，由于创建新滚动列表时的第二个参数为false，因此一次只能选择一个滚动列表中的项。如果列表不允许多选，则选择一个项会取消选择任何其他已选择的项。

请注意，示例中的列表是使用四个可见行创建的。一旦列表被创建，可见行数就无法更改。默认情况下，创建一个List时会创建四行，因此lst = new List()等同于list = new List(4, false)。

从Java 1.1开始，抽象窗口工具包将向List对象发送发生在其上的所有鼠标、键盘和焦点事件。(旧的AWT事件模型仅用于向后兼容，并不建议使用。)

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

如果应用程序希望根据用户选择或激活列表中的项执行某些操作，则应适当实现ItemListener或ActionListener，并注册新的侦听器以接收来自此列表的事件。

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

自:
1.0
参见:

  • Constructor Details

    • 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。
      参见:

  • Method Details

    • addNotify

      public void addNotify()
      创建列表的对等体。对等体允许我们修改列表的外观而不改变其功能。
      覆盖:
      addNotify 在类 Component
      参见:

    • removeNotify

      public void removeNotify()
      移除此列表的对等体。对等体允许我们修改列表的外观而不改变其功能。
      覆盖:
      removeNotify 在类 Component
      参见:

    • getItemCount

      public int getItemCount()
      获取列表中的项目数量。
      返回:
      列表中的项目数量
      自版本:
      1.1
      参见:

    • countItems

      @Deprecated public int countItems()
      Deprecated.
      As of JDK version 1.1, replaced by 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)
      Deprecated.
      replaced by 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)
      Deprecated.
      replaced by add(String, int).
      将指定项目添加到列表中由索引指示的位置。
      参数:
      item - 要添加的项目
      index - 要添加项目的位置

    • replaceItem

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

    • removeAll

      public void removeAll()
      从此列表中移除所有项目。
      自版本:
      1.1
      参见:

    • clear

      @Deprecated public void clear()
      Deprecated.
      As of JDK version 1.1, replaced by 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)
      Deprecated.
      replaced by remove(String) and 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)
      选择滚动列表中指定索引处的项目。

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

      请注意，此方法应主要用于最初选择此组件中的项目。通过编程调用此方法将不会触发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)
      Deprecated.
      As of JDK version 1.1, replaced by isIndexSelected(int).
      确定列表中指定的项目是否已选择。
      参数:
      index - 指定要检查的项目
      返回:
      如果项目已选择，则返回true; 否则返回false

    • getRows

      public int getRows()
      获取此列表中可见行的数量。请注意，一旦创建了List，此数字将永远不会更改。
      返回:
      此滚动列表中可见行的数量

    • isMultipleMode

      public boolean isMultipleMode()
      确定此列表是否允许多重选择。
      返回:
      如果此列表允许多重选择，则返回true; 否则返回false
      自:
      1.1
      参见:

    • allowsMultipleSelections

      @Deprecated public boolean allowsMultipleSelections()
      Deprecated.
      As of JDK version 1.1, replaced by isMultipleMode().
      确定此列表是否允许多重选择。
      返回:
      如果此列表允许多重选择，则返回true; 否则返回false

    • setMultipleMode

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

    • setMultipleSelections

      @Deprecated public void setMultipleSelections(boolean b)
      Deprecated.
      As of JDK version 1.1, replaced by setMultipleMode(boolean).
      为此列表启用或禁用多重选择模式。
      参数:
      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)
      Deprecated.
      As of JDK version 1.1, replaced by getPreferredSize(int).
      返回假定具有指定行数的此组件的首选大小。
      参数:
      rows - 行数
      返回:
      显示此列表的首选尺寸

    • getPreferredSize

      public Dimension getPreferredSize()
      获取此滚动列表的首选大小。
      覆盖:
      getPreferredSize 在类 Component
      返回:
      显示此滚动列表的首选尺寸
      自:
      1.1
      参见:

    • preferredSize

      @Deprecated public Dimension preferredSize()
      Deprecated.
      As of JDK version 1.1, replaced by getPreferredSize().
      从类中复制的描述: Component
      返回组件的首选大小。
      覆盖:
      preferredSize 在类 Component
      返回:
      组件的首选大小

    • getMinimumSize

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

    • minimumSize

      @Deprecated public Dimension minimumSize(int rows)
      Deprecated.
      As of JDK version 1.1, replaced by getMinimumSize(int).
      返回具有指定行数的列表的最小尺寸。
      参数:
      rows - 列表中的行数
      返回:
      显示此列表的最小尺寸

    • getMinimumSize

      public Dimension getMinimumSize()
      确定此滚动列表的最小尺寸。
      覆盖:
      getMinimumSize 在类 Component
      返回:
      显示此滚动列表所需的最小尺寸
      自:
      1.1
      参见:

    • minimumSize

      @Deprecated public Dimension minimumSize()
      Deprecated.
      As of JDK version 1.1, replaced by getMinimumSize().
      从类中复制的描述: Component
      返回此组件的最小尺寸。
      覆盖:
      minimumSize 在类 Component
      返回:
      此组件的最小尺寸

    • addItemListener

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

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

      指定者:
      addItemListener 在接口 ItemSelectable
      参数:
      l - 项目侦听器
      自:
      1.1
      参见:

    • removeItemListener

      public void removeItemListener(ItemListener l)
      移除指定的项目侦听器，使其不再从此列表接收项目事件。如果侦听器l为null，则不会抛出异常，也不会执行任何操作。

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

      指定者:
      removeItemListener 在接口 ItemSelectable
      参数:
      l - 项目侦听器
      自:
      1.1
      参见:

    • getItemListeners

      public ItemListener[] getItemListeners()
      返回在此列表上注册的所有项目侦听器的数组。
      返回值:
      返回此列表的所有ItemListener或如果当前未注册任何项目侦听器，则返回空数组
      自版本:
      1.4
      另请参阅:

    • addActionListener

      public void addActionListener(ActionListener l)
      将指定的动作侦听器添加到此列表以接收来自此列表的动作事件。当用户双击列表项或在列表具有键盘焦点时键入Enter时，将发生动作事件。

      如果侦听器l为null，则不会抛出异常，也不会执行任何操作。

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

      参数:
      l - 动作侦听器
      自版本:
      1.1
      另请参阅:

    • removeActionListener

      public void removeActionListener(ActionListener l)
      从此列表中删除指定的动作侦听器，使其不再接收来自此列表的动作事件。当用户双击列表项时会发生动作事件。如果侦听器l为null，则不会抛出异常，也不会执行任何操作。

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

      参数:
      l - 动作侦听器
      自版本:
      1.1
      另请参阅:

    • getActionListeners

      public ActionListener[] getActionListeners()
      返回在此列表上注册的所有动作侦听器的数组。
      返回值:
      返回此列表的所有ActionListener或如果当前未注册任何动作侦听器，则返回空数组
      自版本:
      1.4
      另请参阅:

    • getListeners

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

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

      ItemListener[] ils = (ItemListener[])(l.getListeners(ItemListener.class));
      如果不存在此类侦听器，则此方法返回空数组。
      覆盖:
      getListeners 在类中 Component
      类型参数:
      T - 侦听器的类型
      参数:
      listenerType - 请求的侦听器类型；此参数应指定从java.util.EventListener继承的接口
      返回值:
      在此列表上注册为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对象来处理在此列表上发生的项目事件。

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

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

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

      参数:
      e - 项目事件
      自版本:
      1.1
      另请参阅:

    • processActionEvent

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

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

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

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

      参数:
      e - 动作事件
      自版本:
      1.1
      另请参阅:

    • paramString

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

    • delItems

      @Deprecated public void delItems(int start, int end)
      Deprecated.
      As of JDK version 1.1, Not for public use in the future. This method is expected to be retained only as a package private method.
      删除指定索引范围内的列表项。
      参数:
      start - 要删除的范围的起始索引
      end - 要删除的范围的结束索引

    • getAccessibleContext

      public AccessibleContext getAccessibleContext()
      获取与此List关联的AccessibleContext。对于列表，AccessibleContext采用AccessibleAWTList的形式。如果需要，将创建一个新的AccessibleAWTList实例。
      指定者:
      getAccessibleContext 在接口中 Accessible
      覆盖:
      getAccessibleContext 在类中 Component
      返回值:
      作为此List的AccessibleContext的AccessibleAWTList
      自版本:
      1.3