Class List

java.lang.Object
vaadinx.awt.Component
vaadinx.awt.List
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible
public class List extends Component implements ItemSelectable, Accessible
Emulator for List — the AWT 1.0 scrolling list box, not JList. Holds the JDK's items and selection itself, so every getter answers on any thread without reaching the SList peer, which renders them: 
List planets = new List(4, false);
planets.add("Mercury");
planets.add("Venus");
planets.addItemListener(e -> show((Integer) e.getItem()));   // payload is the INDEX
planets.addActionListener(e -> open(e.getActionCommand()));  // double-click / Enter
planets.select(1);                                           // silent: no ItemEvent

The selection follows two rule sets, as in the JDK

Until the list is displayable — added to a frame that has been packed or shown — the JDK's own bodies run: select appends to the selection array, an insert or remove leaves the selected indexes where they were (so they may now name other rows, or none), and flipping multi → single keeps every selected index. Once it is displayable, the platform peer's rules run: the selection shifts with inserts and removes, stays sorted in multiple mode, and a multi → single flip keeps only the row that had the location cursor. Both are reproduced; the peer's are XListPeer's.

Leaf peer is locked down per R_leaf_peer_lockdown: no public class in java.awt extends java.awt.List, so there is no protected (Component peer) ctor and every instance — including a user-code subclass — peers over an SList.

The two event payloads differ, and both trip people up. ItemEvent.getItem() is an Integer index (unlike Choice, which posts the item String), while ActionEvent.getActionCommand() is the item text. And an ItemEvent always means "the user picked something": every mutator and both selection methods are silent, which is the inverse of JList.

See Also:

  • Constructor Details

  • Method Details

    • addNotify

      public void addNotify()
      Overrides:
      addNotify in class Component

    • removeNotify

      public void removeNotify()
      Overrides:
      removeNotify in class Component

    • getItemCount

      public int getItemCount()
      Delegates to countItems(), not the other way round — the JDK's direction, so a subclass overriding the deprecated name stays on the invoked path (R_no_vaadin_in_api limb 2). Every pair below runs the same way.

    • countItems

      @Deprecated public int countItems()
      Deprecated.
      as of JDK 1.1, replaced by getItemCount() — but this is the implementation, not the wrapper

    • getItem

      public String getItem(int index)
      Throws:
      ArrayIndexOutOfBoundsException - when out of range, as AWT's backing Vector does (R_match_swing_errors)

    • getItems

      public String[] getItems()
      Returns:
      a fresh array; the receiver is untouched

    • add

      public void add(String item)

    • addItem

      @Deprecated public void addItem(String item)
      Deprecated.
      replaced by add(String) — but this is on the invoked path

    • add

      public void add(String item, int index)
      Parameters:
      index - anything outside [0, getItemCount()) appends, with no exception — including -1, the documented "append"

    • addItem

      @Deprecated public void addItem(String item, int index)
      Deprecated.
      replaced by add(String, int) — but this is the implementation, not the wrapper
      The one insert body every add reaches, coercions included: an out-of-range index appends and a null item becomes "", so no insert ever throws.

    • replaceItem

      public void replaceItem(String newValue, int index)
      Replaces the item at index.

      The JDK body is literally remove(index); add(newValue, index);, both public, so a subclass overriding either intercepts this too. Kept as the two calls rather than a direct peer replace, which would break that (R_no_vaadin_in_api limb 2). A side effect falls out of it: on a displayed list the replaced row loses its selection.

      Throws:
      ArrayIndexOutOfBoundsException - when out of range — raised by the remove half, before anything is added

    • removeAll

      public void removeAll()

    • clear

      @Deprecated public void clear()
      Deprecated.
      as of JDK 1.1, replaced by removeAll() — but this is the implementation

    • remove

      public void remove(String item)
      Removes the first occurrence.
      Throws:
      IllegalArgumentException - when the item is not in the list, with the JDK's own message (R_match_swing_errors)

    • remove

      public void remove(int position)
      Throws:
      ArrayIndexOutOfBoundsException - when out of range, as AWT's Vector.removeElementAt does (R_match_swing_errors)

    • delItem

      @Deprecated public void delItem(int position)
      Deprecated.
      replaced by remove(int) — but this is on the invoked path

    • delItems

      @Deprecated public void delItems(int start, int end)
      Deprecated.
      as of JDK 1.1, and the JDK's own note says it is expected to become package-private — but it is public today and is the implementation, not the wrapper
      The one delete body every remove reaches.
      Throws:
      ArrayIndexOutOfBoundsException - when the range leaves the list — and note the JDK's loop runs downwards from end, so a negative start removes the higher indices first and only then throws, leaving the list shorter. Reproduced. An end past the top throws with nothing removed.

    • getSelectedIndex

      public int getSelectedIndex()
      Returns:
      the sole selected index, or -1 when nothing or more than one thing is selected. Not "the first selected index"

    • getSelectedIndexes

      public int[] getSelectedIndexes()
      Returns:
      a copy, and a zero-length array when nothing is selected

    • getSelectedItem

      public String getSelectedItem()
      Returns:
      null when nothing, or more than one thing, is selected

    • getSelectedItems

      public String[] getSelectedItems()
      Returns:
      a zero-length array when nothing is selected

    • getSelectedObjects

      public Object[] getSelectedObjects()
      Specified by:
      getSelectedObjects in interface ItemSelectable
      Returns:
      an empty array when nothing is selected — List's convention, and the opposite of Choice and Checkbox, which answer null

    • select

      public void select(int index)
      Selects a row. Fires no ItemEvent — the JDK's javadoc says so outright. Out of range is documented as unspecified; both of the JDK's branches store the index anyway, and so does this, so getSelectedIndex() can answer a row that does not exist.

    • deselect

      public void deselect(int index)
      Deselects a row; fires nothing. While displayable, in single mode the call reaches the peer only when index is the sole selected row — the JDK's own guard.

    • isIndexSelected

      public boolean isIndexSelected(int index)

    • isSelected

      @Deprecated public boolean isSelected(int index)
      Deprecated.
      as of JDK 1.1, replaced by isIndexSelected(int) — but this is the implementation

    • getRows

      public int getRows()
      Returns:
      the constructor's value verbatim — 4 for the zero default, and negatives unchanged. Never changes; there is no setter

    • isMultipleMode

      public boolean isMultipleMode()

    • allowsMultipleSelections

      @Deprecated public boolean allowsMultipleSelections()
      Deprecated.
      as of JDK 1.1, replaced by isMultipleMode() — but this is the implementation

    • setMultipleMode

      public void setMultipleMode(boolean b)
      Flips multi-selection at runtime; fires nothing. Going multiple → single, a displayed list keeps the row with the location cursor if it is selected and drops the rest; a peerless one keeps them all.

    • setMultipleSelections

      @Deprecated public void setMultipleSelections(boolean b)
      Deprecated.
      as of JDK 1.1, replaced by setMultipleMode(boolean) — but this is the implementation, and it holds the no-change guard

    • getVisibleIndex

      public int getVisibleIndex()
      Returns:
      the last index passed to makeVisible(int), or -1

    • makeVisible

      public void makeVisible(int index)
      Scrolls the row into view. The index is recorded even when out of range, as in AWT.

    • getPreferredSize

      public Dimension getPreferredSize(int rows)

    • preferredSize

      @Deprecated public Dimension preferredSize(int rows)
      Deprecated.
      as of JDK 1.1, replaced by getPreferredSize(int)

    • getPreferredSize

      public Dimension getPreferredSize()
      Overrides:
      getPreferredSize in class Component

    • preferredSize

      @Deprecated public Dimension preferredSize()
      Deprecated.
      as of JDK 1.1, replaced by getPreferredSize()
      Overrides:
      preferredSize in class Component

    • getMinimumSize

      public Dimension getMinimumSize(int rows)

    • minimumSize

      @Deprecated public Dimension minimumSize(int rows)
      Deprecated.
      as of JDK 1.1, replaced by getMinimumSize(int)

    • getMinimumSize

      public Dimension getMinimumSize()
      Overrides:
      getMinimumSize in class Component

    • minimumSize

      @Deprecated public Dimension minimumSize()
      Deprecated.
      as of JDK 1.1, replaced by getMinimumSize()
      Overrides:
      minimumSize in class Component

    • addItemListener

      public void addItemListener(ItemListener l)
      Specified by:
      addItemListener in interface ItemSelectable

    • removeItemListener

      public void removeItemListener(ItemListener l)
      Specified by:
      removeItemListener in interface ItemSelectable

    • getItemListeners

      public ItemListener[] getItemListeners()

    • addActionListener

      public void addActionListener(ActionListener l)

    • removeActionListener

      public void removeActionListener(ActionListener l)

    • getActionListeners

      public ActionListener[] getActionListeners()

    • processEvent

      protected void processEvent(AWTEvent e)
      Overrides:
      processEvent in class Component

    • processItemEvent

      protected void processItemEvent(ItemEvent e)
      The single funnel every selection reaches its listeners through — both the peer bridge and a user-code processEvent call. Overriding it and calling super is AWT's documented interception idiom.

    • processActionEvent

      protected void processActionEvent(ActionEvent e)
      The double-click / Enter twin of processItemEvent(ItemEvent).

    • paramString

      protected String paramString()
      Overrides:
      paramString in class Component

    • getAccessibleContext

      public AccessibleContext getAccessibleContext()
      Specified by:
      getAccessibleContext in interface Accessible
      Overrides:
      getAccessibleContext in class Component