Getting Started

You will need:

A Java compiler and virtual machine
ale.jar in your CLASSPATH. When you install ALE, it will create a subdirectory called ale. The ale.jar file will be in a subdirectory called jar under the main ale subdirectory.

Once you have ensured that ale.jar is in your CLASSPATH, you are ready to start using ALE to create your interfaces.

To use ALE:

Edit your Java application code to accommodate ALE.
Create your ALE application interface file.
If you want to embed the interface file in your Java code, run the make_array utility (located in the tools subdirectory under the main ale subdirectory) to create a String array that is equivalent to your external interface file and then import the generated String array declaration into your java code.
Compile your Java application.

What goes in your Java code

All of the components you want to use with ALE must be member variables in the object you'll pass to ALE's main method, brew.

The object you pass to brew must implement the interface "FieldToComponentMapper" (fully qualified name: jfd.ale.FieldToComponentMapper).

The interface contains one method with signature:


   public Component mapToComponent(Field f)
      throws Exception;

(Component is java.awt.Component, Field is java.lang.reflect.Field)

You should implement that interface exactly like this:


   public Component mapToComponent(Field f)
      throws Exception
   {
         return((Component)f.get(this));
   }

Make sure that all the components that make up your interface have been instantiated, and then add the method call to use ALE:


   ALE.brew(
      "SampleInterface.ale", "main", this, this
   );

We pass this twice because this is both:

An object that implements FieldToComponentMapper
The container into which all your components will be placed (we are assuming that your main class extends Frame in this example).
Note that if you embed the interface file in your java code, rather than passing the name of the file as brew's first argument you'd pass in the name of the String array containing the layout information.

Set an initial size for your container (e.g., setSize(640, 480)).

Call show()

Note: Do not attempt to define component layout in your application code! This defeats the purpose of ALE!

What goes in the ALE file

The only items that should appear in the ALE file are sections and the component, grid, or flow definitions they contain. This file is used only to define the sizes and locations of your components. The instantiation of your components and the handling of their events occurs in your Java code, not in the ALE file.

The creation and structure of the ALE file is included in this help.

It may be a good idea if the ALE file has the same root name as the class you have defined in your .java file (e.g., public class SampleFile... means your ALE file can be called SampleFile.ale), though ALE does not enforce this convention.

How to compile with ALE

You can either:

Compile normally, leaving the ALE file as a separate external file.

Compile the ALE file into your application.

Compiling normally

If you want to view changes to the interface without recompiling your application every time you make a change, or if you want to ship your ALE file as a separate file with your compiled application, simply compile your application as you normally would leaving the interface definition as a separate, external file.

If you have set up ALE according to the installation instructions, then compiling your code is simple:


   javac yourfile.java

so that a bytecode file is created. Then run it to view your interface:


   java yourfile

Note: Make sure the ale.jar is in your CLASSPATH.

Then make sure that the ALE interface file is delivered with your application.

Note: The external ALE file can be truly external, or delivered as part of a JAR file. When your application calls ALE.brew, the Java Virtual Machine will read your ALE interface file and automatically add, position, and size the components mentioned in the requested section of your ALE file to the container supplied in the call to ALE.brew.

Compiling the ALE file into your application

If you want to include the ALE file in your application bytecode file (presumably so inquisitive or mischievous users won't edit the interface), you can:

Run make_array, stored in the tools subdirectory, to generate an array containing the data in the ALE file:


   ..\tools\make_array your_file.ale (PC)


   ../tools/make_array your_file.ale (Unix)

The array is written to standard output, so be sure to capture the results to a file.

Import the array output into your Java code.

Compile your Java code as you normally would.

Be aware that using ALE in this manner requires that instead of passing a filename as the first parameter to ALE.brew you will pass the String array containing your embedded layout information in its place.