javax.swing

Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms. For a programmer's guide to using these components, see Creating a GUI with JFC/Swing, a trail in The Java Tutorial. For other resources, see Related Documentation.

Swing's Threading Policy

Typical Swing applications do processing in response to an event generated from a user gesture. For example, clicking on a {@code JButton} notifies all {@code ActionListeners} added to the {@code JButton}. As all events generated from a user gesture are dispatched on the event dispatching thread, most developers are not impacted by the restriction.

Where the impact lies, however, is in constructing and showing a Swing application. Calls to an application's {@code main} method, or methods in {@code Applet}, are not invoked on the event dispatching thread. As such, care must be taken to transfer control to the event dispatching thread when constructing and showing an application or applet. The preferred way to transfer control and begin working with Swing is to use {@code invokeLater}. The {@code invokeLater} method schedules a {@code Runnable} to be processed on the event dispatching thread. The following two examples work equally well for transferring control and starting up a Swing application:

public class MyApp implements Runnable {
    public void run() {
        // Invoked on the event dispatching thread.
        // Construct and show GUI.
    }

    public static void main(String[] args) {
        SwingUtilities.invokeLater(new MyApp(args));
    }
}

public class MyApp {
    MyApp(String[] args) {
        // Invoked on the event dispatching thread. Do any initialization
        // here.
    }

    public void show() {
        // Show the UI.
    }

    public static void main(final String[] args) {
        // Schedule a job for the event-dispatching thread:
        // creating and showing this application's GUI.
        SwingUtilities.invokeLater(new Runnable() {
            public void run() {
                new MyApp(args).show();
            }
        });
    }
}

As all events are delivered on the event dispatching thread, care must be taken in event processing. In particular, a long running task, such as network io or computational intensive processing, executed on the event dispatching thread blocks the event dispatching thread from dispatching any other events. While the event dispatching thread is blocked the application is completely unresponsive to user input. Refer to {@link SwingWorker} for the preferred way to do such processing when working with Swing.

More information on this topic can be found in the Swing tutorial, in particular the section on How to Use Threads.

Related Documentation

For overviews, tutorials, examples, guides, and other documentation, please see:

• The Swing Connection
• The Java Tutorial
• Online Training at the Java Developer Connection^SM
• Java Foundation Classes (JFC) home page

Buttons can be configured, and to some degree controlled, by Actions.

Warning: Serialized objects of this class will not be compatible with future Swing releases.

In addition to the actionPerformed method defined by the ActionListener interface, this interface allows the application to define, in a single place:

• One or more text strings that describe the function.

The Box class can create several kinds of invisible components that affect layout: glue, struts, and rigid areas. If all the components your Box contains have a fixed size, you might want to use a glue component (returned by createGlue) to control the components' positions. If you need a fixed amount of space between two components, try using a strut (createHorizontalStrut or createVerticalStrut). If you need an invisible component that always takes up the same amount of space, get it by invoking createRigidArea.

If you are implementing a BoxLayout you can find further information and examples in How to Use BoxLayout, a section in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases.

This model is used for regular buttons, as well as check boxes and radio buttons, which are special kinds of buttons.

This enum holds only a small subset of the keys currently used within Swing, but we may move more of them here in the future.

Adding an item to, and using, this class instead of String for client properties protects against conflicts with developer-set client properties.

Warning: Serialized objects of this class will not be compatible with future Swing releases.

Warning: Serialized objects of this class will not be compatible with future Swing releases.

Warning: Serialized objects of this class will not be compatible with future Swing releases.

Implementation Note: This class overrides invalidate, validate, revalidate, repaint, isOpaque, and firePropertyChange solely to improve performance. If not overridden, these frequently called methods would execute code paths that are unnecessary for the default list cell renderer. If you write your own renderer, take care to weigh the benefits and drawbacks of overriding these methods.

Warning: Serialized objects of this class will not be compatible with future Swing releases.

Warning: Serialized objects of this class will not be compatible with future Swing releases.

The JApplet class is slightly incompatible with java.applet.Applet.

Buttons can be configured, and to some degree controlled, by Actions.

This class provides three levels of API:

1. A static convenience method which shows a modal color-chooser dialog and returns the color selected by the user.
2. A static convenience method for creating a color-chooser dialog where ActionListeners can be specified to be invoked when the user presses one of the dialog buttons.
3. The ability to create instances of JColorChooser panes directly (within any container).

The JComponent class provides:

• The base class for both standard and custom components that use the Swing architecture.
• A "pluggable look and feel" (L&F) that can be specified by the programmer or (optionally) selected by the user at runtime. The look and feel for each component is provided by a UI delegate -- an object that descends from javax.swing.plaf.ComponentUI . See How to Set the Look and Feel in The Java Tutorial for more information.
• Comprehensive keystroke handling. See the document Keyboard Bindings in Swing, an article in The Swing Connection, for more information.
• Support for tool tips -- short descriptions that pop up when the cursor lingers over a component. See How to Use Tool Tips in The Java Tutorial for more information.
• Support for accessibility. JComponent contains all of the methods in the Accessible interface, but it doesn't actually implement the interface.

This component uses implementations of the EditorKit to accomplish its behavior.

