Lists

List components in Pivot include ListView and ListButton. ListView is a (often scrollable) list of items of which one or more may be selected. ListButton is a popup list of items of which only one may be selected at a time. It is often used in place of a group of radio buttons, particularly when space is limited.

ListButton is discussed in the next section. The following example demonstrates the ListView component. Multiple items may be selected at a time, and list selections are reflected in the label to the right.

The WTKX source for the example follows. Note that the list view is itself contained within a ScrollPane. List views do not support scrolling internally. This allows a UI designer to place a list view within an application and have the list view simply grow to accommodate its contents, rather than requiring the designer to specify a fixed height for the list in advance. However, if the designer knows that the list will be long and that it is likely to scroll, it can be placed in a scroll pane. ScrollPane is discussed in more detail in the Navigation Containers section.

Also note that the list's contents are specified in the WTKX document itself, as a JSON array of strings in the listData attribute. List items can also be defined programmatically using an instance of pivot.wtk.content.ListItem in a nested listData element.

<Window title="List Views" maximized="true"
    xmlns:wtkx="http://pivot.apache.org/wtkx"
    xmlns="org.apache.pivot.wtk">
    <content>
        <BoxPane styles="{padding:4, spacing:4}">
            <Border styles="{padding:0, color:10}">
                <content>
                    <ScrollPane preferredWidth="80" preferredHeight="110"
                        horizontalScrollBarPolicy="fill"
                        verticalScrollBarPolicy="fill_to_capacity">
                        <view>
                            <ListView wtkx:id="listView" selectMode="multi"
                                listData="['One', 'Two', 'Three', 'Four', 'Five',
                                    'Six', 'Seven', 'Eight', 'Nine', 'Ten']"/>
                        </view>
                    </ScrollPane>
                </content>
            </Border>
            <BoxPane orientation="vertical" preferredWidth="120" styles="{fill:true}">
                <Label text="You selected:"/>
                <Label wtkx:id="selectionLabel" styles="{wrapText:true}"/>
            </BoxPane>
        </BoxPane>
    </content>
</Window>

The Java code for the example also uses the list data to populate the label component as the list selection changes. A ListView's selection is represented by a sorted list of pivot.wtk.Span objects that contain the currently selected ranges; the application retrieves the list of currently selected ranges and then constructs the label's text by appending each selected item to the string:

package org.apache.pivot.tutorials.lists;

import org.apache.pivot.collections.Map;
import org.apache.pivot.collections.Sequence;
import org.apache.pivot.wtk.Application;
import org.apache.pivot.wtk.DesktopApplicationContext;
import org.apache.pivot.wtk.Display;
import org.apache.pivot.wtk.Label;
import org.apache.pivot.wtk.ListView;
import org.apache.pivot.wtk.ListViewSelectionListener;
import org.apache.pivot.wtk.Span;
import org.apache.pivot.wtk.Window;
import org.apache.pivot.wtkx.WTKXSerializer;

public class ListViews implements Application {
    private Window window = null;
    private Label selectionLabel = null;
    private ListView listView = null;

    private ListViewSelectionListener listViewSelectionListener =
        new ListViewSelectionListener() {
        public void selectedRangeAdded(ListView listView, int rangeStart, int rangeEnd) {
            updateSelection(listView);
        }

        public void selectedRangeRemoved(ListView listView, int rangeStart, int rangeEnd) {
            updateSelection(listView);
        }

        public void selectedRangesChanged(ListView listView, Sequence<Span> previousSelectedRanges) {
            updateSelection(listView);
        }

        private void updateSelection(ListView listView) {
            String selectionText = "";

            Sequence<Span> selectedRanges = listView.getSelectedRanges();
            for (int i = 0, n = selectedRanges.getLength(); i < n; i++) {
                Span selectedRange = selectedRanges.get(i);

                for (int j = selectedRange.getStart();
                    j <= selectedRange.getEnd();
                    j++) {
                    if (selectionText.length() > 0) {
                        selectionText += ", ";
                    }

                    String text = (String)listView.getListData().get(j);
                    selectionText += text;
                }
            }

            selectionLabel.setText(selectionText);
        }
    };

    public void startup(Display display, Map<String, String> properties)
        throws Exception {
        WTKXSerializer wtkxSerializer = new WTKXSerializer();
        window = (Window)wtkxSerializer.readObject(this, "list_views.wtkx");
        selectionLabel = (Label)wtkxSerializer.get("selectionLabel");
        listView = (ListView)wtkxSerializer.get("listView");

        listView.getListViewSelectionListeners().add(listViewSelectionListener);

        window.open(display);
    }

    public boolean shutdown(boolean optional) {
        if (window != null) {
            window.close();
        }

        return false;
    }

    public void suspend() {
    }

    public void resume() {
    }

    public static void main(String[] args) {
        DesktopApplicationContext.main(ListViews.class, args);
    }
}

Next: List Buttons