public class Cell<T>
  Comment     Returned-by     Constructor-argument     Method-argument     Field-type     Type-bound     Links  

The Cell API is used for virtualized controls such as ListView, TreeView, and TableView. A Cell is a Labeled Control, and is used to render a single "row" inside a ListView, TreeView or TableView. Cells are also used for each individual 'cell' inside a TableView (i.e. each row/column intersection). See the JavaDoc for each control separately for more detail.

Every Cell is associated with a single data item (represented by the item property). The Cell is responsible for rendering that item and, where appropriate, for editing the item. An item within a Cell may be represented by text or some other control such as a CheckBox, ChoiceBox or any other Node such as a HBox, GridPane, or even a Rectangle.

Because TreeView, ListView, TableView and other such controls can potentially be used for displaying incredibly large amounts of data, it is not feasible to create an actual Cell for every single item in the control. We represent extremely large data sets using only very few Cells. Each Cell is "recycled", or reused. This is what we mean when we say that these controls are virtualized.

Since Cell is a Control, it is essentially a "model". Its Skin is responsible for defining the look and layout, while the Behavior is responsible for handling all input events and using that information to modify the Control state. Also, the Cell is styled from CSS just like any other Control. However, it is not necessary to implement a Skin for most uses of a Cell. This is because a cell factory can be set - this is detailed more shortly.

Because by far the most common use case for cells is to show text to a user, this use case is specially optimized for within Cell. This is done by Cell extending from Labeled. This means that subclasses of Cell need only set the text property, rather than create a separate Label and set that within the Cell. However, for situations where something more than just plain text is called for, it is possible to place any Node in the Cell graphic property. Despite the term, a graphic can be any Node, and will be fully interactive. For example, a ListCell might be configured with a Button as its graphic. The Button text could then be bound to the cells item property. In this way, whenever the item in the Cell changes, the Button text is automatically updated.

Cell sets focusTraversable to false.

Cell Factories

The default representation of the Cell item is up to the various virtualized container's skins to render. For example, the ListView by default will convert the item to a String and call setText(java.lang.String) with this value. If you want to specialize the Cell used for the ListView (for example), then you must provide an implementation of the cellFactory callback function defined on the ListView. Similar API exists on most controls that use Cells (for example, TreeView, TableView, TableColumn and ListView.

The cell factory is called by the platform whenever it determines that a new cell needs to be created. For example, perhaps your ListView has 10 million items. Creating all 10 million cells would be prohibitively expensive. So instead the ListView skin implementation might only create just enough cells to fit the visual space. If the ListView is resized to be larger, the system will determine that it needs to create some additional cells. In this case it will call the cellFactory callback function (if one is provided) to create the Cell implementation that should be used. If no cell factory is provided, the built-in default implementation will be used.

