<?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="hello-bxml">
    <properties>
        <title>Hello, BXML!</title>
    </properties>

    <body>
        <p>
            Below is the output of the "hello world" application written using BXML. Note that,
            with the exception of the actual text, it is identical to the output of the Java
            version:
        </p>

        <application class="org.apache.pivot.tutorials.HelloBXML"
            width="240" height="80">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
        </application>

        <p>
            The following is the Java source code for the BXML version. The content of the user
            interface is defined entirely by the BXML source file. It is loaded using an instance
            of the <tt>BXMLSerializer</tt> class defined in the <tt>org.apache.pivot.bxml</tt>
            package.
        </p>

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

            import org.apache.pivot.beans.BXMLSerializer;
            import org.apache.pivot.collections.Map;
            import org.apache.pivot.wtk.Application;
            import org.apache.pivot.wtk.Display;
            import org.apache.pivot.wtk.Window;

            public class HelloBXML implements Application {
                private Window window = null;

                @Override
                public void startup(Display display, Map<String, String> properties)
                    throws Exception {
                    BXMLSerializer bxmlSerializer = new BXMLSerializer();
                    window = (Window)bxmlSerializer.readObject(HelloBXML.class, "hello.bxml");
                    window.open(display);
                }

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

                    return false;
                }

                @Override
                public void suspend() {
                }

                @Override
                public void resume() {
                }
            }
            ]]>
        </source>

        <p>
            The BXML that is used to create the UI is shown below:
        </p>

        <source type="xml" location="org/apache/pivot/tutorials/hello.bxml">
            <![CDATA[
            <Window title="Hello BXML!" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns="org.apache.pivot.wtk">
                <Label text="Hello BXML!"
                    styles="{font:'Arial bold 24', color:'#ff0000',
                        horizontalAlignment:'center', verticalAlignment:'center'}"/>
            </Window>
            ]]>
        </source>

        <p>
            Most Pivot applications will be constructed this way, declaring the structure of the
            UI in BXML rather than creating it programmatically in code. However, event handlers,
            which allow an application to respond to user input, are always defined in code (either
            Java or a compatible JVM scripting language). For example, the following BXML produces
            output very similar to the previous two versions, using a combination of BXML and
            JavaScript:
        </p>

        <source type="xml" location="org/apache/pivot/tutorials/hello_javascript.bxml">
            <![CDATA[
            <Window title="Hello JavaScript!" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns="org.apache.pivot.wtk">
                <windowStateListeners>
                    importPackage(org.apache.pivot.wtk);

                    function windowOpened(window) {
                        var label = new Label();
                        label.setText("Hello JavaScript!");
                        label.getStyles().put("font", "Arial BOLD 24");
                        label.getStyles().put("color", "#ff0000");
                        label.getStyles().put("horizontalAlignment", HorizontalAlignment.CENTER);
                        label.getStyles().put("verticalAlignment", VerticalAlignment.CENTER);

                        window.setContent(label);
                    }
                </windowStateListeners>
            </Window>
            ]]>
        </source>

        <p>
            The output of this version is shown below:
        </p>

        <application class="org.apache.pivot.wtk.ScriptApplication"
            width="240" height="80">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <src>/org/apache/pivot/tutorials/hello_javascript.bxml</src>
            </startup-properties>
        </application>

        <p>
            Note that this example does not provide an implementation of the <tt>Application</tt>
            interface. Rather, it is launched using the <tt>org.apache.pivot.wtk.ScriptApplication</tt> class.
            This class, which is included with the Pivot platform, implements the
            <tt>Application</tt> interface and takes the name of a BXML file to launch as a startup
            property named <tt>src</tt>. The source file is expected to contain a root element representing a
            <tt>Window</tt> subclass.
        </p>

        <p>
            The class is named <tt>ScriptApplication</tt> because it is often used to launch
            applications whose logic is defined entirely in script; however, it can actually be
            used to launch any application whose main window is defined in a single BXML file. Many
            of the examples in the following sections are executed using this class.
            Scripting is discussed in more detail in the <a href="scripting.html">Scripting</a> section.
        </p>
    </body>
</document>