<?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="windows">
    <properties>
        <title>Windows</title>
    </properties>

    <body>
        <p>
            Though every tutorial example thus far has used windows, Pivot's actual window classes
            have not yet been explicitly discussed. This is because, for many applications
            (especially those that are browser-based), a single main application window is
            sufficient. However, more complex applications often require multiple windows, allowing
            a user to see and interact with a variety of information.
        </p>

        <p>
            Though the root of the WTK component hierarchy is an instance of <tt>Display</tt>,
            windows generally represent an application's primary entry point into the UI. Windows
            are always direct descendants of the display. They represent a place on the screen
            where the application can draw or place user interface elements.
        </p>

        <p>
            The class diagram below shows the Pivot window class hierarchy (though it is not shown
            in this diagram, Window actually extends Container, which extends Component, the root
            of all WTK UI classes):
        </p>

        <p><img src="windows/windows.png"/></p>
        <p class="caption">Window class hierarchy.</p>

        <p>The following is a description of each window type:</p>

        <ul>
            <li>
                <p>
                    <b>Window</b> - Base window class; it is not abstract and is the most basic
                    means by which content may be placed on the screen. It simply provides an
                    undecorated region in which other components may be placed.
                </p>
            </li>
            <li>
                <p>
                    <b>Frame</b> - A window with a title bar and border for dragging and resizing.
                </p>
            </li>
            <li>
                <p>
                    <b>Dialog</b> - A frame that is generally used for collecting user input
                    (engaging in a "dialog" with the user); may optionally be "modal", blocking
                    input to its owner.
                </p>
            </li>
            <li>
                <p>
                    <b>Alert</b> - A dialog that is generally used to present brief notifications
                    to the user.
                </p>
            </li>
            <li>
                <p>
                    <b>Sheet</b> - A window that, like a dialog, is generally used for collecting
                    user input; however, unlike dialogs, sheets always have an owner, and are
                    always modal over the owner's client area.
                </p>
            </li>
            <li>
                <p>
                    <b>Prompt</b> - A sheet that is generally used to present brief notifications
                    to the user; the sheet equivalent of <tt>Alert</tt>.
                </p>
            </li>
            <li>
                <p>
                    <b>MenuPopup</b> - A popup window that is used to present a menu to the user.
                    It can be used stand-alone as a context menu, but is also used by other
                    components including <tt>MenuBar</tt> and <tt>MenuButton</tt>.
                </p>
            </li>
            <li>
                <p>
                    <b>SuggestionPopup</b> - A popup window that provides "auto-complete"
                    functionality for a text input.
                </p>
            </li>
            <li>
                <p>
                    <b>Palette</b> - A floating tool palette window.
                </p>
            </li>
            <li>
                <p>
                    <b>FileBrowserSheet</b> - A sheet that allows the user to browse the local file
                    system.
                </p>
            </li>
            <li>
                <p>
                    <b>Tooltip</b> - A small, popup-like window that disappears as soon as the
                    user moves the mouse.
                </p>
            </li>
        </ul>

        <p>
            Most of the tutorial examples up to this point have used a single, maximized,
            decorationless <tt>Window</tt> to host their example content, since this type of user
            interface is well-suited to browser-based deployment as employed by this tutorial.
            However, Pivot applications are not limited to this sort of interface. Just like a
            native windowing toolkit, a Pivot application can open as many windows on the display
            of as many different types as are required by the application.
        </p>

        <p>
            The following sample application demonstrates many of these window types. It creates
            three top-level frames, each of which contains buttons for launching several other
            window types:
        </p>

        <application class="org.apache.pivot.tutorials.windows.Windows" width="720" height="600">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
        </application>

        <p>The content of each frame is defined in "frame.bxml":</p>

        <source type="xml" location="org/apache/pivot/tutorials/windows/frame.bxml">
            <![CDATA[
            <Frame bxml:id="frame" icon="@application_form.png"
                preferredWidth="480" preferredHeight="360"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns:content="org.apache.pivot.wtk.content"
                xmlns="org.apache.pivot.wtk">
                <bxml:define>
                    <bxml:include bxml:id="dialog" src="dialog.bxml"/>
                    <bxml:include bxml:id="sheet" src="sheet.bxml"/>
                </bxml:define>

                <bxml:script>
                var palette = null;
                </bxml:script>

                <BoxPane orientation="vertical">
                    <PushButton buttonData="Show Alert">
                        <buttonPressListeners>
                            importPackage(org.apache.pivot.wtk);
                            function buttonPressed(button) {
                                Alert.alert("This is an Alert.", frame);
                            }
                        </buttonPressListeners>
                    </PushButton>

                    <PushButton buttonData="Show Prompt">
                        <buttonPressListeners>
                            importPackage(org.apache.pivot.wtk);
                            function buttonPressed(button) {
                                Prompt.prompt("This is a Prompt.", frame);
                            }
                        </buttonPressListeners>
                    </PushButton>

                    <PushButton buttonData="Show Dialog">
                        <buttonPressListeners>
                            importPackage(org.apache.pivot.wtk);
                            function buttonPressed(button) {
                                dialog.open(frame, null);
                            }
                        </buttonPressListeners>
                    </PushButton>

                    <PushButton buttonData="Show Sheet">
                        <buttonPressListeners>
                            importPackage(org.apache.pivot.wtk);
                            function buttonPressed(button) {
                                sheet.open(frame, null);
                            }
                        </buttonPressListeners>
                    </PushButton>

                    <PushButton buttonData="Show Palette">
                        <buttonPressListeners>
                            importPackage(org.apache.pivot.wtk);
                            function buttonPressed(button) {
                                if (palette == null) {
                                    palette = application.load("palette.bxml");
                                    palette.setLocation(frame.getX() + frame.getWidth() + 20, frame.getY() + 20);
                                }

                                palette.open(frame);
                            }
                        </buttonPressListeners>
                    </PushButton>
                </BoxPane>
            </Frame>
            ]]>
        </source>
        <p class="caption">frame.bxml</p>

        <p>
            This file includes several additional BXML files that define the dialog, sheet, and
            palette windows opened by the main frame:
        </p>

        <source type="xml" location="org/apache/pivot/tutorials/windows/dialog.bxml">
            <![CDATA[
            <Dialog bxml:id="dialog" title="Dialog" modal="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns="org.apache.pivot.wtk">
                <TablePane preferredWidth="320" preferredHeight="210">
                    <columns>
                        <TablePane.Column width="1*"/>
                    </columns>

                    <TablePane.Row height="1*">
                        <Label text="This is a dialog."
                            preferredWidth="320" preferredHeight="210"
                            styles="{horizontalAlignment:'center', verticalAlignment:'center'}"/>
                    </TablePane.Row>

                    <TablePane.Row height="-1">
                        <BoxPane styles="{horizontalAlignment:'right'}">
                            <PushButton buttonData="Close"
                                ButtonPressListener.buttonPressed="dialog.close()"/>
                        </BoxPane>
                    </TablePane.Row>
                </TablePane>
            </Dialog>
            ]]>
        </source>
        <p class="caption">dialog.bxml</p>

        <source type="xml" location="org/apache/pivot/tutorials/windows/sheet.bxml">
            <![CDATA[
            <Sheet bxml:id="sheet" title="Sheet"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns="org.apache.pivot.wtk">
                <BoxPane styles="{verticalAlignment:'bottom'}">
                    <TablePane>
                        <columns>
                            <TablePane.Column width="1*"/>
                        </columns>

                        <TablePane.Row height="1*">
                            <Label text="This is a sheet."
                                preferredWidth="320" preferredHeight="210"
                                styles="{horizontalAlignment:'center', verticalAlignment:'center'}"/>
                        </TablePane.Row>

                        <TablePane.Row height="-1">
                            <BoxPane styles="{horizontalAlignment:'right'}">
                                <PushButton buttonData="Close"
                                    ButtonPressListener.buttonPressed="sheet.close()"/>
                            </BoxPane>
                        </TablePane.Row>
                    </TablePane>
                </BoxPane>
            </Sheet>
            ]]>
        </source>
        <p class="caption">sheet.bxml</p>

        <source type="xml" location="org/apache/pivot/tutorials/windows/palette.bxml">
            <![CDATA[
            <Palette title="Palette" preferredWidth="60" preferredHeight="120"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns="org.apache.pivot.wtk">
                <FlowPane styles="{padding:1}">
                    <PushButton buttonData="1" styles="{toolbar:true, minimumAspectRatio:1, maximumAspectRatio:1}"/>
                    <PushButton buttonData="2" styles="{toolbar:true, minimumAspectRatio:1, maximumAspectRatio:1}"/>
                    <PushButton buttonData="3" styles="{toolbar:true, minimumAspectRatio:1, maximumAspectRatio:1}"/>
                    <PushButton buttonData="4" styles="{toolbar:true, minimumAspectRatio:1, maximumAspectRatio:1}"/>
                    <PushButton buttonData="5" styles="{toolbar:true, minimumAspectRatio:1, maximumAspectRatio:1}"/>
                    <PushButton buttonData="6" styles="{toolbar:true, minimumAspectRatio:1, maximumAspectRatio:1}"/>
                </FlowPane>
            </Palette>
            ]]>
        </source>
        <p class="caption">palette.bxml</p>

        <p>
            The application code simply instantiates three <tt>Frame</tt> objects and sets the
            component read from the BXML as the frames' contents:
        </p>

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

            import java.io.IOException;

            import org.apache.pivot.beans.BXMLSerializer;
            import org.apache.pivot.collections.Map;
            import org.apache.pivot.serialization.SerializationException;
            import org.apache.pivot.wtk.Application;
            import org.apache.pivot.wtk.DesktopApplicationContext;
            import org.apache.pivot.wtk.Display;
            import org.apache.pivot.wtk.Frame;
            import org.apache.pivot.wtk.Window;

            public class Windows implements Application {
                private Display display = null;

                @Override
                public void startup(Display display, Map<String, String> properties) throws Exception {
                    this.display = display;

                    int x = 0;
                    int y = 0;

                    for (int i = 0; i < 3; i++) {
                        BXMLSerializer bxmlSerializer = new BXMLSerializer();
                        bxmlSerializer.getNamespace().put("application", this);

                        Frame frame;
                        try {
                            frame = (Frame)bxmlSerializer.readObject(Windows.class, "frame.bxml");
                        } catch (SerializationException exception) {
                            throw new RuntimeException(exception);
                        } catch (IOException exception) {
                            throw new RuntimeException(exception);
                        }

                        frame.setTitle("Frame " + (i + 1));
                        frame.setLocation(x, y);
                        x += 20;
                        y += 20;

                        frame.open(display);
                    }
                }

                @Override
                public boolean shutdown(boolean optional) {
                    for (int i = display.getLength() - 1; i >= 0; i--) {
                        Window window = (Window)display.get(i);
                        window.close();
                    }

                    return false;
                }

                @Override
                public void suspend() {
                }

                @Override
                public void resume() {
                }

                public Window load(String fileName)
                    throws SerializationException, IOException {
                    BXMLSerializer bxmlSerializer = new BXMLSerializer();
                    return (Window)bxmlSerializer.readObject(Windows.class, fileName);
                }

                public static void main(String[] args) {
                    DesktopApplicationContext.main(Windows.class, args);
                }
            }
            ]]>
        </source>
    </body>
</document>
