How to Use BorderLayout

As Figure 1 shows, a BorderLayout ^[1] has five areas. These areas are specified by the BorderLayout constants PAGE_START , PAGE_END , LINE_START , LINE_END , and CENTER .

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

Figure 1. BorderLayoutDemo , an application that uses BorderLayout .

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

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

Version Note

Before v1.4, the preferred names for the various areas were different, ranging from points of the compass (for example, BorderLayout.NORTH for the top area) to wordier versions of the constants we use in our examples. The constants used in our examples are preferred because they're standard and enable programs to adjust to languages that have different orientations.

If you enlarge a container that uses BorderLayout , the center area gets as much of the available space as possible. The other areas expand only as much as necessary to fill all available space. Often a container uses only one or two of the areas of the BorderLayout ”say just the center or the center and the bottom.

The following code adds components to a frame's content pane. Because content panes use BorderLayout by default, the code doesn't need to set the layout manager.

  ...//Container pane = aFrame.getContentPane()...  JButton button = new JButton("Button 1 (PAGE_START)"); pane.add(button, BorderLayout.PAGE_START); //Make the center component big, since that's the //typical usage of BorderLayout. button = new JButton("Button 2 (CENTER)"); button.setPreferredSize(new Dimension(200, 100)); pane.add(button, BorderLayout.CENTER); button = new JButton("Button 3 (LINE_START)"); pane.add(button, BorderLayout.LINE_START); button = new JButton("Long-Named Button 4 (PAGE_END)"); pane.add(button, BorderLayout.PAGE_END); button = new JButton("5 (LINE_END)"); pane.add(button, BorderLayout.LINE_END); 

We strongly recommend that you specify the component's location (for example, BorderLayout.LINE_END ) as one of the arguments to the add method. If you leave it out, the component will be added to the center but your code will be much less clear. If you find that a component is missing from a container controlled by BorderLayout , make sure that you have specified the component's location and that you didn't put another component in the same location.

All of our examples that use BorderLayout specify the component as the first argument to the add method. For example:

 add(component, BorderLayout.CENTER)  //preferred 

However, you might see code in other programs that specifies the component second. Here are two alternate ways of writing the preceding code:

 add(BorderLayout.CENTER, component)  //valid but old-fashioned add("Center", component)             //valid but error prone 

The BorderLayout API

Table 1 describes a couple of BorderLayout constructors and some methods for adding space between components. You can find the BorderLayout API documentation online at: http://java.sun.com/j2se/1.4.2/docs/api/java/awt/BorderLayout.html.

Table 1. Adding Space around Components

Constructor or Method	Purpose
BorderLayout(int horizontalGap, int verticalGap)	Specify gaps (in pixels). By default, BorderLayout puts no extra space around the components it manages .
void setHgap(int) void setVgap(int)	Set the horizontal and vertical gaps.

Examples That Use BorderLayout

The following table shows a few of the many examples that use BorderLayout .

Example	Where Described	Notes
BorderLayoutDemo	This section	Puts a component in each of the five possible locations.
TabbedPaneDemo	How to Use Tabbed Panes (page 382)	Puts a single component in the center of a content pane so that it is as large as possible.
CheckBoxDemo	How to Use Check Boxes (page 163)	Creates a JPanel that uses BorderLayout . Puts components in the left (actually, LINE_START ) and center locations.