Basic ALE File Structure

The ALE file is a simple input file that defines the location and size of each component within a container (dialog). It does not instantiate any components, nor does it address component event handling.

An ALE file is an ASCII text file that is interpreted when your application is run. If you want to compile your ALE file into your application, an additional compilation step will be needed, but you don't have to do anything special to the original ALE file.

An ALE file can define multiple dialogs. Each section of an ALE file defines a single container, and you can have multiple sections.

An ALE file should have two basic elements:

at least one section assignment
at least one component assignment

Let's have a look at an ALE file, simple.ale, that defines a dialog with a single button.


section main
{
   button1(p, p, w / 2, h / 2, CC)
}

Note: Remember, the ALE file contains nothing other than the size and positioning of the components. The components are actually defined and instantiated in your Java code.

The section groups the components defined within it. Any components defined between the opening and closing braces are included in the section.

The component breaks down like this:


     name(width, height, X point, Y point, alignment)

where:

name is the name of the component as defined in your Java code.
In our example, the name is button1.
width is the width of the component. This can be defined in absolute pixels or using an expression.
In our example, the width is p, the preferred width of the component. p in the example is a placeholder meaning "use the preferred size".
height is the height of the component. This can be defined in absolute pixels or using an expression.
In our example, the height is p, the preferred height of the component.
X point is a point in X, measured in pixels or set with an expression, where the component should be positioned (from the left side of the dialog).
In our example, the X point is w / 2, meaning half the width of the dialog. The variable w refers to the dialog's entire width.
Y point is a point in Y, measured in pixels or set with an expression, where the component should be positioned (from the top of the dialog).
In our example, the Y point is y / 2, meaning half the height of the dialog. The variable y refers to the dialog's entire height.
alignment is how the component should be placed relative to the X,Y point just defined. The first letter is the alignment in X (Left, Right, Center) and the second letter is the alignment in Y (Top, Bottom, Center).
In our example, the alignment is CC (Center Center).

Note: Java defines the X,Y origin (0,0) to be the top left corner of the dialog box.
Also, it's important to note here that the point defined by X,Y is a point around which the component will be aligned. In this example, the point is at exactly half the width and half the height of the dialog -- the exact center. The alignment attribute (here defined as CC, or Center Center) determines where the component will lie relative to the X,Y point.

This file generates this dialog:

This is simplest dialog you can create.

ALE provides two methods you can use to position components quickly and easily:

grid -- generates a table of components
flow -- places a series of components one after the other in a row or column

An ALE file, GridAWT.ale, that contains a grid looks similar to:


section main
{
   // 3 x 3 grid, xMin/yMin is (0, 0) xMax/yMax is (w, h)
   // it will cover the entire parent container

   grid(3, 3, 0, 0, w, h)
   {
      // Note that the purpose of "grid" is to determine
      // x and y locations for the components.
      // For this reason we put "0, 0" in for
      // the location fields for each of the components.

      button1(p, p, 0, 0, CC)
      button2(p, p, 0, 0, CC)
      button3(p, p, 0, 0, CC)
      button4(p, p, 0, 0, CC)
      button5(p, p, 0, 0, CC)
      button6(p, p, 0, 0, CC)
      button7(p, p, 0, 0, CC)
      button8(p, p, 0, 0, CC)
      button9(p, p, 0, 0, CC)
   }
}

The grid syntax is:


   grid(rows, columns, xmin, ymin, xmax, ymax)

So our grid breakdown is:

grid specifies that this is the grid method.
3 is the number of rows the grid should have.
3 is the number of columns the grid should have.
0 is the point in X where the grid should start being drawn.
0 is the point in Y where the grid should start being drawn.
w is the point in X where the grid should stop being drawn.
In our example, w is the greatest point in X, or the width of the dialog where this grid will be drawn.
h is the point in Y where the grid should stop being drawn.
In our example, w is the greatest point in Y, or the height of the dialog where this grid will be drawn.

Note: You can think of the xmin,ymin point as the upper left corner of the grid, and the xmax,ymax point as the lower right corner of the grid.

The component syntax is the same as the previous component syntax, except that the X,Y point, used for positioning the component at a particular point, is ignored. The alignment attribute is still used.

This ALE file generates this dialog:

An ALE file that contains a flow looks similar to:


   flow(HORIZONTAL, 5, w - 5, 5)
   {
      button1 ((w - 10) / 3, h / 2,     0, 0, CT)
      button2 (button1.w,    button1.h, 0, 0, CT)
      button3 (button1.w,    button1.h, 0, 0, CT)
   }

The flow syntax is:


   flow(direction, start point, end point, opposing direction centerline)

So our flow breakdown is:

The direction may be either HORIZONTAL or VERTICAL. In this case, the flow is horizontal.
The start point is the point where the flow should begin. This can be defined as relative to another component or to the dialog itself. In our example, the start point is defined as 5 pixels to the right of the dialog's left side.
The end point is the point where the flow should stop. This can be defined as relative to another component or to the dialog itself. The end point is defined here as 5 pixels shy of the dialog's entire width (w).
The opposing direction centerline is the line used to center the objects in the opposite direction of their flow. In our example, the flow is horizontal, so we need to define where the flow lies vertically. We have set the vertical setting to 5, so that the centerline of the horizontal flow is 5 pixels from the dialog box's top.

This file generates this dialog: