number of ratings	1
average rating	4.00

8 Getting started

In this chapter we will see how to build some simple Carousel applications using both Java and XML. We will see all the features needed to build a fully functional application within Carousel in action. The chapter provides an introduction to the setup mechanisms used within a Carousel application. Most of the features described can be configured interactively but to aid understanding they are explained at a lower level.

The chapter assumes that you have already encountered the features described in the previous chapter and that you have a basic understanding of how Java based applications function.

Don't worry if you do not understand all the nuances of the technology described as the various pieces of the application are but together. Later chapters are devoted to the individual features employed.

If you are new to Java we recommend that you study some of the numerous educational resources available on the Internet, some of which are listed in the appendix on Java ( "Learning Java" on page 340).

Hello world

Traditionally the first example used in many user guides is the infamous 'Hello World' example where the task is to emit or display the simple text 'Hello World'. In Carousel this is very simple, all you need do is create an XML file called ' home.xml ', preferably in a new folder. The XML file contains the declaration of the user interface needed for this task. It looks like the following:

Code Sample 8-1 - Page user-interface declaration

And that's just about it. The only other thing that is needed is a convenient way of starting the application. To do this we create a startup command file. This command file doesn't have to do very much other than invoking the Java environment and telling it what class to start. The start class in this case is the entry point to the Carousel framework or library. It contains the following command:

Code Sample 8-2 - Command-line startup

java -classpath .;XuiCore118.jar; net.xoetrope.awt.XApplet

The XuiCore118 jar is the minimum level of library support that can be used with Carousel. It is a version of the Carousel core compiled for early JDKs (including the Java environment embedded in Microsoft's Internet Explorer).

To use a fuller more functional JDK, for example to access the Swing toolkit instead of the AWT simply change the startup file to use this command:

Code Sample 8-3 - Command-line startup for Swing

java -classpath .;XuiCoreSwing.jar; net.xoetrope.swing.XApplet

Running this command will create a Swing user interface (UI) for the application. The two versions of the application should look pretty much the same.

This little example immediately shows a number of the benefits of Carousel and XML. Most obviously the UI declaration is very small and compact. Consider all the code needed to get such an example up and running in many languages. Secondly the approach of separating the UI declaration from the implementation makes it easy to switch that implementation, as shown above in switching from the AWT to Swing toolkits.

Hello world redux

Another much touted benefit of Carousel is its close integration with Java and the ability to declare the UI in XML or in Java. To emphasize this let's see how we can build the same thing in Java.

This time instead of creating ' home.xml ' we need to create a Java class. Using the normal naming conventions and capitalization we will call this class ' Home.java '. The Java code needed is as follows:

Code Sample 8-4 - Java UI class

import net.xoetrope.xui.*; import net.xoetrope.awt.*; public class Home extends XPage { public Home() { addComponent( XPage.LABEL, 32, 37, 100, 29, "Hello World" ); } }

Now while this isn't as compact as the XML declaration it is nonetheless a little more compact than the traditional Java code used for such an example.

To run this example there is of course another step required, that is, to compile the Java code. This can be done from the command-line, in the root directory of the project. Just type the following command:

Code Sample 8-5 - Command-line startup for compilation of the Java class

javac Home.java

This should create a file called ' Home.class ' in the same directory. The application can then be run in the very same way as the XML version. The underlying XUI will try loading an an XML file in preference to a Java class, so if it finds your XML file first then that will be used instead of the Java class even if the two files are in the same folder.

Beyond HelloWorld

While the HelloWorld examples offer a minimal way of getting started with Carousel it is not normal. Carousel can use many different resources and settings to configure and run an application. The HelloWorld examples relied on default settings for most of the Carousel configuration.

Normally Carousel applications are configured via a startup properties file. This file can be specified as a command-line argument:

Code Sample 8-6 - Command-line startup using a startup properties file

java -classpath .;XuiCore118.jar; net.xoetrope.awt.XApplet startup.properties

Or, if no command-line argument is provided Carousel will look for ' startup.properties '. (And remember that the startup file is regenerated by Carousel whenever an application is saved. Carousel itself uses a file project.xui to store the properties that are written to the startup.properties file).

It is also useful to separate the various components of an Carousel project into separate sub-directories. Thus the XML declarations for pages are put into the ' pages ' sub-directory, while the Java source files are places in the ' src ' sub-directory. Other resources such as images are placed in the ' resources ' sub-directory and finally localization files are placed in the ' lang ' subdirectory.

When using Carousel (as we will see in the next chapter), a special class/resource loader is built-in and can locate files in these subdirectories without the need for them to appear on the classpath.

The startup file contains settings that control much of how Carousel is configured. Some of the more commonly used configuration settings are shown below and could be used for the HelloWorld example.

Code Sample 8-7 - Startup properties

CenterWin=true ClientHeight=480 ClientWidth=640 StartClass=Home Title=A simple HelloWorld example StyleFile=styles.xml UseWindow=true StartPackage=xui.projects.helloworld

The purpose of these settings is as follows:

Table 8-1 - Startup parameters

Startup parameter	Usage
CentreWin	(true|false) Centers the application window on the screen when set to true.
ClientHeight	Set the height of the application window in pixels .
ClientWidth	Set the width of the application window in pixels.
StartClass	S ets the name of name of the initial class or XML file to display.
StartPackage	S ets the name of the package used for this application's Java classes. In the case of the HelloWorld examples no package was used so this setting could be omitted. The above example indicates that Carousel should look for a class called 'xui.projects.helloworld.Home.class'.
UseWindow	(true|false) Tells Carousel to use a Window without a border or use a normal application frame to hold the application.
StyleFile	Points to the name of a style file used to configure the colours and fonts in the application.

Building a simple address form

Most applications require user interaction and some data capture. Typical of this is entry of user details including name, telephone numbers and addresses.

This example goes beyond what was used in HelloWorld and shows some of the major steps in creating an attractive UI. We will start by creating a very simple form and then we will apply some style information to improve the look. In later sections this example will be expanded to produce a fully working, full featured form.

To start with we need a declaration of the input fields needed to capture the user input. We will use XML for this, and at its simplest this looks like the following:

Code Sample 8-8 - An address form/page declared in XML

In the above declaration the Label fields are all right aligned and the edit fields are all named. We name the edit fields as later we will want to interact with them programmatically.

This form is basic and does not include any formatting specific to any region. The address is comprised of three lines whereas most applications would further customize addresses for things like post or zip codes. We leave such customization as a user exercise as it will not affect the overall behavior of the form.

Note also that the form is laid out using absolute positioning and that in general it is better to use layout managers for the positioning of components (again, this will be covered in later chapters).

Generally the order in which the components are declared is of little importance, but it is in this order that the components are added to the container and therefore this dictates the z-order of the components. The z-order may be of interest if components overlap.

Applying style

To improve the appearance of the form we apply some styling information. This style information simply consists of the name of a style to use when rendering the component.

Carousel includes a style editor for interactively setting up the colours and fonts that comprise styles. These styles can then be interactively applied to a component or alternatively the styles can be applied via the Java code as the application executes.

The style details are stored in an XML file pointed to by the startup parameter ' StyleFile '. In the absence of a file name the files ' styles.xml ' is used. A typical style file includes colour and font information as below:

Code Sample 8-9 - A typical style file