mirror of
https://github.com/openjdk/jdk.git
synced 2026-07-10 19:19:22 +00:00
154 lines
6.9 KiB
Java
154 lines
6.9 KiB
Java
/*
|
|
* Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* This code is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License version 2 only, as
|
|
* published by the Free Software Foundation. Oracle designates this
|
|
* particular file as subject to the "Classpath" exception as provided
|
|
* by Oracle in the LICENSE file that accompanied this code.
|
|
*
|
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
* version 2 for more details (a copy is included in the LICENSE file that
|
|
* accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU General Public License version
|
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
*
|
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.com if you need additional information or have any
|
|
* questions.
|
|
*/
|
|
|
|
/**
|
|
* 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
|
|
* <a href="https://docs.oracle.com/javase/tutorial/uiswing/index.html"
|
|
* target="_top">Creating a GUI with JFC/Swing</a>, a trail in
|
|
* <em>The Java Tutorial</em>. For other resources, see
|
|
* <a href="#related">Related Documentation</a>.
|
|
*
|
|
* <h2><a id="threading">Swing's Threading Policy</a></h2>
|
|
* In general Swing is not thread safe. All Swing components and related
|
|
* classes, unless otherwise documented, must be accessed on the event
|
|
* dispatching thread.
|
|
* <p>
|
|
* 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.
|
|
* <p>
|
|
* 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:
|
|
* <pre>
|
|
* 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());
|
|
* }
|
|
* }</pre>
|
|
* Or:<pre>
|
|
* 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();
|
|
* }
|
|
* });
|
|
* }
|
|
* }</pre>
|
|
* This restriction also applies to models attached to Swing components. For
|
|
* example, if a {@code TableModel} is attached to a {@code JTable}, the
|
|
* {@code 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.
|
|
* <p>
|
|
* 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
|
|
* {@link javax.swing.SwingUtilities#invokeLater(Runnable)} so that any changes
|
|
* to UI rendering will be done post processing all the model listeners
|
|
* installed by the component.
|
|
* </p>
|
|
* <p>
|
|
*
|
|
* 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 javax.swing.SwingWorker} for the preferred way to do such processing
|
|
* when working with Swing.
|
|
* <p>
|
|
* More information on this topic can be found in the
|
|
* <a href="https://docs.oracle.com/javase/tutorial/uiswing/">Swing tutorial</a>,
|
|
* in particular the section on
|
|
* <a
|
|
* href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/index.html">
|
|
* Concurrency in Swing</a>.
|
|
*
|
|
* <h2><a id="serialization">Swing's Serialization policy</a></h2>
|
|
* <strong>Warning:</strong>
|
|
* Serialized objects of any Swing class will not be compatible with
|
|
* future Swing releases. The current serialization support is
|
|
* appropriate for short term storage or RMI between applications running
|
|
* the same version of Swing. As of 1.4, support for long term storage
|
|
* of all JavaBeans has been added to the <code>java.beans</code> package.
|
|
*
|
|
* <h2><a id="related">Related Documentation</a></h2>
|
|
* For overviews, tutorials, examples, guides, and other documentation,
|
|
* please see:
|
|
* <ul>
|
|
* <li><a href="https://www.oracle.com/java/technologies/a-swing-architecture.html"
|
|
* target="_top">A Swing Architecture Overview</a></li>
|
|
* <li><a href="https://docs.oracle.com/javase/tutorial/"
|
|
* target="_top">The Java Tutorial</a></li>
|
|
* <li><a href="https://www.oracle.com/java/technologies/javase/training-support.html"
|
|
* target="_top">Java SE Training and Certification</a></li>
|
|
* </ul>
|
|
*
|
|
* @serial exclude
|
|
*/
|
|
package javax.swing;
|