In this month's article I introduce TableLayout, a robust but easy-to-use LayoutManager for use in any Java Swing application. It's based very loosely on the HTML TABLE paradigm, where components are placed in table cells in row-major order. Vertical and horizontal alignment for the component in a cell can be specified, and a component (cell) may span rows and columns. I also present Forms-Panel, a JPanel sub-class that abstracts the underlying TableLayout.

This article assumes you have some familiarity with the design and use of LayoutManagers in Swing.

Background
I have been doing Java Swing applications for many years, and I've never been comfortable using a GUI designer tool, both for the verbose and often horrible Java code they produce and the lack of support for anything other than absolute positioning and sizing of components. I suspect that the quality of these tools has improved tremendously in recent years, but I'm stuck in my ways and have come to be fairly productive in laying out a user interface without the help of a visual design tool. (I have done some desktop application development in C# using Visual Studio .NET, which forces you to use the visual designer of this IDE. I was actually surprised at how productive I could be in this environment, and C# does not have the LayoutManager concept, so perhaps there is hope for me.)

I have found the LayoutManager concept in Swing to be truly inspired, but powerful and easy-to-use implementations a little wanting. My idea of a good LayoutManager is one that is fairly robust yet doesn't require a big learning curve to use or a lot of code to implement. I believe that the code used to lay out a user interface should be fairly self-documenting. In this regard, I have never been a fan of GridBagLayout and its necessary but evil companion, GridBagConstraints. I certainly recognize the power and capability of this LayoutManager, but I have found it difficult to learn and use, and even harder to maintain code that uses it.

I once led a team of UI developers in which I decreed (because I could) that the use of GridBagLayout would not pass code inspection. Fortunately, we had my TableLayout. I have used one form or another of it on several different projects over the years, and it has slowly evolved during this time as well. I would often maintain that any user interface could be done using a combination of BorderLayout and my TableLayout, given the willingness to subdivide the layout into separate and distinct grids (JPanels).

TableLayout Concepts
TableLayout uses a grid to lay out UI components, which is desirable, since good UI design involves the use of the grid concept. In contrast to Swing's GridLayout, TableLayout does not force every cell in the grid to be the same width and height. (I have never found GridLayout to be useful for much of anything other than a calendar or calculator application.) Rather it lets the preferred height of all the components in a row control the row height, and the preferred width of each component in a column control the width of the column. This by itself is not a new or original concept, but TableLayout brings some other things to the "table" as well. First, it supports the idea of extending the last row or column in the layout to the containing parent's boundaries. Second, it allows you to control the vertical and horizontal alignment of a component in a cell and to have cells span rows and columns if necessary. These are both optional behaviors, and TableLayout takes reasonable defaults so that it can be used in a very straightforward manner to easily lay out a sensible user interface.

CellConstraint
Cell alignment and row/column spanning are controlled using the CellConstraint object, which is only needed to specify something other than the default alignment or spanning. The CellConstraint class has several different constructors, but the easiest one to use is:

public CellContraint(String encoding);

In fact, TableLayout will accept a String as a constraint argument (the Container's add() method) and invoke this CellConstraint constructor for you (you'll see this in all example code). The encoding is a comma-separated list of name-value pairs that specify alignment and spanning, very similar to HTML TABLE attributes. Supported attributes are align, vAlign, rowSpan, and colSpan (case-insensitive). align is used for horizontal cell alignment and accepts case-insensitive values of left, center, right, or fill. vAlign is used to specify vertical alignment for a cell, with values of top, middle, bottom, or fill. The default value for align is fill, while the default value for vAlign is middle. rowSpan and colSpan each take a numeric argument indicating the number of rows or columns to span. As with the HTML table, a value of 0 for rowSpan or colSpan means to span to the end of the row or column. Table 1 summarizes the CellConstraint values.

You can specify these values directly in other CellConstraint constructors if desired. For example:

CellConstraint c = new CellConstraint
(2, 1, TagValue.LEFT, TagValue.MIDDLE);

is identical to:

CellConstraint c = new CellContraint("colspan=2, align=left");

Both create a CellContraint for spanning two columns, with a left horizontal alignment.

Using TableLayout
TableLayout has several constructors that are similar to the constructors for GridLayout and accomplish the same. As with GridLayout, you can specify either the number of rows or the number of columns to be zero, but not both. TableLayout has constructors that let you control whether or not the last column in the container is filled, or the last row in the container is filled. The default for the former is true, the latter, false. TableLayout provides getter and setter methods for these attributes as well as the horizontal and vertical spacing between table cells. How does application code that uses TableLayout compare to one that uses GridBagLayout? Consider Figure 1, an example of a simple login dialog box.

The dialog consists of three separate components:
the top "form" where the login parameters are entered, a horizontal line (normally the horizontal line separator would be accomplished with a custom border around one of the other two panels, but having a component rendering this more clearly demonstrates the capabilities of TableLayout; we'll see this FormSeparator component again later in this article), and a button panel with two buttons. The dialog uses a TableLayout consisting of one-column (and zero rows) to position these three components. The "form" panel uses a two-column (zero rows) TableLayout.

You can run the LoginDialog test application that comes with the code for this article to create Figure 1. Note that the "User id: " and "Password" labels are left-aligned. Actually, they just use the default horizontal alignment, which is fill. Some UI designers believe that labels in a form should be right-aligned. Invoke the LoginDialog test application with the commandline argument align=right, and you'll see the dialog in Figure 2, which has right-aligned labels.

Figure 3 shows the same dialog produced using a GridBagLayout for the login form panel, while Listing 1 shows the code snippet used to produce the two different versions.

From Listing 1, you can clearly see that with TableLayout, less code is involved, the code is self-documenting (components are laid out in row-major order), and the code is more maintainable. (Imagine having to insert an additional component in the login form of the dialog. With TableLayout, that is very straightforward; not so with GridBagLayout, as the additional layout code will likely affect the layout code for components below the new one.) Note the use of the static TableLayout getFillerComponent() method to create the empty cell below the "Password" label and force the JCheckBox into the next column.

The TableLayoutDemo class provided with this article's code further demonstrates the capabilities of this LayoutManager. Figure 4 shows the resulting window. A TableLayout is used to lay out this JFrame, and a sub-panel using a TableLayout contains the nine JButton components. This TableLayout is manipulated using the sliders and checkboxes, which dynamically modify the corresponding TableLayout properties.

Listing 2 shows the code used to lay out the nine buttons. Note the alignment values for four of the buttons, and the corresponding behavior as the TableLayout attributes are modified.

Figures 5-8 show the effects of dynamically changing the TableLayout properties given the alignment attributes in Listing 2 (see Figure 5...Figure 6...Figure 7...Figure 8).

To demonstrate row and column spanning, run the ComplexTableLayout class provided with this article's code. Figure 9 shows the resulting window, and Listing 3 shows the code used to produce this.

Note the order in which the components are added to the layout. This would be done very similarly for an HTML table.

How It Works
The code for TableLayout is straightforward enough. As components are added to the parent container using a CellConstraint (addLayoutComponent() method), TableLayout ensures that every cell is mapped to a row and column position. Components that span a row or column leave "reserved" cells around them. An inner class, CellData, is used to hold the component and the constraint for each cell.

The actual child component layout and preferred size calculation for the parent Container is done in the layoutContainer() method. First, all of the preferred sizes for each child component are obtained. Based on this information, TableLayout is able to calculate the maximum height for each row and the maximum width for each column, i.e., the bounds for each cell. Given the cell bounds, each cell component is assigned its location and size, adjusting for any alignment and spanning. The size of each component in a last row or column is also adjusted if the layout is filling the last row or column. Finally, the preferred size of the parent Container is calculated given the cell boundaries and the spacing between each row and column.