A Real World ALE File

Our example interface file lays out the interface used by the popular image manipulation tool for UNIX, xv. The entire ALE file is available undisturbed in the The xv ALE file, but is sectioned off here for the purpose of introducing you to the file structure. This help page does not detail all of the file, but covers most of the topics that you'll encounter in your interface creation.

The xv ALE file is laid out logically, from top to bottom, and from left to right. There is only one section in this file, as all the components are to be placed within the same container.

As you read through this example, keep in mind that several types of definitions are being used:

a section definition
component definitions
a flow definition

Each one is slightly different, so try to be aware of the differences as we run through this example.



   // xv interface emulation; xv is copyrighted by John Bradley.
   // All rights reserved.
   // No copyright infringement is intended.
   // The creators of ALE and its documentation
   // have only the highest regard for xv.

   // Top section components consisting of logo and
   // two rows of buttons equal to the height of the logo

   section main
   {

      logo(p, p, 5, 5, LT)

The first entry, section main, defines the entire dialog. The section will have an ending }, as you would expect.

First, let's look at the logo placement and attributes:

logo is the name of the component that contains the logo. This is the name that you have defined, or will define, in your .java file (e.g., logo = new JButton(new ImageIcon("gifs\xv\unregistered.gif"));)
The first p is the width of the component. In this case, the component's width is defined to be its own "preferred" width (i.e., logo will be a JButton containing an image, the preferred width will be the width of the GIF). Using p for the component's width effectively means "I don't want to explicitly choose a size, just use the size that the component would normally be".
The second p is the height of the component. Again, the component's height is defined to be its own "preferred" height (i.e., the actual height of the GIF used to create the logo button).
The first 5 is a point in X, measured in pixels, where the component should be positioned (from the left side of the dialog).
The second 5 is a point in Y, measured in pixels, where the component should be positioned (from the top of the dialog).
LT is the alignment (Left Top) the component should have relative to the X, Y point (i.e., 5, 5) just defined.

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 5 pixels from the dialog's left side and 5 pixels from its top. The alignment attribute (here defined as LT, or Left Top) determines where the component will lie relative to the X,Y point. The first letter specifies the alignment in X and the second letter specifies the alignment in Y.

Now let's have a look at the two rows of buttons that are defined to the right of the logo. These buttons could be defined as either two rows, or as three columns, but in our example we use two rows.



      flow(HORIZONTAL, logo.r + 5, w - 5, 5)
      {
         display    ((w - logo.r - 10) / 3 - 1, logo.h / 2 - 1, 0, 0, CT)
         bitControl (display.w, display.h,                      0, 0, CT)
         algorithms (display.w, display.h,                      0, 0, CT)
      }

      root      (display.w, display.h, display.l,    display.b + 1, LT)
      windows   (display.w, display.h, bitControl.l, display.b + 1, LT)
      imageSize (display.w, display.h, algorithms.l, display.b + 1, LT)

The flow function is used to place several components one after the other in either a horizontal row or a vertical column. Flow has the following attributes: a direction (horizontal or vertical), a start point, an end point, and an opposing direction centerline.

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 logo's right side. Here, logo.r + 5 means "start at the logo's right side and add 5 pixels".
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).

Note: The w variable always represents the dialog's full width. For example, if the dialog is 400 pixels wide, w = 400. So if you wanted a button to be one-fourth the size of the dialog, you could specify its width to be w/4. In the same way, our end point in this example is defined as w - 5, meaning that the end point should be at least 5 pixels to the left of the dialog's right side.
So why do the examples always use these relative values rather than absolute values? Simply because we assume that a user might resize the window in some way. If the components are absolutely defined and the window can be resized, some components might not fit within a window that's made smaller, or if the user drags the window larger, the components will all congregate up in the top left corner, leaving a large empty area to the bottom and the right.
You can certainly use absolute values if you wish, especially if you plan to prevent the user from resizing the dialog.
The opposing direction centerline, also referred to as c, 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.