The following code pops up a file chooser for the user's home directory that sees only .jpg and .gif images:

 JFileChooser chooser = new JFileChooser();
 FileNameExtensionFilter filter = new FileNameExtensionFilter(
 "JPG & GIF Images", "jpg", "gif");
 chooser.setFileFilter(filter);
 int returnVal = chooser.showOpenDialog(parent);
 if(returnVal == JFileChooser.APPROVE_OPTION) {
 System.out.println("You chose to open this file: " +
 chooser.getSelectedFile().getName());
 }
 

Warning: Swing is not thread safe.

The JFrame class is slightly incompatible with Frame. Like all other JFC/Swing top-level containers, a JFrame contains a JRootPane as its only child. The content pane provided by the root pane should, as a rule, contain all the non-menu components displayed by the JFrame. This is different from the AWT Frame case.

Generally, you add JInternalFrames to a JDesktopPane.

A JLabel object can display either text, an image, or both. You can specify where in the label's display area the label's contents are aligned by setting the vertical and horizontal alignment. By default, labels are vertically centered in their display area. Text-only labels are leading edge aligned, by default; image-only labels are horizontally centered, by default.

You can also specify the position of the text relative to the image. By default, text is on the trailing edge of the image, with the text and image vertically aligned.

A label's leading and trailing edge are determined from the value of its java.awt.ComponentOrientation property.

For convenience, JLayeredPane divides the depth-range into several different layers.

While the JOptionPane class may appear complex because of the large number of methods, almost all uses of this class are one-line calls to one of the static showXxxDialog methods shown below:

Method Name	Description
showConfirmDialog	Asks a confirming question, like yes/no/cancel.
showInputDialog	Prompt for some input.
showMessageDialog	Tell the user about something that has happened.
showOptionDialog	The Grand Unification of the above three.

All dialogs are modal.

Warning: Swing is not thread safe.

The following image shows the relationships between the classes that use root panes.

For more information and examples see How to Use Menus, a section in The Java Tutorial.

Warning: Swing is not thread safe.

The slider can show both major tick marks, and minor tick marks between the major ones.

Tabs/components are added to a TabbedPane object by using the addTab and insertTab methods. A tab is represented by an index corresponding to the position it was added in, where the first tab has an index equal to 0 and the last tab has an index equal to the tab count minus 1.

The TabbedPane uses a SingleSelectionModel to represent the set of tab indices and the currently selected index.

The JTable has many facilities that make it possible to customize its rendering and editing but provides defaults for these features so that simple tables can be set up easily.

With most look and feels, the user can drag out a tool bar into a separate window (unless the floatable property is set to false). For drag-out to work correctly, it is recommended that you add JToolBar instances to one of the four "sides" of a container whose layout manager is a BorderLayout, and do not add children to any of the other four "sides".

Warning: Swing is not thread safe.

A specific node in a tree can be identified either by a TreePath (an object that encapsulates a node and all of its ancestors), or by its display row, where each row in the display area displays one node. An expanded node is a non-leaf node (as identified by TreeModel.isLeaf(node) returning false) that will displays its children when all its ancestors are expanded. A collapsed node is one which hides them.

As of 1.6 RepaintManager handles repaint requests for Swing's top level components (JApplet, JWindow, JFrame and JDialog).

tiled

The components are placed end-to-end, starting either at coordinate 0 (the leftmost or topmost position) or at the coordinate representing the end of the allocated span (the rightmost or bottommost position).

aligned

The components are aligned as specified by each component's X or Y alignment value.

Each SizeRequirements object contains information about either the width (and X alignment) or height (and Y alignment) of a single component or a group of components:

minimum

The smallest reasonable width/height of the component or component group, in pixels.

preferred

The natural width/height of the component or component group, in pixels.

maximum

The largest reasonable width/height of the component or component group, in pixels.

alignment

The X/Y alignment of the component or component group.

Warning: Serialized objects of this class will not be compatible with future Swing releases.

 String[] days = new DateFormatSymbols().getWeekdays();
 SpinnerModel model = new SpinnerListModel(Arrays.asList(days).subList(1, 8));
 

Each constraint, represented by a Spring object, controls the vertical or horizontal distance between two component edges. The edges can belong to any child of the container, or to the container itself. For example, the allowable width of a component can be expressed using a constraint that controls the distance between the west (left) and east (right) edges of the component. The allowable y coordinates for a component can be expressed by constraining the distance between the north (top) edge of the component and the north edge of its container.

Every child of a SpringLayout-controlled container, as well as the container itself, has exactly one set of constraints associated with it. These constraints are represented by a SpringLayout.Constraints object. By default, SpringLayout creates constraints that make their associated component have the minimum, preferred, and maximum sizes returned by the component's java.awt.Component.getMinimumSize , java.awt.Component.getPreferredSize , and java.awt.Component.getMaximumSize methods.

When writing a multi-threaded application using Swing, there are two constraints to keep in mind: (refer to How to Use Threads for more details):

• Time-consuming tasks should not be run on the Event Dispatch Thread.

This implementation spreads table rows naturally in sequence across multiple pages, fitting as many rows as possible per page. The distribution of columns, on the other hand, is controlled by a printing mode parameter passed to the constructor.

ToolTipManager contains numerous properties for configuring how long it will take for the tooltips to become visible, and how long till they hide.

Specifying the look and feel

Warning: Serialized objects of this class will not be compatible with future Swing releases.