User Guide

110 CellRenderer API
About the composition of the List component
List components are composed of rows. These rows display rollover and selection highlights,
are used as hit states for row selection, and play a vital part in scrolling. Aside from selection
highlights and icons (such as the node icons and expander arrows of a Tree component), a row
consists of one cell (or, in the case of the DataGrid component, many cells). In the default
case, these cells are TextField objects that implement the CellRenderer API. However, you can
tell a List component to use a different class of component as the cell for each row. The only
requirement is that the class must implement the CellRenderer API, which the List
component uses for communicating with the cell.
The stacking order of a row in a List or DataGrid component
About the scrolling behavior of the List component
The List class uses a fairly complex algorithm for scrolling. A list only lays out as many rows as
it can display at once; items beyond the value of the
rowCount property don’t get rows at all.
When the list scrolls, it moves all the rows up or down (depending on the scrolling direction).
The list then recycles the rows that are scrolled out of view; it reinitializes them and uses them
for the new rows being scrolled into view. To do this, it sets the value of the old row to the
new item in the view and moves the old row to where the new item is scrolled into view.
Because of this scrolling behavior, you cannot expect a cell to be used for only one value.
Recycling of rows means that the cell renderer must know how to completely reset its state
when it is set to a new value. For example, if your cell renderer creates an icon to display one
item, it might need to remove that icon when another item is rendered with it. Assume your
cell renderer is a container that will be filled with numerous item values over time, and it has
to know how to completely change itself from displaying one value to displaying another. In
fact, your cell should even know how to properly render undefined items, which might mean
removing all old content in the cell.
NOTE
If a cell has button event handlers (onPress and so on), the background hit area may not
receive input necessary to trigger the events.