<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to you under the Apache License,
Version 2.0 (the "License"); you may not use this file except in
compliance with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<document id="list-buttons">
    <properties>
        <title>List Buttons</title>
    </properties>

    <body>
        <p>The following example demonstrates use of the <tt>ListButton</tt> component. Selecting an image name from the drop-down shows the corresponding image file in the image view on the right.</p>

        <application class="org.apache.pivot.wtk.ScriptApplication"
            width="480" height="340">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <src>/org/apache/pivot/tutorials/lists/list_buttons.bxml</src>
            </startup-properties>
        </application>

        <p>
            The BXML source for the example is below. Like the previous example, list data is
            specified as an attribute containing a JSON array of strings; this value is used to
            load the image displayed to the right of the list button. Like <tt>ListView</tt>,
            <tt>ListButtons</tt> can also be populated programmatically using instances of
            <tt>ListItem</tt>.
        </p>

        <source type="xml" location="org/apache/pivot/tutorials/lists/list_buttons.bxml">
            <![CDATA[
            <lists:ListButtons title="List Buttons" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns:lists="org.apache.pivot.tutorials.lists"
                xmlns="org.apache.pivot.wtk">
                <TablePane styles="{showHorizontalGridLines: true, showVerticalGridLines:true,
                    horizontalSpacing:1, verticalSpacing:1}">
                    <columns>
                        <TablePane.Column width="-1"/>
                        <TablePane.Column width="1*"/>
                    </columns>

                    <TablePane.Row height="340">
                        <BoxPane orientation="vertical" styles="{verticalAlignment:'top', padding: 4}">
                            <Label text="Picture:"/>
                            <ListButton bxml:id="listButton"
                                listData="['IMG_0725_2.jpg', 'IMG_0735_2.jpg', 'IMG_0767_2.jpg']"/>
                        </BoxPane>

                        <ImageView bxml:id="imageView" styles="{backgroundColor:'#404040'}"/>
                    </TablePane.Row>
                </TablePane>
            </lists:ListButtons>
            ]]>
        </source>

        <p>
            The Java source for the example is below:
        </p>

        <source type="java" location="org/apache/pivot/tutorials/lists/ListButtons.java">
            <![CDATA[
            package org.apache.pivot.tutorials.lists;

            import java.net.URL;

            import org.apache.pivot.beans.Bindable;
            import org.apache.pivot.collections.Map;
            import org.apache.pivot.util.Resources;
            import org.apache.pivot.util.concurrent.TaskExecutionException;
            import org.apache.pivot.wtk.ApplicationContext;
            import org.apache.pivot.wtk.ImageView;
            import org.apache.pivot.wtk.ListButton;
            import org.apache.pivot.wtk.ListButtonSelectionListener;
            import org.apache.pivot.wtk.Window;
            import org.apache.pivot.wtk.media.Image;

            public class ListButtons extends Window implements Bindable {
                private ListButton listButton = null;
                private ImageView imageView = null;

                @Override
                public void initialize(Map<String, Object> namespace, URL location, Resources resources) {
                    listButton = (ListButton)namespace.get("listButton");
                    imageView = (ImageView)namespace.get("imageView");

                    listButton.getListButtonSelectionListeners().add(new ListButtonSelectionListener.Adapter() {
                        @Override
                        public void selectedItemChanged(ListButton listButton, Object previousSelectedItem) {
                            Object selectedItem = listButton.getSelectedItem();

                            if (selectedItem != null) {
                                // Get the image URL for the selected item
                                ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
                                URL imageURL = classLoader.getResource("org/apache/pivot/tutorials/" + selectedItem);

                                // If the image has not been added to the resource cache yet,
                                // add it
                                Image image = (Image)ApplicationContext.getResourceCache().get(imageURL);

                                if (image == null) {
                                    try {
                                        image = Image.load(imageURL);
                                    } catch (TaskExecutionException exception) {
                                        throw new RuntimeException(exception);
                                    }

                                    ApplicationContext.getResourceCache().put(imageURL, image);
                                }

                                // Update the image
                                imageView.setImage(image);
                            }
                        }
                    });

                    listButton.setSelectedIndex(0);
                }
            }
            ]]>
        </source>

        <p>
            This example makes use of the global resource cache to store the loaded images.
            This cache can be used to store any kind of application-specific data that may
            be expensive to load. Entries are keyed by the URL from which they were retrieved, and,
            once placed in the cache, are available to all code within the application. When the
            list button's selection changes, the application first looks for an image in the
            resource cache; if it is not found, it is loaded and added to the cache.
            It is then set as the "image" property of the image view and displayed.
            Note that the global cache does not have a way to limiting the number of elements
            to contain, so the cache continues to grow; to keep it small you have
            to manually remove old elements from it when they are no more necessary.
        </p>
    </body>
</document>