The buttons within this particular flow are fairly complicated. The buttons are, to reiterate:


         display    ((w - logo.r - 10) / 3 - 1, logo.h / 2 - 1, 0, 0, CT)
         bitControl (display.w, display.h,                      0, 0, CT)
         algorithms (display.w, display.h,                      0, 0, CT)

The components defined within a flow function have width, height, X, Y, and alignment attributes, just as the logo object had. The breakdown looks like this:

display is the component name that you have defined, or will define, in your .java file (e.g., display = new JButton("Display");)
(w - logo.r - 10) / 3 - 1 defines the width of this button. As you can see, a fairly complex formula has been used to calculate the width of the display button.
Let's take it step-by-step:
```
     (w - logo.r - 10) / 3 - 1
```
We know that the w variable is the value of the entire width of the dialog. We also know that the button should fit, in the X direction, within the space left over by the logo. We'd like to have some extra spacing, too, to make the button look nice. So (w - logo.r - 10) says, "Take the width of the entire dialog, subtract the amount of space used before the right side of the logo is reached, and subtract 10 more pixels from that." So if the dialog were 400 pixels, and the position of the right side of the logo were at 100 pixels, then (w - logo.r - 10) would be (400 - 100 - 10), or 290 pixels.
But we aren't done yet because we're defining the width of one button in a row of three buttons, so we have to leave room for the other two buttons. What we have right now is the definition of the width we want to use for all three buttons. So we'll take that definition and divide by 3 (for the total of 3 buttons). Using our example, each button would now be 130 pixels wide. But we've also specified that an additional pixel should be subtracted from that total, so each button would finally be 129 pixels wide.
logo.h / 2 - 1 is the defined height of the component.
```
     logo.h / 2 - 1
```
This definition is somewhat simpler: Take the complete height of the logo (logo.h) and divide it by 2. Remember, we're going to have two rows of buttons, and we want the buttons to be all the same height. Then we subtract an additional pixel.

Note: You may be wondering what all this "additional pixel" business is about. The additional pixel is used for aesthetic purposes, to nudge components away from each other, making for a more elegant look. In order to use the additional pixel(s) in a way that allows the buttons to line up properly with the logo, we have to subtract one pixel from their size definitions so we can add it back in as a positioning element later.
The first 0 is the X point where the component should be placed. Since this button occurs within a flow, and since the flow handles component placement, you can set this value to 0. If you set a value for the X point, it will be ignored.
The second 0 is the Y point where the component should be placed. Since this button occurs within a flow, and since the flow handles component placement, you can set this value to 0. If you set a value for the Y point, it will be ignored.
CT defines the alignment around the X,Y point. CT, or Center Top, seems a reasonable alignment, ensuring that the button will be positioned at the Center Top of its assigned place in the flow.

Note: As you can see, the buttons regulated by the flow will align themselves to fill up the space between the flow's start and end points, from left to right, no matter what size the dialog ultimately is.

The other two buttons follow display's lead, having the same attributes.

That's the flow, but what about the second row of buttons?

The second row of buttons is defined in this manner:


      root      (display.w, display.h, display.l,    display.b + 1, LT)
      windows   (display.w, display.h, bitControl.l, display.b + 1, LT)
      imageSize (display.w, display.h, algorithms.l, display.b + 1, LT)

Why aren't these buttons defined within a flow? They could be, but they don't have to be. Instead, they can simply refer to the positioning of the buttons within the previous flow.

Let's look at the root button, but skip to the important parts.

display.w is the width of the button. Because the display button has already been defined, root can simply use its width.
display.h is the height of the button. Because the display button has already been defined, root can simply use its height.
display.l is the button's position in X. The left side of the display button will serve as root's X point.
display.b + 1 is the button's position in Y. In this case, root should be positioned exactly one pixel beneath the bottom of the display button. (Here's where that additional pixel comes in handy.)
LT is the alignment Left Top.

