<?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="file-browsing">
    <properties>
        <title>File Browsing</title>
    </properties>

    <body>
        <p>
            Pivot includes support for easily adding local file system access to an application.
            The following example demonstrates the use of the <tt>FileBrowserSheet</tt> class:
        </p>

        <application class="org.apache.pivot.wtk.ScriptApplication"
            width="640" height="480">
            <libraries signed="true">
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <src>/org/apache/pivot/tutorials/filebrowsing/file_browsing.bxml</src>
            </startup-properties>
        </application>

        <p>
            It allows the user to browse the local file system using one of four supported modes:
        </p>

        <ul>
            <li><p><b>Open</b> - select a single file to open</p></li>
            <li><p><b>Open Multiple</b> - select multiple files to open</p></li>
            <li><p><b>Save As</b> - select a file name to save as</p></li>
            <li><p><b>Save To</b> - select a folder to save to</p></li>
        </ul>

        <p>
            The BXML source for the application is as follows:
        </p>

        <source type="xml" location="org/apache/pivot/tutorials/filebrowsing/file_browsing.bxml">
            <![CDATA[
            <filebrowsing:FileBrowsing title="File Browsing" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns:filebrowsing="org.apache.pivot.tutorials.filebrowsing"
                xmlns="org.apache.pivot.wtk">
                <bxml:define>
                    <ButtonGroup bxml:id="fileBrowserSheetModeGroup"/>
                </bxml:define>

                <Border styles="{padding:6}">
                    <BoxPane orientation="vertical" styles="{spacing:6}">
                        <Label text="Mode:" styles="{font:{bold:true}}"/>

                        <RadioButton buttonData="Open" buttonGroup="$fileBrowserSheetModeGroup" selected="true">
                            <userData mode="open"/>
                        </RadioButton>
                        <RadioButton buttonData="Open Multiple" buttonGroup="$fileBrowserSheetModeGroup">
                            <userData mode="open_multiple"/>
                        </RadioButton>
                        <RadioButton buttonData="Save As" buttonGroup="$fileBrowserSheetModeGroup">
                            <userData mode="save_as"/>
                        </RadioButton>
                        <RadioButton buttonData="Save To" buttonGroup="$fileBrowserSheetModeGroup">
                            <userData mode="save_to"/>
                        </RadioButton>

                        <PushButton bxml:id="openSheetButton" buttonData="Open Sheet"/>
                    </BoxPane>
                </Border>
            </filebrowsing:FileBrowsing>
            ]]>
        </source>

        <p>
            The Java source code is shown below. When the user presses the "Open Sheet" button,
            it creates a <tt>FileBrowserSheet</tt> using the selected mode and opens the sheet.
            When the sheet is closed, it simply displays an alert to the user reflecting the
            selection:
        </p>

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

            import java.io.File;
            import java.net.URL;

            import org.apache.pivot.beans.BXML;
            import org.apache.pivot.beans.Bindable;
            import org.apache.pivot.collections.ArrayList;
            import org.apache.pivot.collections.Map;
            import org.apache.pivot.collections.Sequence;
            import org.apache.pivot.util.Resources;
            import org.apache.pivot.wtk.Alert;
            import org.apache.pivot.wtk.Button;
            import org.apache.pivot.wtk.ButtonGroup;
            import org.apache.pivot.wtk.ButtonPressListener;
            import org.apache.pivot.wtk.FileBrowserSheet;
            import org.apache.pivot.wtk.ListView;
            import org.apache.pivot.wtk.MessageType;
            import org.apache.pivot.wtk.PushButton;
            import org.apache.pivot.wtk.Sheet;
            import org.apache.pivot.wtk.SheetCloseListener;
            import org.apache.pivot.wtk.Window;

            public class FileBrowsing extends Window implements Bindable {
                @BXML private ButtonGroup fileBrowserSheetModeGroup = null;
                @BXML private PushButton openSheetButton = null;

                @Override
                public void initialize(Map<String, Object> namespace, URL location, Resources resources) {
                    openSheetButton.getButtonPressListeners().add(new ButtonPressListener() {
                        @Override
                        public void buttonPressed(Button button) {
                            Button selection = fileBrowserSheetModeGroup.getSelection();

                            String mode = (String)selection.getUserData().get("mode");
                            FileBrowserSheet.Mode fileBrowserSheetMode = FileBrowserSheet.Mode.valueOf(mode.toUpperCase());
                            final FileBrowserSheet fileBrowserSheet = new FileBrowserSheet();

                            if (fileBrowserSheetMode == FileBrowserSheet.Mode.SAVE_AS) {
                                fileBrowserSheet.setSelectedFile(new File(fileBrowserSheet.getRootDirectory(), "New File"));
                            }

                            fileBrowserSheet.setMode(fileBrowserSheetMode);
                            fileBrowserSheet.open(FileBrowsing.this, new SheetCloseListener() {
                                @Override
                                public void sheetClosed(Sheet sheet) {
                                    if (sheet.getResult()) {
                                        Sequence<File> selectedFiles = fileBrowserSheet.getSelectedFiles();

                                        ListView listView = new ListView();
                                        listView.setListData(new ArrayList<File>(selectedFiles));
                                        listView.setSelectMode(ListView.SelectMode.NONE);
                                        listView.getStyles().put("backgroundColor", null);

                                        Alert.alert(MessageType.INFO, "You selected:", listView, FileBrowsing.this);
                                    } else {
                                        Alert.alert(MessageType.INFO, "You didn't select anything.", FileBrowsing.this);
                                    }
                                }
                            });
                        }
                    });
                }
            }
            ]]>
        </source>

        <p>
            Note that, internally, <tt>FileBrowserSheet</tt> uses an instance of the
            <tt>org.apache.pivot.wtk.FileBrowser</tt> class to perform the actual file system
            navigation. It is actually possible to use this component directly within an
            application to create a custom file browser; however, a discussion of the
            <tt>FileBrowser</tt> class is outside the scope of this tutorial.
        </p>
    </body>
</document>
