Previous | Next | Trail Map | Creating a User Interface | Using the JFC/Swing Packages

How to Use Panels

JPanel(in the API reference documentation) is a general-purpose container for lightweight components. Like all other containers, it uses a layout manager(in the Creating a User Interface trail) to position and size its components. Like all Swing components, a JPanel allows you to add borders to itself and to determine whether it uses double buffering to enhance painting performance.

The application pictured here uses a panel and its default layout manager, FlowLayout(in the API reference documentation), to display three buttons:

The main class for this application is ButtonDemo, which is a subclass of JPanel. Here's the code from ButtonDemo's constructor that adds the three buttons to the panel:
public ButtonDemo() {
    super();
    ...
    create the three buttons
    ...
    //Add Components to this container, using the default FlowLayout.
    add(b1);
    add(b2);
    add(b3);
}
This code does not explicitly set the layout manager for the panel, so it uses the default layout manager. This layout manager, FlowLayout, places components in a row at their preferred sizes. If you want to use a different layout manager, you can either specify a layout manager when you create the JPanel object or use the setLayout method later. The AWT provides a collection of useful layout managers, and Swing adds another general-purpose layout manager, BoxLayout. For general information about layout and about the AWT layout managers, in particular, see Laying Out Components within a Container(in the Creating a User Interface trail). For a list of JPanel examples that use a variety of layout managers, see Examples that Use JPanels.

The preceding code snippet uses an add method inherited from java.awt.Container(in the API reference documentation) that requires a single argument: the component to be added. Like other Container subclasses, JPanel inherits other add methods that allow you to specify constraints and positioning information when adding the component. Choose the appropriate add method for the layout manager you're using.

Other Containers

JPanel is just one of several container-providing classes that you might use. Here are some special-purpose containers you might consider using in place of a JPanel:

Box Automatically uses a BoxLayout to lay out its components. The advantage of Box is that it's super lightweight, since it extends the Container class directly. The disadvantage of Box is that it isn't a true Swing component -- it doesn't inherit the API that supports features such as borders on the box and easy setting of the box's minimum, preferred, and maximum sizes. For this reason, our examples often use JPanel with BoxLayout, instead of using Box.
JLayeredPane Provides a third dimension, depth, for positioning components. Layered panes do not have layout managers but can be used to layer components laid out in JPanels. One type of layered pane, JDesktopPane, is designed primarily to contain and manage internal frames.
JScrollPane Provides a scrollable view of a large or growable component.
JSplitPane Displays two components whose relative size can be manipulated by the user.
JTabbedPane Allows multiple components, usually JPanel objects, to share the same space.

Another container you might use is the default content pane of an applet, frame, internal frame, or dialog. The content pane is a Container that, as a rule, holds all of a window's non-menu components. You find the content pane using a method called getContentPane. Similarly, you can set the content pane -- perhaps to be a JPanel that you created -- using setContentPane. See How to Make Frames for more information about content panes.

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(in the API reference documentation), Container(in the API reference documentation), and Component(in the API reference documentation). The following tables list the API you're most likely to use. [Link to JComponent, Container, and Component discussions.]

Creating a JPanel
Method Purpose
JPanel()
JPanel(boolean)
JPanel(LayoutManager)
JPanel(LayoutManager, boolean)
Create a panel. When present, the boolean parameter determines the panel's buffering strategy. A value of true indicates double buffered. The LayoutManager parameter provides a layout manager for the new panel. If left unspecified a panel uses FlowLayout to layout its components.

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 position or index of the component within the container. 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 provides a name for the component.
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).

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 contained in this lesson use JPanel objects. The following table lists a few:

Example Where Described Notes
ButtonDemo.java How to Use Buttons A subclass of JPanel. Uses FlowLayout, the default layout manager of a panel.
ToolBarDemo.java How to Use Toolbar Shows a panel with three components laid out by BorderLayout.
BorderDemo.java How to Use Borders Contains several panels that use BoxLayout. Contains many more panels that have various kinds of borders.
BoxLayoutDemo.java How to Use BoxLayout Illustrates the use of a panel with Swing's BoxLayout manager.
LabelDemo.java How to Use Labels Uses a panel whose three components are laid out in a grid by GridLayout.
TabbedPaneDemo.java How to Use Tabbed Panes A subclass of JPanel that creates its GUI in its constructor and uses a GridLayout.


Previous | Next | Trail Map | Creating a User Interface | Using the JFC/Swing Packages