Package 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
In general Swing is not thread safe. All Swing components and related classes, unless otherwise documented, must be accessed on the event dispatching thread.
Typical Swing applications do processing in response to an event generated from a user gesture. For example, clicking on a JButton notifies all ActionListeners added to the 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 main method, or methods in 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 invokeLater . The invokeLater method schedules a 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:
import javax.swing.SwingUtilities; 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()); >>
import javax.swing.SwingUtilities; 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(); >>); > >
This restriction also applies to models attached to Swing components. For example, if a TableModel is attached to a JTable , the TableModel should only be modified on the event dispatching thread. If you modify the model on a separate thread you run the risk of exceptions and possible display corruption.
Although it is generally safe to make updates to the UI immediately, when executing on the event dispatch thread, there is an exception : if a model listener tries to further change the UI before the UI has been updated to reflect a pending change then the UI may render incorrectly. This can happen if an application installed listener needs to update the UI in response to an event which will cause a change in the model structure. It is important to first allow component installed listeners to process this change, since there is no guarantee of the order in which listeners may be called. The solution is for the application listener to make the change using SwingUtilities.invokeLater(Runnable) so that any changes to UI rendering will be done post processing all the model listeners installed by the component.
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 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 Concurrency in Swing.
Related Documentation
Package 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
In general Swing is not thread safe. All Swing components and related classes, unless otherwise documented, must be accessed on the event dispatching thread.
Typical Swing applications do processing in response to an event generated from a user gesture. For example, clicking on a JButton notifies all ActionListeners added to the 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 main method, or methods in 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 invokeLater . The invokeLater method schedules a 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:
import javax.swing.SwingUtilities; 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()); >>
import javax.swing.SwingUtilities; 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(); >>); > >
This restriction also applies to models attached to Swing components. For example, if a TableModel is attached to a JTable , the TableModel should only be modified on the event dispatching thread. If you modify the model on a separate thread you run the risk of exceptions and possible display corruption.
Although it is generally safe to make updates to the UI immediately, when executing on the event dispatch thread, there is an exception : if a model listener tries to further change the UI before the UI has been updated to reflect a pending change then the UI may render incorrectly. This can happen if an application installed listener needs to update the UI in response to an event which will cause a change in the model structure. It is important to first allow component installed listeners to process this change, since there is no guarantee of the order in which listeners may be called. The solution is for the application listener to make the change using SwingUtilities.invokeLater so that any changes to UI rendering will be done post processing all the model listeners installed by the component.
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 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 Concurrency in Swing.
Related Documentation
The Action interface provides a useful extension to the ActionListener interface in cases where the same functionality may be accessed by several controls.
About the JFC and Swing
JFC is short for Java Foundation Classes, which encompass a group of features for building graphical user interfaces (GUIs) and adding rich graphics functionality and interactivity to Java applications. It is defined as containing the features shown in the table below.
| Feature | Description |
|---|---|
| Swing GUI Components | Includes everything from buttons to split panes to tables. Many components are capable of sorting, printing, and drag and drop, to name a few of the supported features. |
| Pluggable Look-and-Feel Support | The look and feel of Swing applications is pluggable, allowing a choice of look and feel. For example, the same program can use either the Java or the Windows look and feel. Additionally, the Java platform supports the GTK+ look and feel, which makes hundreds of existing look and feels available to Swing programs. Many more look-and-feel packages are available from various sources. |
| Accessibility API | Enables assistive technologies, such as screen readers and Braille displays, to get information from the user interface. |
| Java 2D API | Enables developers to easily incorporate high-quality 2D graphics, text, and images in applications and applets. Java 2D includes extensive APIs for generating and sending high-quality output to printing devices. |
| Internationalization | Allows developers to build applications that can interact with users worldwide in their own languages and cultural conventions. With the input method framework developers can build applications that accept text in languages that use thousands of different characters, such as Japanese, Chinese, or Korean. |
This trail concentrates on the Swing components. We help you choose the appropriate components for your GUI, tell you how to use them, and give you the background information you need to use them effectively. We also discuss other features as they apply to Swing components.
Which Swing Packages Should I Use?
The Swing API is powerful, flexible — and immense. The Swing API has 18 public packages:
| javax.accessibility | javax.swing.plaf | javax.swing.text |
| javax.swing | javax.swing.plaf.basic | javax.swing.text.html |
| javax.swing.border | javax.swing.plaf.metal | javax.swing.text.html.parser |
| javax.swing.colorchooser | javax.swing.plaf.multi | javax.swing.text.rtf |
| javax.swing.event | javax.swing.plaf.synth | javax.swing.tree |
| javax.swing.filechooser | javax.swing.table | javax.swing.undo |
Fortunately, most programs use only a small subset of the API. This trail sorts out the API for you, giving you examples of common code and pointing you to methods and classes you’re likely to need. Most of the code in this trail uses only one or two Swing packages: