How to Use Panels

The JPanel ^[103] class provides general-purpose containers for lightweight components . By default, panels don't paint anything except their background; however, you can easily add borders to them. Borders are covered in How to Use Borders (page 535) in Chapter 9.

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

In many look and feels (but not GTK+), panels are opaque by default. Opaque panels work well as content panes and can help painting efficiency, as described in Chapter 6. You can toggle a panel's transparency by invoking setOpaque . A transparent panel draws no background, so any components underneath show through.

An Example

Figure 38 shows a shaded version of the Converter application, which is discussed in more detail in Using Models (page 50).

Figure 38. A screenshot of the Converter applications with several of its JPanel s shaded.

Converter uses panels in several ways (as shown in Figure 39):

• One JPanel instance (shaded black) serves as a content pane for the application's frame. This content pane uses a top-to-bottom BoxLayout to lay out its contents, and an empty border to put 5 pixels of space around them. See Using Top-Level Containers (page 46) for information about content panes.

• Two instances of a custom JPanel subclass named ConversionPanel are used to both contain components and coordinate communication between components. The panels also have titled borders, which describe their contents and paint a line around them. Each panel uses a left-to-right BoxLayout object to lay out its contents.

• In each ConversionPanel , a JPanel instance is used to ensure that a combo box is at the right size and position. Each panel uses a top-to-bottom BoxLayout object (helped by an invisible space-filling component) to lay out the combo box.

• In each ConversionPanel , an instance of an unnamed JPanel subclass groups two components (a text field and a slider) and restricts their size. Each panel uses a top-to-bottom BoxLayout object to lay out its contents.

Figure 39. A screenshot of what Converter normally looks like (without shading).

As Converter demonstrates , panels are useful for grouping components, simplifying component layout, and putting borders around groups of components. The rest of this section gives hints on grouping and laying out components. For information about using borders, see How to Use Borders (page 535) in Chapter 9.

Setting the Layout Manager

Like other containers, a panel uses a layout manager to position and size its components. By default, a panel's layout manager is an instance of FlowLayout , which places the panel's contents in a row. You can easily make a panel use any other layout manager by invoking the setLayout method or specifying a layout manager when creating the panel. The latter approach is preferable for performance reasons, since it avoids the unnecessary creation of a FlowLayout object.

Here's an example of setting the layout manager when creating the panel:

 JPanel p = new JPanel(new BorderLayout()); //PREFERRED! 

This approach doesn't work with BoxLayout , since the BoxLayout constructor requires a pre-existing container. Here's an example that uses BoxLayout :

 JPanel p = new JPanel(); p.setLayout(new BoxLayout(p, BoxLayout.PAGE_AXIS)); 

Adding Components

When you add components to a panel, you use the add method. Exactly which arguments you specify to the add method depend on which layout manager the panel uses. When the layout manager is FlowLayout , BoxLayout , GridLayout , or SpringLayout , you'll typically use the one-argument add method, like this:

 aFlowPanel.add(aComponent); aFlowPanel.add(anotherComponent); 

When the layout manager is BorderLayout , you need to provide an argument specifying the added component's position within the panel. For example:

 aBorderPanel.add(aComponent, BorderLayout.CENTER); aBorderPanel.add(anotherComponent, BorderLayout.PAGE_END); 

With GridBagLayout you can use either add method, but you must somehow specify grid bag constraints for each component.

For information about using the standard layout managers, see Chapter 4, Laying Out Components within a Container (page 87).

The Panel API

The API in the JPanel class itself is minimal. The methods you are most likely to invoke on a JPanel object are those it inherits from its superclasses ” JComponent , Container , and Component . Tables 52 through 54 list the API you're most likely to use, with the exception of methods related to borders and layout hints.

For more information about the API all JComponent s can use, see The JComponent Class (page 53). Also refer to the JPanel API documentation at: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JPanel.html.

Table 52. Creating a JPanel

Constructor	Purpose
JPanel() JPanel(LayoutManager)	Create a panel. The LayoutManager parameter provides a layout manager for the new panel. By default, a panel uses a FlowLayout to lay out its components.

Table 53. Managing a Container's Components

Method	Purpose
void add(Component) void add(Component, int) void add(Component, Object) void add(Component, Object, int) void add(String, Component)	Add the specified component to the panel. When present, the int parameter is the index of the component within the container. By default, the first component added is at index 0, the second is at index 1, and so on. The Object parameter is layout manager dependent and typically provides information to the layout manager regarding positioning and other layout constraints for the added component. The String parameter is similar to the Object parameter.
int getComponentCount()	Get the number of components in this panel.
Component getComponent(int) Component getComponentAt(int, int) Component getComponentAt(Point) Component[] getComponents()	Get the specified component or components. You can get a component based on its index or x, y position.
void remove(Component) void remove(int) void removeAll()	Remove the specified component(s).

Table 54. Setting/Getting the Layout Manager

Method	Purpose
void setLayout(LayoutManager) LayoutManager getLayout()	Set or get the layout manager for this panel. The layout manager is responsible for positioning the panel's components within the panel's bounds according to some philosophy.

Examples That Use Panels

Many examples in this book use JPanel objects. The following table lists a few.

Example	Where Described	Notes
Converter	This section and An Example: Converter (page 51)	Uses five panels, four of which use BoxLayout and one of which uses GridLayout . The panels use borders and, as necessary, size and alignment hints to affect layout.
ListDemo	How to Use Lists (page 267)	Uses a panel, with its default FlowLayout manager, to center three components in a row.
ToolBarDemo	How to Use Tool Bars (page 427)	Uses a panel as a content pane. The panel contains three components, laid out by BorderLayout .
BorderDemo	How to Use Borders (page 535)	Contains many panels that have various kinds of borders. Several panels use BoxLayout .
BoxLayoutDemo	How to Use BoxLayout (page 462)	Illustrates the use of a panel with Swing's BoxLayout manager.