| <?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.Style; |
| 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(Style.font, new Font("Arial", Font.BOLD, 24)); |
| label.getStyles().put(Style.color, Color.RED); |
| label.getStyles().put(Style.horizontalAlignment, |
| HorizontalAlignment.CENTER); |
| label.getStyles().put(Style.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><applet></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> |