The implementation of the cell factory is then responsible not just for creating a Cell instance, but also configuring that Cell such that it reacts to changes in its state. For example, if I were to create a custom Cell which formatted Numbers such that they would appear as currency types, I might do so like this:

 public class MoneyFormatCell extends ListCell<Number> {

     public MoneyFormatCell() {    }

     @Override protected void updateItem(Number item, boolean empty) {
         // calling super here is very important - don't skip this!
         super.updateItem(item, empty);

         // format the number as if it were a monetary value using the
         // formatting relevant to the current locale. This would format
         // 43.68 as "$43.68", and -23.67 as "-$23.67"
         setText(item == null ? "" : NumberFormat.getCurrencyInstance().format(item));

         // change the text fill based on whether it is positive (green)
         // or negative (red). If the cell is selected, the text will
         // always be white (so that it can be read against the blue
         // background), and if the value is zero, we'll make it black.
         if (item != null) {
             double value = item.doubleValue();
             setTextFill(isSelected() ? Color.WHITE :
                 value == 0 ? Color.BLACK :
                 value < 0 ? Color.RED : Color.GREEN);
This class could then be used inside a ListView as such:
 ObservableList<Number> money = ...;
 final ListView<Number> listView = new ListView<Number>(money);
 listView.setCellFactory(new Callback<ListView<Number>, ListCell<Number>>() {
     @Override public ListCell<Number> call(ListView<Number> list) {
         return new MoneyFormatCell();
In this example an anonymous inner class is created, that simply returns instances of MoneyFormatCell whenever it is called. The MoneyFormatCell class extends ListCell, overriding the updateItem method. This method is called whenever the item in the cell changes, for example when the user scrolls the ListView or the content of the underlying data model changes (and the cell is reused to represent some different item in the ListView). Because of this, there is no need to manage bindings - simply react to the change in items when this method occurs. In the example above, whenever the item changes, we update the cell text property, and also modify the text fill to ensure that we get the correct visuals. In addition, if the cell is "empty" (meaning it is used to fill out space in the ListView but doesn't have any data associated with it), then we just use the empty String.

Note that there are additional methods prefixed with 'update' that may be of interest, so be sure to read the API documentation for Cell, and subclasses of Cell, closely.

Of course, we can also use the binding API rather than overriding the 'update' methods. Shown below is a very trivial example of how this could be achieved.

 public class BoundLabelCell extends ListCell<String> {

     public BoundLabelCell() {

Key Design Goals

Key Use Cases

Following are a number of key use cases used to drive the Cell API design, along with code examples showing how those use cases are satisfied by this API. This is by no means to be considered the definitive list of capabilities or features supported, but rather, to provide some guidance as to how to use the Cell API. The examples below are focused on the ListView, but the same philosophy applies to TreeCells or other kinds of cells.

Changing the Cell's Colors

This should be extraordinarily simple in JavaFX. Each Cell can be styled directly from CSS. So for example, if you wanted to change the default background of every cell in a ListView to be WHITE you could do the following CSS:

 .list-cell {
   -fx-padding: 3 3 3 3;
   -fx-background-color: white;
If you wanted to set the color of selected ListView cells to be blue, you could add this to your CSS file:
 .list-cell:selected {
   -fx-background-color: blue;
Most Cell implementations extend from IndexedCell rather than Cell. IndexedCell adds two other pseudoclass states: "odd" and "even". Using this you can get alternate row striping by doing something like this in your CSS file:
 .list-cell:odd {
   -fx-background-color: grey;
Each of these examples require no code changes. Simply update your CSS file to alter the colors. You can also use the "hover" and other pseudoclasses in CSS the same as with other controls.

Another approach to the first example above (formatting a list of numbers) would be to use style classes. Suppose you had an ObservableList of Numbers to display in a ListView and wanted to color all of the negative values red and all positive or 0 values black. One way to achieve this is with a custom cellFactory which changes the styleClass of the Cell based on whether the value is negative or positive. This is as simple as adding code to test if the number in the cell is negative, and adding a "negative" styleClass. If the number is not negative, the "negative" string should be removed. This approach allows for the colors to be defined from CSS, allowing for simple customization. The CSS file would then include something like the following:

 .list-cell {
   -fx-text-fill: black;

 .list-cell .negative {
   -fx-text-fill: red;


Most virtualized controls that use the Cell architecture (e.g. ListView, TreeView, TableView and TreeTableView) all support the notion of editing values directly via the cell. You can learn more about the control-specific details by going to the 'editing' section in the class documentation for the controls linked above. The remainder of this section will cover some of the finer details of editing with cells.

The general flow of editing is as follows (note that in these steps the ListView control is used as an example, but similar API exists for all controls mentioned above, and the process is exactly the same in general):

  1. User requests a cell enter editing mode (via keyboard or mouse commands), or the developer requests that a cell enter editing mode (by calling a method such as the ListView edit method. Note: If the user double-clicks or fires an appropriate keyboard command to initiate editing, then they are effectively calling the appropriate edit method on the control (i.e. the entry method for user-initiated and developer-initiated editing is the same).
  2. Each cell in the visible region of the control is notified that the current editing cell has changed, and checks to see if it is itself. At this point one of three things can happen:
    1. If the editing index is the same index as the cell, startEdit() will be called on this cell. Some pointers:
      1. It is recommended that subclasses of Cell override the startEdit() method to update the visuals of the cell when enters the editing state. Note however that it is very important that subclasses that override the startEdit() method continue to call super.startEdit() so that parent classes can update additional state that is necessary for editing to be successful.
      2. Within the startEdit() method is an ideal time to change the visuals of the cell. For example (and note that this example is more fleshed out in the UI control javadocs for ListView, etc), you may set the graphicProperty() of the cell to a TextField and set the textProperty() to null. This would allow end users to then type in input and make changes to your data model.
      3. When the user has completed editing, they will want to commit or cancel their change. This is your responsibility to handle (e.g. by having the Enter key commit the edit and the ESC key cancel the edit). You do this by attaching the appropriate event listeners to the nodes you show whilst in the editing state.
    2. If the editing index is not the same index as the cell, and if the cell is currently in the editing state, cancelEdit() will be called on this cell. As with the startEdit() method, you should override this method to clean up the visuals of the cell (and most probably return the graphicProperty() back to null and set the textProperty() to its (possibly new) value. Again, be sure to always call super.cancelEdit() to make sure all state is correctly updated.
    3. If the editing index is not the same index as the cell, and if the cell is not currently in the isEditing() editing state}, then nothing will happen on this cell.

extends Labeled

<T>    The type of the item contained within the Cell.

Since:  JavaFX 2.0