ComboBox
A JComboBox over items: it shows the item that is selected and drops the full list down in a popup for the user to choose from.
The selection is controlled via selectedItem + onSelectionChange, with null meaning no selection. onSelectionChange reports the user's choices only: a declared selectedItem is the composition's own state, so applying it - and rebuilding items under it - leaves the callback silent. It is re-applied on every pass, so a choice the caller does not adopt is undone. The selection names an item rather than a position, so items that compare equal are one and the same selection.
Parameters
the list of items to display
the selected item (controlled); null selects nothing, as does an item the current items do not contain
callback invoked when the user chooses an item
the SwingModifier applied to the underlying component
whether the user can type a value into the combo box's editor; false by default
callback invoked with the editor's text when an editable combo box's editor is committed; a text that matches no item is reported here and nowhere else, since selectedItem can only name an item. Left out, such a text goes unreported
the maximum number of items the popup shows before it scrolls, or null to leave the count the box already carries
optional composable cell rendered per item against a ListItemScope; null keeps the default toString rendering. The display area composes a cell only for one of items: text typed into an editable editor renders empty there on the pass that turns editable off, until the next writes selectedItem back
See also
A ComboBox driven by a raw ActionListener instead of an onSelectionChange lambda. The actionListener is attached as-is and removed on the same instance; pass a stable instance (e.g. remember {}) to avoid churn. Being attached as-is, it is notified of every action event the combo box fires, including the one that applies selectedItem. selectedItem is declared, applied and re-asserted as on the onSelectionChange-driven overload.
Parameters
the list of items to display
the selected item; null selects nothing, as does an item the current items do not contain
the listener notified of every action event the combo box fires
the SwingModifier applied to the underlying component
whether the user can type a value into the combo box's editor; false by default. An editor commit reaches actionListener under the "comboBoxEdited" action command, carrying whatever was typed as the combo box's selected item
the maximum number of items the popup shows before it scrolls, or null to leave the count the box already carries
optional composable cell rendered per item against a ListItemScope; null keeps the default toString rendering. The display area composes a cell only for one of items: text typed into an editable editor renders empty there on the pass that turns editable off, until the next writes selectedItem back
See also
A ComboBox driven by a caller-owned ComboBoxModel. The model owns both the items and the selection, so this overload is observation-only: it renders the model and reports selection changes through onSelectionChange without ever writing the selection back into the model. Swapping the model instance installs the new model verbatim.
Parameters
the combo box model to render; owns its items and selection
the SwingModifier applied to the underlying component
callback invoked with the settled selected index when the user chooses an item
whether the user can type a value into the combo box's editor; false by default
the maximum number of items the popup shows before it scrolls, or null to leave the count the box already carries
optional composable cell rendered per item against a ListItemScope; null keeps the default toString rendering. The display area composes a cell only for a value the model lists among its elements. A selection outside them leaves it empty, as does text typed into an editable editor
See also
A model-driven ComboBox driven by a raw ActionListener instead of an onSelectionChange lambda. The model owns its items and selection and is never mutated by the library. The actionListener is attached as-is and removed on the same instance; pass a stable instance (e.g. remember {}) to avoid churn. Swapping the model instance installs the new model verbatim.
Parameters
the combo box model to render; owns its items and selection
the listener notified of every action event the combo box fires
the SwingModifier applied to the underlying component
whether the user can type a value into the combo box's editor; false by default. An editor commit reaches actionListener under the "comboBoxEdited" action command, carrying whatever was typed as the combo box's selected item
the maximum number of items the popup shows before it scrolls, or null to leave the count the box already carries
optional composable cell rendered per item against a ListItemScope; null keeps the default toString rendering. The display area composes a cell only for a value the model lists among its elements. A selection outside them leaves it empty, as does text typed into an editable editor