Note: The alignment here is around the X,Y point that was defined relative to the row of buttons in the flow. Because the X,Y point is relative to the top left corner of those buttons, the alignment must reflect this to work correctly.
For example, if we had defined the X,Y point to be relative to the bottom right corner of the flow buttons (i.e., root (display.w, display.h, display.r, display.t - 1, BR)), then our alignment would be to BR, Bottom Right.

If you're feeling comfortable with ALE file structure, go ahead and experiment with an interface of your own. You can either copy the original examples and edit them, or start fresh with a new file.

If you feel you need a little more work on the structure, keep reading.

Now we'll tackle xv's Message Area listbox and the column of buttons that appear to its right.



   //Message Area on the left and a column of buttons to its right
   //Buttons are distributed evenly to the height of the Message Area

   messageArea (.8 * w, .55 * h, 5, logo.b + 5, LT)

   flow(VERTICAL, messageArea.t, messageArea.b, w - 5)
   {
       next    (w - (messageArea.r + 10), messageArea.h / 7, 0, 0, RC)
       prev    (next.w, next.h,                              0, 0, RC)
       load    (next.w, next.h,                              0, 0, RC)
       save    (next.w, next.h,                              0, 0, RC)
       print   (next.w, next.h,                              0, 0, RC)
       delete  (next.w, next.h,                              0, 0, RC)
       files   (next.w, next.h,                              0, 0, RC)
   }

Let's look at the Message Area:

messageArea is the name of the component. This is the name that you have defined, or will define, in your .java file (e.g., messageArea = new JScrollPane(new JTextArea());)
.8 * w is the width of the component. In this case, the component is defined to be 80% of the width of the overall dialog in which it appears. w represents the width of the dialog box.
.55 * h is the height of the component. In this case, the component is defined to be 55% of the height of the overall dialog in which it appears. h represents the height of the dialog box.
5 is a point in X, measured in pixels, where the component should be positioned (from the left side of the dialog).
logo.b + 5 is a point in Y, measured in pixels, where the component should be positioned (5 pixels from the bottom of the logo).
LT is the alignment (Left Top) the component should have relative to the X, Y point (i.e., 5, 5) just defined.

Now let's look at the flow section.


   flow(VERTICAL, messageArea.t, messageArea.b, w - 5)

Here, the flow is a vertical flow that starts at the message area's top and ends at the message area's bottom. It is also defined to have a centerline that is 5 pixels to the left of the dialog's right side.

Note: Remember here that the opposed direction centerline determines the center of the flow in the opposite direction of its natural flow. So the centerline w - 5 tells ALE where the flow should be positioned horizontally.

And the buttons within the flow?


       next    (w - (messageArea.r + 10), messageArea.h / 7, 0, 0, RC)
       prev    (next.w, next.h,                              0, 0, RC)

The button next has a width that is defined relative to both the messageArea component and the dialog box: add 10 pixels to the right edge of the messageArea component, and then subtract that value from the width of the dialog box. This causes the button to take up the remaining width of the dialog box, but with 10 pixels of surrounding space left over. [The flow definition, if you remember, includes a centerline that is 5 pixels shy of the dialog box right side, so the flow definition and the button definition combined cause the button to fall in the center of the leftover space.

The next button's height is defined as one-seventh of the messageArea's height. Because seven buttons are defined within this flow, this is a shortcut way of ensuring this button will be proportional to the messageArea, and you can guess that the other buttons will be defined to be exactly the same height.

Because the flow handles the positioning of the buttons, their X and Y values are left at 0. Any alignment setting is still honored.

Once the next button is defined, the following buttons, because they are meant to be the same size as next, are all defined to have the same width and height as next.

If you're still stumped by all of this, try looking through Interface Layout for more details on putting components where you want them. You might also try compiling one of the examples, then editing a copy of the ALE file to see what happens when you resize and reposition components.