The list is the largest and most complicated component in the toolkit. It is extremely flexible and you can use it where other toolkits force you to use tables or trees. Essentially it manages a hierarchical structure of items. If you aren't using it as a tree, the items are just roots in the tree. You don't pay any overhead for this.

The list can be in one of four different icon rendering modes:

  1. LIST_VERTICAL - renders the items with a small icon to the left, top to bottom.
  2. LIST_HORIZONTAL - renders the items with a small icon the left, top to bottom and left to right.
  3. When the items reach the bottom of the pane they start in the next column, and the list scrolls horizontally.
  4. ICON - renders the items with a large icon and the label underneath.
  5. COLUMNS - like LIST_VERTICAL, but you can specify an arbitrary number of columns.
Items with fields matching the column names have the field contents rendered into the column for the item row. Supported rendering targets are String, Boolean, Number, and Date. The columns can be resized and reordered by the user. Note: at the time of writing only LIST_VERTICAL and COLUMNS modes are implemented.

Lists can be in one of two selection modes. By default, they are single-select, so only one item at a time can be selected. You can also set multiple selection mode. By default the last selected item cannot be deselected by the user, since normally you want at least something selected. You can turn off this behaviour. You can also turn off selectability by the user at all, if you want to use the list simply as a representation, for instance. This is useful for displaying trees that the user can navigate without allowing them to select anything.

When the list is in a hierarchical state (some items are children of other items), parent items can be collapsed and expanded with the circular expansion symbols. Additionally, you can specify that an item may have children, but you just don't know what they are yet. In this case, you register yourself as a TreeValidator for the list and set the reuired items to be lazy. When the user attempts to expand a lazy item, you receive a callback in which you can populate the list with that item's children.

There are a number of attributes that can be set for items in lists. Enabled, for instance, means that the item cannot be selected (or deselected) and is shown in a disabled control colour. You can also set different font styles for different items (for instance, to indicate meta-information within the list, such as that n items are selected, but one is the primary selection.


The list uses a Tree to manage its items. This is a general utility class that you can use to manage hierarchical structures of any kind of object. It's pretty well optimised for doing this.


The list can be sorted according to a number of indices (as many as there are columns, in different orders of descending and ascending). To sort a list, normally all you need to do is call setSorted(true). If you have a sorted list, you should turn off sorting before adding and removing items in several stages, and then turn it back on again when you have finished the operations, since sorting can be an expensive task.

The list delegates sorting to its Tree storage, specifying an ItemCollator object to use to compare the items. If you have very specific requirements, you can design your own collation classes.

Performance issues

The list has several different methods for allowing you to add and remove items and set their state in various ways. If you have to perform an operation on several items in the list at a time, I strongly suggest you use the methods that take an array of items (eg. add(Ditem[]) instead of add(DItem)). This obviates the list's need to repaint and validate itself more than once.

Performance in the list is currently pretty good. I've had several thousand items in a list at once without any problems. Constructing such a number of items, though, especially with icons, may take time. Think about why you're trying to put so many items in the list. Can you filter the data more effectively elsewhere in the application?

knife home page questions, etc