Creating a Custom Layout Manager

Note: Before you start creating a custom layout manager, make sure that no existing one will work. Layout managers such as GridBagLayout , SpringLayout , and BoxLayout in particular, are flexible enough to work in many cases. You can also find layout managers from other sources, such as the Internet. Finally, you can simplify layout by grouping components into containers such as invisible panels.

To create a custom layout manager, you must create a class that implements the Layout-Manager interface. You can either implement it directly or implement its subinterface, LayoutManager2 . Every layout manager must implement at least the following five methods , which are required by the LayoutManager interface:

void addLayoutComponent(String, Component)

Called by the Container add methods. Layout managers that don't associate strings with their components generally do nothing in this method.

void removeLayoutComponent(Component)

Called by the Container remove and removeAll methods. Many layout managers do nothing in this method, relying instead on querying the container for its components via the Container method getComponents .

Dimension preferredLayoutSize(Container)

Called by the Container getPreferredSize method, which is itself called under a variety of circumstances. This method should calculate and return the ideal size of the container, assuming that the components it contains will be at or above their preferred sizes. This method must take into account the container's internal borders, which are returned by the getInsets method.

Dimension minimumLayoutSize(Container)

Called by the Container getMinimumSize method, which is itself called under a variety of circumstances. This method should calculate and return the minimum size of the container, assuming that the components it contains will be at or above their minimum sizes. It has to take into account the container's internal borders, which are returned by the getInsets method.

void layoutContainer(Container)

Called when the container is first displayed and each time its size changes. A layout manager's layoutContainer method doesn't actually draw components. It simply invokes each component's setSize , setLocation , and setBounds methods to set the component's size and position. This method must take into account the container's internal borders, which are returned by the getInsets method. If appropriate, it should also consider the container's orientation (returned by the getComponentOrientation method). You can't assume that the preferredLayoutSize or minimumLayoutSize method will be called before layoutContainer is called.

Besides the preceding five methods, layout managers generally implement at least one public constructor and the toString method.

If you want to support component constraints, maximum sizes, or alignment, your layout manager should implement the LayoutManager2 interface, which adds five methods to those required by LayoutManager :

• addLayoutComponent(Component, Object)

• getLayoutAlignmentX(Container)

• getLayoutAlignmentY(Container)

• invalidateLayout(Container)

• maximumLayoutSize(Container)

For more information about these methods, see the LayoutManager2 API documentation. ^[4]

^[4] LayoutManager2 API documentation: http://java.sun.com/j2se/1.4.2/docs/api/java/awt/LayoutManager2.html.

When implementing a layout manager, you might want to use SizeRequirements ^[5] objects to help you determine the size and position of components. For an example of using Size-Requirements , see the source code for BoxLayout.

^[5] SizeRequirements API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/SizeRequirements.html.

The example CustomLayoutDemo uses a custom layout manager called DiagonalLayout , which lays out components diagonally, from left to right, one per row (see Figure 9).

Figure 9. CustomLayoutDemo using DialogalLayout to lay out five buttons .

You can run CustomLayoutDemo using Java Web Start or compile and run the example yourself. ^[6]

^[6] To run CustomLayoutDemo using Java Web Start, click the CustomLayoutDemo link on the RunExamples/layout.html page on the CD. You can find the source files here: JavaTutorial/uiswing/layout/example-1dot4/index.html#CustomLayoutDemo .

Another example of a custom layout manager is GraphPaperLayout , which implements LayoutManager2 and lays out components in a grid (see Figure 10).

Figure 10. A rough demo called GraphPaperTest that uses GraphPaperLayout .

You can run GraphPaperTest using Java Web Start or compile and run the example yourself. ^[7]

^[7] To run GraphPaperTest using Java Web Start, click the GraphPaperTest link on the RunExamples/layout.html page on the CD. You can find the source files here: JavaTutorial/uiswing/layout/example-1dot4/index.html#GraphPaperTest .

When a container uses GraphPaperLayout , the size and location of its child components are specified (using grid units rather than absolute locations) as they're added to it. You can set the relative grid size, the horizontal space between components, and the vertical space between components when initializing the layout manager. You can also change component locations and the grid size dynamically.