User Guide

CellRenderer API 145
CellRenderer API
The CellRenderer API is a set of properties and methods that the list-based components (List,
DataGrid, Tree, Menu, and ComboBox) use to manipulate and display custom cell content for
each of their rows. This customized cell can contain a prebuilt component, such as a CheckBox
component, or any class you create.
Understanding the List class
To use the CellRenderer API, you need an advanced understanding of the List class. The
DataGrid, Tree, Menu, and ComboBox components are extensions of the List class, so
understanding the List class lets you understand them as well.
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
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.
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.
CHAPTER 6
Components Dictionary