<?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>
            You can run this example as a Standard Java Application executing ScriptApplication in the following way:<br/>
            org.apache.pivot.wtk.ScriptApplication --src=/org/apache/pivot/tutorials/hello.bxml
        </p>

        <p>
            Note that you can even add the main() method to be able to run the class as
            Standard Java Application in the usual way.
        </p>
        <source type="java" location="org/apache/pivot/tutorials/HelloBXML.java">
            <![CDATA[
                public static void main(String[] args) {
                    DesktopApplicationContext.main(HelloBXML.class, args);
                }
            ]]>
        </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>
            You can run this example as a Standard Java Application executing ScriptApplication in the following way:<br/>
            org.apache.pivot.wtk.ScriptApplication --src=/org/apache/pivot/tutorials/hello_javascript.bxml
        </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>

        <p>
            Accessing BXML resources is the same as accessing any other kind of resources from within a Java application,
            following the same rules of standard ClassLoader resource retrieval methods.
            <br/>
            Note that it's not mandatory to use BXML files within Pivot (all could be done in Java or any JVM compatible language),
            but BXML is a much more convenient method for specifying the UI layout.
        </p>

        <br/>

    </body>
</document>
