Module javafx.controls
Package javafx.scene.control

Class ListView<T>

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.layout.Region
javafx.scene.control.Control
javafx.scene.control.ListView<T>
Type 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.
All Implemented Interfaces:
Styleable, EventTarget, Skinnable
@DefaultProperty("items") public class ListView<T> extends Control
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: 

 ObservableList<String> names = FXCollections.observableArrayList(
          "Julia", "Ian", "Sue", "Matthew", "Hannah", "Stephan", "Denise");
 ListView<String> listView = new ListView<String>(names);

The elements of the ListView are contained within the items ObservableList. 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);
Image of the ListView control

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: 

 listView.getSelectionModel().setSelectionMode(SelectionMode.MULTIPLE);

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.

Warning: Nodes should not be inserted directly into the items list

ListView allows for the items list to contain elements of any type, including Node instances. Putting nodes into the items list is strongly discouraged, as it can lead to unexpected results.

Important points to note:

  • Avoid inserting Node instances directly into the items list or its data model.
  • The recommended approach is to put the relevant information into the items list, and provide a custom cell factory to create the nodes for a given cell and update them on demand using the data stored in the item for that cell.
  • Avoid creating new Nodes in the updateItem method of a custom cell factory.

The following minimal example shows how to create a custom cell factory for ListView containing Nodes: 

  ListView<Color> lv = new ListView<>();
  lv.getItems().addAll(Color.RED, Color.GREEN, Color.BLUE);

  lv.setCellFactory(p -> {
    return new ListCell<>() {
        private final Rectangle rectangle;
        {
            setContentDisplay(ContentDisplay.GRAPHIC_ONLY);
            rectangle = new Rectangle(10, 10);
        }

        @Override
        protected void updateItem(Color item, boolean empty) {
            super.updateItem(item, empty);

            if (item == null || empty) {
                setGraphic(null);
            } else {
                rectangle.setFill(item);
                setGraphic(rectangle);
            }
         }
     };
 });

This example has an anonymous custom ListCell class in the custom cell factory. Note that the Rectangle (Node) object needs to be created in the instance initialization block or the constructor of the custom ListCell class and updated/used in its updateItem method.

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 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.

When you call Cell.commitEdit(Object) an event is fired to the ListView, which you can observe by adding an EventHandler via setOnEditCommit(javafx.event.EventHandler). Similarly, you can also observe edit events for edit start and edit cancel.

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 ListView.EditEvent that is fired. It is simply a matter of calling ListView.EditEvent.getNewValue() to retrieve this value.

It is very important to note that if you call setOnEditCommit(javafx.event.EventHandler) with your own EventHandler, then you will be removing the default handler. Unless you then handle the writeback to the property (or the relevant data source), nothing will happen. You can work around this by using the Node.addEventHandler(javafx.event.EventType, javafx.event.EventHandler) method to add a editCommitEvent() EventType with your desired EventHandler as the second argument. Using this method, you will not replace the default implementation, but you will be notified when an edit commit has occurred.

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.

Since:
JavaFX 2.0
See Also: