A ListView displays a horizontal or vertical list of items from which the
user may select, or with which the user may interact. A ListView is able to
have its generic type set to represent the type of data in the backing model.
Doing this has the benefit of making various methods in the ListView, as well
as the supporting classes (mentioned below), type-safe. In addition, making
use of the generic type supports substantially simplified development of applications
making use of ListView, as all modern IDEs are able to auto-complete far
more successfully with the additional type information.

Populating a ListView

A simple example of how to create and populate a ListView of names (Strings)
is shown here:

The elements of the ListView are contained within the
itemsObservableList. This
ObservableList is automatically observed by the ListView, such that any
changes that occur inside the ObservableList will be automatically shown in
the ListView itself. If passing the ObservableList in to the
ListView constructor is not feasible, the recommended approach for setting
the items is to simply call:

ObservableList<T> content = ...
listView.setItems(content);

The end result of this is, as noted above, that the ListView will automatically
refresh the view to represent the items in the list.

Another approach, whilst accepted by the ListView, is not the
recommended approach:

List<T> content = ...
getItems().setAll(content);

The issue with the approach shown above is that the content list is being
copied into the items list - meaning that subsequent changes to the content
list are not observed, and will not be reflected visually within the ListView.

ListView Selection / Focus APIs

To track selection and focus, it is necessary to become familiar with the
SelectionModel and FocusModel classes. A ListView has at most
one instance of each of these classes, available from
selectionModel and
focusModel properties respectively.
Whilst it is possible to use this API to set a new selection model, in
most circumstances this is not necessary - the default selection and focus
models should work in most circumstances.

The default SelectionModel used when instantiating a ListView is
an implementation of the MultipleSelectionModel abstract class.
However, as noted in the API documentation for
the selectionMode
property, the default value is SelectionMode.SINGLE. To enable
multiple selection in a default ListView instance, it is therefore necessary
to do the following:

Customizing ListView Visuals

The visuals of the ListView can be entirely customized by replacing the
default cell factory. A cell factory is used to
generate ListCell instances, which are used to represent an item in the
ListView. See the Cell class documentation for a more complete
description of how to write custom Cells.

Editing

This control supports inline editing of values, and this section attempts to
give an overview of the available APIs and how you should use them.

Firstly, cell editing most commonly requires a different user interface
than when a cell is not being edited. This is the responsibility of the
Cell implementation being used. For ListView, this is the responsibility
of the cell factory. It is your choice whether the cell is
permanently in an editing state (e.g. this is common for CheckBox cells),
or to switch to a different UI when editing begins (e.g. when a double-click
is received on a cell).

To know when editing has been requested on a cell,
simply override the javafx.scene.control.Cell.startEdit() method, and
update the cell text and
graphic properties as
appropriate (e.g. set the text to null and set the graphic to be a
TextField). Additionally, you should also override
Cell.cancelEdit() to reset the UI back to its original visual state
when the editing concludes. In both cases it is important that you also
ensure that you call the super method to have the cell perform all duties it
must do to enter or exit its editing mode.

Once your cell is in an editing state, the next thing you are most probably
interested in is how to commit or cancel the editing that is taking place. This is your
responsibility as the cell factory provider. Your cell implementation will know
when the editing is over, based on the user input (e.g. when the user presses
the Enter or ESC keys on their keyboard). When this happens, it is your
responsibility to call Cell.commitEdit(Object) or
Cell.cancelEdit(), as appropriate.

By default the ListView edit commit handler is non-null, with a default
handler that attempts to overwrite the property value for the
item in the currently-being-edited row. It is able to do this as the
Cell.commitEdit(Object) method is passed in the new value, and this
is passed along to the edit commit handler via the
EditEvent that is fired. It is simply a matter of calling
EditEvent.getNewValue() to retrieve this value.

Hopefully this summary answers some of the commonly asked questions.
Fortunately, JavaFX ships with a number of pre-built cell factories that
handle all the editing requirements on your behalf. You can find these
pre-built cell factories in the javafx.scene.control.cell package.

extendsControl

Parameters:

<T>

This type is used to represent the type of the objects stored in
the ListViews items ObservableList. It is
also used in the selection model
and focus model.