<?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-world">
    <properties>
        <title>Hello, World!</title>
    </properties>

    <body>
        <p>
            Below is the output of the traditional "hello world" application written in Pivot:
        </p>

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

        <p>
            This version of the application was written entirely in Java and is shown below; a BXML
            example is shown in the next section:
        </p>

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

            import java.awt.Color;
            import java.awt.Font;

            import org.apache.pivot.collections.Map;
            import org.apache.pivot.wtk.Application;
            import org.apache.pivot.wtk.Display;
            import org.apache.pivot.wtk.HorizontalAlignment;
            import org.apache.pivot.wtk.Label;
            import org.apache.pivot.wtk.VerticalAlignment;
            import org.apache.pivot.wtk.Window;

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

                @Override
                public void startup(Display display, Map<String, String> properties) {
                    window = new Window();

                    Label label = new Label();
                    label.setText("Hello World!");
                    label.getStyles().put("font", new Font("Arial", Font.BOLD, 24));
                    label.getStyles().put("color", Color.RED);
                    label.getStyles().put("horizontalAlignment",
                        HorizontalAlignment.CENTER);
                    label.getStyles().put("verticalAlignment",
                        VerticalAlignment.CENTER);

                    window.setContent(label);
                    window.setTitle("Hello World!");
                    window.setMaximized(true);

                    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 program demonstrates some of the fundamental features of the Pivot platform: the
            <tt>Application</tt> interface, the <tt>Window</tt> class, and styles.
        </p>

        <h3>The Application Interface</h3>
        <p>
            The Application interface is the entry point into a Pivot application. It is similar to
            the <tt>main()</tt> method used in C and Java programming or the lifecycle methods used
            in traditional Java applet development. It defines the following four methods:
        </p>

        <ul>
            <li>
                <tt>startup()</tt> - called when an application is starting up
            </li>
            <li>
                <tt>shutdown()</tt> - called when a running application is shutting down
            </li>
            <li>
                <tt>suspend()</tt> - called when an application is temporarily deactivated
            </li>
            <li>
                <tt>resume()</tt> - called when a suspended application is resumed
            </li>
        </ul>

        <p>
            However, unlike <tt>main()</tt> or the applet lifecycle methods, which require a
            separate code base for each environment, <tt>Application</tt> defines a single
            interface that is used for both web deployment or desktop execution, allowing the same
            program to run unmodified in either environment.
        </p>

        <p>
            A Pivot application can be run in the browser using the <tt>&lt;applet&gt;</tt> tag, as
            shown below; the class name of the Pivot application is specified by the
            "application_class_name" applet parameter (see
            <a href="http://java.sun.com/javase/6/docs/technotes/guides/jweb/deployment_advice.html#deplToolkit">this article</a>
            for more information on how to deploy Java applets):
        </p>

        <source type="html">
            <![CDATA[
            <applet code="org.apache.pivot.wtk.BrowserApplicationContext$HostApplet"
                archive="lib/pivot-core-[version].jar,lib/pivot-wtk-[version].jar,lib/pivot-wtk-terra-[version].jar,lib/pivot-tutorials-[version].jar"
                width="160" height="80">
                <param name="application_class_name" value="org.apache.pivot.tutorials.HelloJava">
            </applet>
            ]]>
        </source>

        <p>
            The same application can be run from the command line using the following syntax (minus
            the line breaks) on UNIX-based systems:
        </p>

        <p>
            <tt>java -cp pivot-core-<i>[version]</i>.jar:pivot-wtk-<i>[version]</i>.jar:
            pivot-wtk-terra-<i>[version]</i>.jar:pivot-tutorials-<i>[version]</i>.jar
            org.apache.pivot.wtk.DesktopApplicationContext org.apache.pivot.tutorials.HelloJava</tt>
        </p>

        <p>
            and the following on Windows systems:
        </p>

        <p>
            <tt>java -cp pivot-core-<i>[version]</i>.jar;pivot-wtk-<i>[version]</i>.jar;
            pivot-wtk-terra-<i>[version]</i>.jar;pivot-tutorials-<i>[version]</i>.jar
            org.apache.pivot.wtk.DesktopApplicationContext org.apache.pivot.tutorials.HelloJava</tt>
        </p>

        <p>
            Note that (for offline testing purposes) <tt>pivot-tutorials-<i>[version]</i>.jar</tt>
            is not provided directly in binary distribution, but it's inside generated war files
            (under the lib folder). Otherwise, you can build it from sources.
        </p>

       <p>
            The application class name is specified as the first argument to the
            <tt>DesktopApplicationContext</tt> loader application.
        </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/HelloJava.java">
            <![CDATA[
                public static void main(String[] args) {
                    DesktopApplicationContext.main(HelloJava.class, args);
                }
            ]]>
        </source>


        <br/>
        <h3>The Window Class</h3>
        <p>
            A window is the top-level entry point into an application's user interface. Almost all
            Pivot applications will use at least one window.
        </p>

        <p>
            The window in the sample application is an instance of <tt>Window</tt>, the most basic
            window type. It is simply an undecorated area of the screen into which other components
            may be placed. Other window types, such as <tt>Dialog</tt> and <tt>Frame</tt>, add
            additional features and behaviors such as title bars and modality.
        </p>

        <p>
            The window used by "Hello World" is "maximized": it automatically fills the entire area
            of the display. A maximized, decorationless window is commonly used as a top-level
            application window, particularly for applications that will be primarily run in a web
            browser. However, windows can also be given an explicit size, can be resized by the
            user, or can take on the default size of their content. Windows are discussed in more
            detail in the <a href="windows.html">Windows</a> section.
        </p>

        <br/>
        <h3>Styles</h3>
        <p>
            Styles are a means of customizing a component's appearance. Style properties are
            defined by a component's skin and are accessed via a component's styles collection. For
            example, the example application sets the font, color, and alignment styles on the
            "Hello World" label. Though skins are not required to provide styling support, most
            will provide similar capabilities.
        </p>

        <br/>

    </body>
</document>
