Tree and List

Using Trees and Lists is a great way to organize selectable data. List is usually used as an element of a SelectBox, however it can still be used on its own. Trees can organize data like an expandable file explorer.

ListStyle

The "background" drawable is the box that contains the entire contents of the widget. Do not add too much padding here or your selections will look a little odd.

Lists require a font to display their items. The user can click on any of the items to select it. To distinguish between selected and unselected items, set the "fontColorSelected" and "fontColorUnselected" color fields.

Another way to make selected items stand out, you can specify a "selection" drawable. It could technically be a single pixel sized image that will be stretched, however you'll want to add some padding to your selection drawable if you find your text getting squished against the background. You can also add "over" and "down" drawables for when the user mouses over and clicks on these items.

List Layout

If you just need a simple list with a few text options, it's easy enough to use #setItems() to do so.

List<String> list = new List(skin);
list.setItems(new String[] {"selection one", "selection two", "selection three"});
root.add(list);

List aligns to the left by default. There are times I like to set the alignment to the center especially if it's part of a SelectBox that is centered.

list.setAlignment(Align.center);

List accepts any kind of object as the array of items, but only implements them as text via Object#toString(). You can't add drawables or widgets to a list and expect them to display inside the list.

List list = new List(skin);
list.setItems(new Object[] {"string", new Label("label", skin), skin.getDrawable("button-normal")});
root.add(list);

Having a List of a specific type can be very useful when you need to use the selected Object to do a task.

final List<Drawable> list = new List(skin);
list.setItems(new Drawable[] {skin.getDrawable("checkbox"), skin.getDrawable("radio"), skin.getDrawable("button-normal")});
root.add(list);

root.row();
final Image image = new Image();
root.add(image).space(10);

list.addListener(new ChangeListener() {
    @Override
    public void changed(ChangeEvent event, Actor actor) {
        image.setDrawable(list.getSelected());
    }
});

TreeStyle

Tree Layout

Further steps

Widgets often extend past the limited bounds of their parent and you need a way to contain them. Proceed with the next chapter, 06 - ScrollPane or return to the table of contents.