T - The type of the item contained within the Cell.public class Cell<T> extends Labeled
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 Labeled.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() {
textProperty().bind(itemProperty());
}
}
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):
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).editing cell
has changed, and checks to see if it is itself. At this point one of three
things can happen:
startEdit() will be called on this cell. Some pointers:
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.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
Labeled.graphicProperty() of the cell to a
TextField and set the Labeled.textProperty()
to null. This would allow end users to then type in input
and make changes to your data model.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.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
Labeled.graphicProperty() back to null and set the
Labeled.textProperty() to its (possibly new) value. Again,
be sure to always call super.cancelEdit() to make sure all
state is correctly updated.isEditing() editing state},
then nothing will happen on this cell.| Type | Property and Description |
|---|---|
BooleanProperty |
editable
A property representing whether this cell is allowed to be put into an
editing state.
|
ReadOnlyBooleanProperty |
editing
Property representing whether this cell is currently in its editing state.
|
ReadOnlyBooleanProperty |
empty
A property used to represent whether the cell has any contents.
|
<any> |
item
The data value associated with this Cell.
|
ReadOnlyBooleanProperty |
selected
Indicates whether or not this cell has been selected.
|
alignmentProperty, contentDisplayProperty, ellipsisStringProperty, fontProperty, graphicProperty, graphicTextGapProperty, labelPaddingProperty, lineSpacingProperty, mnemonicParsingProperty, textAlignmentProperty, textFillProperty, textOverrunProperty, textProperty, underlineProperty, wrapTextPropertycontextMenuProperty, skinClassNameProperty, skinProperty, tooltipProperty| Modifier and Type | Field and Description |
|---|---|
private static java.lang.String |
DEFAULT_STYLE_CLASS
*
Stylesheet Handling *
*
|
private BooleanProperty |
editable |
private ReadOnlyBooleanWrapper |
editing |
private ReadOnlyBooleanWrapper |
empty |
private <any> |
item
*
Properties *
*
|
private boolean |
itemDirty
*
Private Implementation *
*
|
private static PseudoClass |
PSEUDO_CLASS_EMPTY |
private static PseudoClass |
PSEUDO_CLASS_FILLED |
private static PseudoClass |
PSEUDO_CLASS_FOCUSED |
private static PseudoClass |
PSEUDO_CLASS_SELECTED |
private ReadOnlyBooleanWrapper |
selected |
| Constructor and Description |
|---|
Cell()
Creates a default Cell with the default style class of 'cell'.
|
| Modifier and Type | Method and Description |
|---|---|
void |
cancelEdit()
Call this function to transition from an editing state into a non-editing
state, without saving any user input.
|
void |
commitEdit(T newValue)
Call this function when appropriate (based on the user interaction requirements
of your cell editing user interface) to do two things:
Fire the appropriate events back to the backing UI control (e.g.
|
BooleanProperty |
editableProperty()
A property representing whether this cell is allowed to be put into an
editing state.
|
ReadOnlyBooleanProperty |
editingProperty()
Property representing whether this cell is currently in its editing state.
|
private ReadOnlyBooleanWrapper |
editingPropertyImpl() |
ReadOnlyBooleanProperty |
emptyProperty()
A property used to represent whether the cell has any contents.
|
protected java.lang.Boolean |
getInitialFocusTraversable()
Returns the initial focus traversable state of this control, for use
by the JavaFX CSS engine to correctly set its initial value.
|
T |
getItem()
Returns the data value associated with this Cell.
|
boolean |
isEditable()
Returns whether this cell is allowed to be put into an editing state.
|
boolean |
isEditing()
Represents whether the cell is currently in its editing state or not.
|
boolean |
isEmpty()
Returns a boolean representing whether the cell is considered to be empty
or not.
|
protected boolean |
isItemChanged(T oldItem,
T newItem)
This method is called by Cell subclasses so that certain CPU-intensive
actions (specifically, calling
updateItem(Object, boolean)) are
only performed when necessary (that is, they are only performed
when the currently set item is considered to be
different than the proposed new item that could be set). |
boolean |
isSelected()
Returns whether this cell is currently selected or not.
|
<any> |
itemProperty()
The data value associated with this Cell.
|
protected void |
layoutChildren() |
private void |
markCellDirty() |
ReadOnlyBooleanProperty |
selectedProperty()
Indicates whether or not this cell has been selected.
|
void |
setEditable(boolean value)
Allows for certain cells to not be able to be edited.
|
private void |
setEditing(boolean value) |
private void |
setEmpty(boolean value) |
void |
setItem(T value)
Sets the item to the given value - should not be called directly as the
item is managed by the virtualized control.
|
(package private) void |
setSelected(boolean value) |
void |
startEdit()
Call this function to transition from a non-editing state into an editing
state, if the cell is editable.
|
protected void |
updateItem(T item,
boolean empty)
The updateItem method should not be called by developers, but it is the
best method for developers to override to allow for them to customise the
visuals of the cell.
|
void |
updateSelected(boolean selected)
Updates whether this cell is in a selected state or not.
|
alignmentProperty, contentDisplayProperty, ellipsisStringProperty, fontProperty, getAlignment, getClassCssMetaData, getContentBias, getContentDisplay, getControlCssMetaData, getEllipsisString, getFont, getGraphic, getGraphicTextGap, getInitialAlignment, getLabelPadding, getLineSpacing, getText, getTextAlignment, getTextFill, getTextOverrun, graphicProperty, graphicTextGapProperty, isMnemonicParsing, isUnderline, isWrapText, labelPaddingProperty, lineSpacingProperty, mnemonicParsingProperty, setAlignment, setContentDisplay, setEllipsisString, setFont, setGraphic, setGraphicTextGap, setLineSpacing, setMnemonicParsing, setText, setTextAlignment, setTextFill, setTextOverrun, setUnderline, setWrapText, textAlignmentProperty, textFillProperty, textOverrunProperty, textProperty, toString, underlineProperty, wrapTextPropertycomputeMaxHeight, computeMaxWidth, computeMinHeight, computeMinWidth, computePrefHeight, computePrefWidth, contextMenuProperty, createDefaultSkin, executeAccessibleAction, getBaselineOffset, getContextMenu, getControlChildren, getCssMetaData, getSkin, getTooltip, isResizable, loadSkinClass, queryAccessibleAttribute, setContextMenu, setSkin, setTooltip, skinClassNameProperty, skinProperty, tooltipPropertypublic final <any> itemProperty
This value should only be set in subclasses of Cell by the virtualised user interface controls that know how to properly work with the Cell class.
public final ReadOnlyBooleanProperty emptyProperty
When a cell is empty, it can be styled differently via the 'empty' CSS pseudo class state. For example, it may not receive any alternate row highlighting, or it may not receive hover background fill when hovered.
isEmpty()public final ReadOnlyBooleanProperty selectedProperty
isSelected()public final ReadOnlyBooleanProperty editingProperty
isEditing()public final BooleanProperty editableProperty
editable property is also
true.isEditable(),
setEditable(boolean)private <any> item
private ReadOnlyBooleanWrapper empty
private ReadOnlyBooleanWrapper selected
private ReadOnlyBooleanWrapper editing
private BooleanProperty editable
private boolean itemDirty
private static final java.lang.String DEFAULT_STYLE_CLASS
private static final PseudoClass PSEUDO_CLASS_SELECTED
private static final PseudoClass PSEUDO_CLASS_FOCUSED
private static final PseudoClass PSEUDO_CLASS_EMPTY
private static final PseudoClass PSEUDO_CLASS_FILLED
public Cell()
public final <any> itemProperty()
This value should only be set in subclasses of Cell by the virtualised user interface controls that know how to properly work with the Cell class.
public final void setItem(T value)
value - the new data value to set in this cellpublic final T getItem()
public final ReadOnlyBooleanProperty emptyProperty()
When a cell is empty, it can be styled differently via the 'empty' CSS pseudo class state. For example, it may not receive any alternate row highlighting, or it may not receive hover background fill when hovered.
isEmpty()private void setEmpty(boolean value)
public final boolean isEmpty()
public final ReadOnlyBooleanProperty selectedProperty()
isSelected()void setSelected(boolean value)
public final boolean isSelected()
private void setEditing(boolean value)
public final boolean isEditing()
public final ReadOnlyBooleanProperty editingProperty()
isEditing()private ReadOnlyBooleanWrapper editingPropertyImpl()
public final void setEditable(boolean value)
value - A boolean representing whether the cell is editable or not.
If true, the cell is editable, and if it is false, the cell can not
be edited.public final boolean isEditable()
public final BooleanProperty editableProperty()
editable property is also
true.isEditable(),
setEditable(boolean)public void startEdit()
public void cancelEdit()
public void commitEdit(T newValue)
ListView). This will begin the process of pushing this edit
back to the relevant data source / property (although it does not
guarantee that this will be successful - that is dependent upon the
specific edit commit handler being used). Refer to the UI control
class javadoc for more detail.In general there is no need to override this method in custom cell
implementations - it should be sufficient to simply call this method
when appropriate (e.g. when the user pressed the Enter key, you may do something
like cell.commitEdit(converter.fromString(textField.getText()));
newValue - The value as input by the end user, which should be
persisted in the relevant way given the data source underpinning the
user interface and the install edit commit handler of the UI control.protected void layoutChildren()
layoutChildren in class Controlprotected void updateItem(T item, boolean empty)
ListView control) to call this method. However,
the purpose of having the updateItem method is so that developers, when
specifying custom cell factories (again, like the ListView
cell factory),
the updateItem method can be overridden to allow for complete customisation
of the cell.
It is very important that subclasses of Cell override the updateItem method properly, as failure to do so will lead to issues such as blank cells or cells with unexpected content appearing within them. Here is an example of how to properly override the updateItem method:
protected void updateItem(T item, boolean empty) {
super.updateItem(item, empty);
if (empty || item == null) {
setText(null);
setGraphic(null);
} else {
setText(item.toString());
}
}
Note in this code sample two important points:
empty condition, and if true, we
set the text and graphic properties to null. If we do not do this,
it is almost guaranteed that end users will see graphical artifacts
in cells unexpectedly.item - The new item for the cell.empty - whether or not this cell represents data from the list. If it
is empty, then it does not represent any domain data, but is a cell
being used to render an "empty" row.public void updateSelected(boolean selected)
selected - whether or not to select this cell.protected boolean isItemChanged(T oldItem, T newItem)
updateItem(Object, boolean)) are
only performed when necessary (that is, they are only performed
when the currently set item is considered to be
different than the proposed new item that could be set).
The default implementation of this method tests against equality, but developers are able to override this method to perform checks in other ways that are specific to their domain.
oldItem - The currently-set item contained within the cell (i.e. it is
the same as what is available via getItem()).newItem - The item that will be set in the cell, if this method
returns true. If this method returns false, it may not be
set.private final void markCellDirty()
protected java.lang.Boolean getInitialFocusTraversable()
getInitialFocusTraversable in class Control