The JavaTM Tutorial
Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search
Feedback Form

Trail: Creating a GUI with JFC/Swing
Lesson: Using Swing Components

How to Use Tool Bars

A JToolBar(in the API reference documentation) is a container that groups several components -- usually buttons with icons -- into a row or column. Often, tool bars provide easy access to functionality that is also in menus. How to Use Actions describes how to provide the same functionality in menu items and tool bar buttons.

The following pictures show an application that contains a tool bar above a text area.

ToolBarDemo, with the tool bar in an initial north position

By default, the user can drag the tool bar to a different edge of its container or out into a window of its own. The next figure shows how the application looks after the user has dragged the tool bar to the right edge of its container.

ToolBarDemo, after the tool bar is dragged to the east

For the drag-out behavior to work correctly, the tool bar must be in a container that uses BorderLayout. The component that the tool bar affects is generally in the center of the container. The tool bar must be the only other component in the container; it must not be in the center.

The next figure shows how the application looks after the user has dragged the tool bar outside its window.

ToolBarDemo, after the tool bar is dragged out into its own window

The following code implements the tool bar. You can find the entire program in ToolBarDemo.java(in a .java source file). It relies on three images.


Note:  If any buttons in your tool bar duplicate functionality of other components, such as menu items, then you should probably create and add the tool-bar buttons as described in How to Use Actions.


PENDING: We need to change the text and examples to reflect the fact that, whenever practical, toolbars using the Java look and feel should use the images from the Java look and feel graphics respository(outside of the tutorial). Here is an example of doing so:
String imgLocation = "toolbarButtonGraphics/navigation/Back24.gif";
URL imageURL = getClass().getResource(imgLocation);

if (imageURL != null) {
    button = new JButton(new ImageIcon(imageURL));
}
You need to include the JLF graphics repository JAR file in the class path of the program. For example:
java -cp .;jars/jlfgr-1_0.jar ToolBarDemo [Microsoft Windows]
java -cp .:jars/jlfgr-1_0.jar ToolBarDemo [UNIX]

[PENDING: The following code needs to be reworked to use add(Container)/setAction.]
public ToolBarDemo() {
    ...
    JToolBar toolBar = new JToolBar();
    addButtons(toolBar);
    ...
    JPanel contentPane = new JPanel();
    contentPane.setLayout(new BorderLayout());
    ...
    contentPane.add(toolBar, BorderLayout.NORTH);
    contentPane.add(scrollPane, BorderLayout.CENTER);
    ...
}

protected void addButtons(JToolBar toolBar) {
    JButton button = null;

    //first button
    button = new JButton(new ImageIcon("images/left.gif"));
    ...
    toolBar.add(button);

    //second button
    button = new JButton(new ImageIcon("images/middle.gif"));
    ...
    toolBar.add(button);

    //third button
    button = new JButton(new ImageIcon("images/right.gif"));
    ...
    toolBar.add(button);
}

By adding a few lines of code to the preceding example, we can demonstrate some more tool bar features:

Here is a picture of the new UI,

ToolBarDemo2 shows a tool bar with a variety of components

You can find the entire program in ToolBarDemo2.java(in a .java source file). It relies on three images.

Because the tool bar can no longer be dragged, it no longer has bumps at its left edge. Here's the code that turns off dragging:

toolBar.setFloatable(false);
The biggest visible difference is that the tool bar contains two new components, which are preceded by a blank space -- a separator. Here is the code that adds the separator:
toolBar.addSeparator();
Here is the code that adds the new components:
//fourth button
button = new JButton("Another button");
...
toolBar.add(button);

//fifth component is NOT a button!
JTextField textField = new JTextField("A text field");
...
toolBar.add(textField);
You can easily make the components in a tool bar be aligned along their tops or bottoms, instead of centered, by invoking the setAlignmentY method. For example, to align the tops of all the components in a tool bar, invoke setAlignmentY(TOP_ALIGNMENT) on each component. Similarly, you can use the setAlignmentX method to specify the alignment of components when the tool bar is vertical. This flexibility of layout is possible because tool bars use BoxLayout to position their components. For more information, see How to Use BoxLayout(in the Creating a GUI with JFC/Swing trail).

The Tool Bar API

The following table lists the commonly used JToolBar(in the API reference documentation) constructors and methods. Other methods you might call are listed in the API tables in The JComponent Class.

Method or Constructor Purpose
JToolBar()
JToolBar(int)
JToolBar(String)
JToolBar(String, int)
Create a tool bar. The optional int parameter lets you specify the orientation; the default is HORIZONTAL. The optional String parameter, introduced in 1.3, allows you to specify the title displayed for the undocked tool bar's window.
Component add(Component) Add a component to the tool bar.

Version Note:  Before 1.3, the only way to associate an Action with a toolbar button was to use JToolBar's add(Action) method to create the button and add it to the tool bar. As of 1.3, that method is no longer recommended. You can instead associate a button with an Action using the setAction(Action) method.

void addSeparator() Add a separator to the end of the tool bar.
void setFloatable(boolean)
boolean isFloatable()
The floatable property is true by default, to indicate that the user can drag the tool bar out into a separate window. To turn off tool bar dragging, use toolbar.setFloatable(false).

Examples that Use Tool Bars

This table lists examples that use JToolBar and where those examples are described.

Example Where Described Notes
ToolBarDemo This page. A basic tool bar with icon-only buttons.
ToolBarDemo2 This page Demonstrates a non-floatable tool bar containing a separator and non-button components.
ActionDemo How to Use Actions Implements a tool bar using Action objects.


Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search
Feedback Form

Copyright 1995-2002 Sun Microsystems, Inc. All rights reserved.