Class SList

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.HtmlComponent
com.vaadin.swingbridge.surrogates.SList
All Implemented Interfaces:
com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.BlurNotifier<SList>, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.Focusable<SList>, com.vaadin.flow.component.FocusNotifier<SList>, com.vaadin.flow.component.HasElement, com.vaadin.flow.component.HasEnabled, com.vaadin.flow.component.HasSize, com.vaadin.flow.component.HasStyle, ComponentMixin, ItemSelectable, Serializable
@Tag("select") public class SList extends com.vaadin.flow.component.HtmlComponent implements ComponentMixin, com.vaadin.flow.component.Focusable<SList>, ItemSelectable
Surrogate for List — the AWT 1.0 scrolling list box, not JList. Hosts a native <select> directly (is-a HtmlComponent) and picks up the AWT Component API from ComponentMixin. 
SList l = new SList(4, false);
l.addItem("Mercury", -1);
l.addItem("Venus", -1);
l.select(1);                 // silent: no ItemEvent, exactly as in AWT
l.addItemListener(e -> log(e.getItem()));   // only the browser fires

Why a native <select> and not Grid

java.awt.List and an HTML <select size=N> are the same widget — both 1995-era scrolling selection boxes — so most of what a Grid peer would have to simulate, the element simply is. The size attribute is AWT's rows; the multiple attribute is the runtime setMultipleMode(boolean) flip, with no component swap; the <option> children are the item store, positionally identified, so duplicate item Strings need none of SJList's SD_sjlist index-identity machinery; and writing option.selected fires no change, which is AWT's documented "programmatic selection is silent" contract for free rather than a rule to enforce. Rationale, the measured rendering table and the rejected Grid / VirtualList / ListBox designs: SD_slist.

The trade, taken deliberately: a native <select multiple> is not themed by Aura. That is SScrollbar's bargain (SD_sscrollbar) — an AWT widget rendering as the browser's own control — and here it arguably reads as fidelity rather than as a gap.

size is floored at 2

A <select> renders as a drop-down at size=1 without multiple, and as a list box otherwise (measured in Gecko; the HTML spec says "list box control" when multiple is present or size > 1). AWT's rows defaults to 4 but new List(1) is legal, so applyRows(int) emits max(2, rows). This is a rendering floor only — the emulator's getRows() returns the JDK value verbatim, negatives included, because rows never round-trips through the attribute.

State

Items, multipleMode and rows are all DOM state, so none of them is a field here. The one mirror is selected: the browser owns the selection and the server cannot read it synchronously, so the change bridge writes it and every programmatic select(int)/deselect(int) writes it through alongside the DOM. That is an R_swing_is_truth write-through, not an R_vaadin_first shadow cache — and notably it needs no preventPeerEvents guard, because our own write fires no change, so the feedback loop the guard exists to break cannot form.

removeAll() is named removeAllItems() here, the SJComboBox.removeAllItems() convention, so nothing reads as the HasComponents container clear to a stage-3 eye; the emulator vaadinx.awt.List carries AWT's removeAll and clear names. AWT's generic getListeners(Class) is absent for the SD_sbutton erasure clash against Vaadin Component's.

See Also:

  • Constructor Details

    • SList

      public SList()

    • SList

      public SList(int rows)

    • SList

      public SList(int rows, boolean multipleMode)
      Parameters:
      rows - AWT's visible-row count, already through the JDK's (rows != 0) ? rows : 4 substitution by the caller; emitted as size=max(2, rows)

  • Method Details

    • getItemCount

      public int getItemCount()

    • getItemAt

      public String getItemAt(int index)
      Throws:
      ArrayIndexOutOfBoundsException - as AWT's Vector.elementAt does — explicitly, because the plain IndexOutOfBoundsException superclass would slip past a migrator's catch (R_match_swing_errors)

    • getItemsArray

      public String[] getItemsArray()

    • addItem

      public void addItem(String item, int index)
      AWT's addItem(String, int) — the one insert body, coercions included: an out-of-range index appends and a null item becomes "". Never throws.
      Parameters:
      index - -1, or anything outside [0, count), appends

    • removeItemRange

      public void removeItemRange(int start, int end)
      AWT's delItems(start, end), quirk and all: the loop runs downwards from end, so a negative start removes the higher indices and then throws, leaving the list shorter. An end past the top throws on the first removal with nothing removed.
      Throws:
      ArrayIndexOutOfBoundsException - exactly where AWT's Vector.removeElementAt would (R_match_swing_errors)

    • setItemsAndSelection

      public void setItemsAndSelection(List<String> texts, int[] selectedIndexes)
      Replaces the items and the selection, applying none of the insert / remove selection rules above. For a caller that keeps AWT's item vector and selection itself and flushes them here after each change — the emulator vaadinx.awt.List does. Only the rows that differ are touched (the common prefix and suffix stay), so a caller flushing after every single add costs one <option> per call.
      Parameters:
      texts - copied; a null entry renders as "", as AWT stores it
      selectedIndexes - see setSelectedIndexes(int[])

    • setSelectedIndexes

      public void setSelectedIndexes(int[] selectedIndexes)
      Shows exactly this selection, applying none of the selection rules above. Fires no ItemEvent.
      Parameters:
      selectedIndexes - in any order, duplicates allowed; entries outside the rows are skipped, since nothing can render them. In SINGLE mode only the first rendered entry shows, since a single-select <select> holds one — the caller may keep more (AWT's own selection array can, after a multi → single flip while peerless)

    • removeAllItems

      public void removeAllItems()
      Empties the list and the selection.

    • indexOfItem

      public int indexOfItem(String item)
      The index of the first item equal to item, or -1.

    • select

      public void select(int index)
      Selects a row. Fires no ItemEvent — AWT's javadoc says so outright, and here it is the platform's behaviour rather than something suppressed. Out of range is a no-op: AWT documents out-of-range as "unspecified behavior" and its peer path silently does nothing.

    • deselect

      public void deselect(int index)
      Deselects a row, reproducing AWT's guard rather than only its outcome: in SINGLE mode the call reaches the peer only when index is the sole selected row. Fires no ItemEvent.

    • getSelectedIndexes

      public int[] getSelectedIndexes()
      Ascending, and a fresh array each call — never the live mirror.

    • 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" — AWT's body is (sel.length == 1) ? sel[0] : -1

    • getSelectedItem

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

    • getSelectedItemsArray

      public String[] getSelectedItemsArray()

    • getSelectedObjects

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

    • isIndexSelected

      public boolean isIndexSelected(int index)

    • isMultipleMode

      public boolean isMultipleMode()
      Read straight off the peer — no shadow, the round-trip is lossless. Reads the attribute because applyMultipleMode(boolean) writes one; Vaadin's property map and its attribute map are separate, so getProperty("multiple", …) would answer false forever.

    • setMultipleMode

      public void setMultipleMode(boolean multipleMode)
      Flips the multiple attribute live. Fires no ItemEvent.

      Going multiple → single, the browser keeps at most one option selected (measured in Gecko: the first). AWT's rule is "the item with the location cursor stays, else all are deselected" and there is no location cursor here, so the mirror is trimmed to match what the browser will have done — a third outcome inside the same R_best_effort_behaviour latitude, and closer to AWT than dropping the selection wholesale.

    • makeVisible

      public void makeVisible(int index)
      scrollIntoView on the row; no read-back, so no getter here.

    • 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()

    • processItemEvent

      protected void processItemEvent(ItemEvent e)
      AWT's dispatch hook, and the single funnel every browser selection reaches the listeners through. Overriding it and calling super is the documented interception idiom for java.awt.List subclasses.

    • processActionEvent

      protected void processActionEvent(ActionEvent e)
      The ActionEvent twin of processItemEvent(ItemEvent).

    • paramString

      protected String paramString()
      AWT's List.paramString tail.

    • getAccessibleContext

      public AccessibleContext getAccessibleContext()