1 /*
   2  * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javax.swing;
  26 
  27 import java.awt.*;
  28 import java.awt.event.*;
  29 import java.beans.PropertyChangeListener;
  30 import java.util.Locale;
  31 import java.util.Vector;
  32 import java.io.Serializable;
  33 
  34 import javax.accessibility.*;
  35 
  36 
  37 /**
  38  * An extended version of <code>java.awt.Frame</code> that adds support for
  39  * the JFC/Swing component architecture.
  40  * You can find task-oriented documentation about using <code>JFrame</code>
  41  * in <em>The Java Tutorial</em>, in the section
  42  * <a
  43  href="http://java.sun.com/docs/books/tutorial/uiswing/components/frame.html">How to Make Frames</a>.
  44  *
  45  * <p>
  46  * The <code>JFrame</code> class is slightly incompatible with <code>Frame</code>.
  47  * Like all other JFC/Swing top-level containers,
  48  * a <code>JFrame</code> contains a <code>JRootPane</code> as its only child.
  49  * The <b>content pane</b> provided by the root pane should,
  50  * as a rule, contain
  51  * all the non-menu components displayed by the <code>JFrame</code>.
  52  * This is different from the AWT <code>Frame</code> case.
  53  * As a conveniance <code>add</code> and its variants, <code>remove</code> and
  54  * <code>setLayout</code> have been overridden to forward to the
  55  * <code>contentPane</code> as necessary. This means you can write:
  56  * <pre>
  57  *       frame.add(child);
  58  * </pre>
  59  * And the child will be added to the contentPane.
  60  * The content pane will
  61  * always be non-null. Attempting to set it to null will cause the JFrame
  62  * to throw an exception. The default content pane will have a BorderLayout
  63  * manager set on it.
  64  * Refer to {@link javax.swing.RootPaneContainer}
  65  * for details on adding, removing and setting the <code>LayoutManager</code>
  66  * of a <code>JFrame</code>.
  67  * <p>
  68  * Unlike a <code>Frame</code>, a <code>JFrame</code> has some notion of how to
  69  * respond when the user attempts to close the window. The default behavior
  70  * is to simply hide the JFrame when the user closes the window. To change the
  71  * default behavior, you invoke the method
  72  * {@link #setDefaultCloseOperation}.
  73  * To make the <code>JFrame</code> behave the same as a <code>Frame</code>
  74  * instance, use
  75  * <code>setDefaultCloseOperation(WindowConstants.DO_NOTHING_ON_CLOSE)</code>.
  76  * <p>
  77  * For more information on content panes
  78  * and other features that root panes provide,
  79  * see <a
  80  href="http://java.sun.com/docs/books/tutorial/uiswing/components/toplevel.html">Using Top-Level Containers</a> in <em>The Java Tutorial</em>.
  81  * <p>
  82  * In a multi-screen environment, you can create a <code>JFrame</code>
  83  * on a different screen device.  See {@link java.awt.Frame} for more
  84  * information.
  85  * <p>
  86  * <strong>Warning:</strong> Swing is not thread safe. For more
  87  * information see <a
  88  * href="package-summary.html#threading">Swing's Threading
  89  * Policy</a>.
  90  * <p>
  91  * <strong>Warning:</strong>
  92  * Serialized objects of this class will not be compatible with
  93  * future Swing releases. The current serialization support is
  94  * appropriate for short term storage or RMI between applications running
  95  * the same version of Swing.  As of 1.4, support for long term storage
  96  * of all JavaBeans<sup><font size="-2">TM</font></sup>
  97  * has been added to the <code>java.beans</code> package.
  98  * Please see {@link java.beans.XMLEncoder}.
  99  *
 100  * @see JRootPane
 101  * @see #setDefaultCloseOperation
 102  * @see java.awt.event.WindowListener#windowClosing
 103  * @see javax.swing.RootPaneContainer
 104  *
 105  * @beaninfo
 106  *      attribute: isContainer true
 107  *      attribute: containerDelegate getContentPane
 108  *    description: A toplevel window which can be minimized to an icon.
 109  *
 110  * @author Jeff Dinkins
 111  * @author Georges Saab
 112  * @author David Kloba
 113  */
 114 public class JFrame  extends Frame implements WindowConstants,
 115                                               Accessible,
 116                                               RootPaneContainer,
 117                               TransferHandler.HasGetTransferHandler
 118 {
 119     /**
 120      * The exit application default window close operation. If a window
 121      * has this set as the close operation and is closed in an applet,
 122      * a <code>SecurityException</code> may be thrown.
 123      * It is recommended you only use this in an application.
 124      * <p>
 125      * @since 1.3
 126      */
 127     public static final int EXIT_ON_CLOSE = 3;
 128 
 129     /**
 130      * Key into the AppContext, used to check if should provide decorations
 131      * by default.
 132      */
 133     private static final Object defaultLookAndFeelDecoratedKey =
 134             new StringBuffer("JFrame.defaultLookAndFeelDecorated");
 135 
 136     private int defaultCloseOperation = HIDE_ON_CLOSE;
 137 
 138     /**
 139      * The <code>TransferHandler</code> for this frame.
 140      */
 141     private TransferHandler transferHandler;
 142 
 143     /**
 144      * The <code>JRootPane</code> instance that manages the
 145      * <code>contentPane</code>
 146      * and optional <code>menuBar</code> for this frame, as well as the
 147      * <code>glassPane</code>.
 148      *
 149      * @see JRootPane
 150      * @see RootPaneContainer
 151      */
 152     protected JRootPane rootPane;
 153 
 154     /**
 155      * If true then calls to <code>add</code> and <code>setLayout</code>
 156      * will be forwarded to the <code>contentPane</code>. This is initially
 157      * false, but is set to true when the <code>JFrame</code> is constructed.
 158      *
 159      * @see #isRootPaneCheckingEnabled
 160      * @see #setRootPaneCheckingEnabled
 161      * @see javax.swing.RootPaneContainer
 162      */
 163     protected boolean rootPaneCheckingEnabled = false;
 164 
 165 
 166     /**
 167      * Constructs a new frame that is initially invisible.
 168      * <p>
 169      * This constructor sets the component's locale property to the value
 170      * returned by <code>JComponent.getDefaultLocale</code>.
 171      *
 172      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
 173      * returns true.
 174      * @see java.awt.GraphicsEnvironment#isHeadless
 175      * @see Component#setSize
 176      * @see Component#setVisible
 177      * @see JComponent#getDefaultLocale
 178      */
 179     public JFrame() throws HeadlessException {
 180         super();
 181         frameInit();
 182     }
 183 
 184     /**
 185      * Creates a <code>Frame</code> in the specified
 186      * <code>GraphicsConfiguration</code> of
 187      * a screen device and a blank title.
 188      * <p>
 189      * This constructor sets the component's locale property to the value
 190      * returned by <code>JComponent.getDefaultLocale</code>.
 191      *
 192      * @param gc the <code>GraphicsConfiguration</code> that is used
 193      *          to construct the new <code>Frame</code>;
 194      *          if <code>gc</code> is <code>null</code>, the system
 195      *          default <code>GraphicsConfiguration</code> is assumed
 196      * @exception IllegalArgumentException if <code>gc</code> is not from
 197      *          a screen device.  This exception is always thrown when
 198      *      GraphicsEnvironment.isHeadless() returns true.
 199      * @see java.awt.GraphicsEnvironment#isHeadless
 200      * @see JComponent#getDefaultLocale
 201      * @since     1.3
 202      */
 203     public JFrame(GraphicsConfiguration gc) {
 204         super(gc);
 205         frameInit();
 206     }
 207 
 208     /**
 209      * Creates a new, initially invisible <code>Frame</code> with the
 210      * specified title.
 211      * <p>
 212      * This constructor sets the component's locale property to the value
 213      * returned by <code>JComponent.getDefaultLocale</code>.
 214      *
 215      * @param title the title for the frame
 216      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
 217      * returns true.
 218      * @see java.awt.GraphicsEnvironment#isHeadless
 219      * @see Component#setSize
 220      * @see Component#setVisible
 221      * @see JComponent#getDefaultLocale
 222      */
 223     public JFrame(String title) throws HeadlessException {
 224         super(title);
 225         frameInit();
 226     }
 227 
 228     /**
 229      * Creates a <code>JFrame</code> with the specified title and the
 230      * specified <code>GraphicsConfiguration</code> of a screen device.
 231      * <p>
 232      * This constructor sets the component's locale property to the value
 233      * returned by <code>JComponent.getDefaultLocale</code>.
 234      *
 235      * @param title the title to be displayed in the
 236      *          frame's border. A <code>null</code> value is treated as
 237      *          an empty string, "".
 238      * @param gc the <code>GraphicsConfiguration</code> that is used
 239      *          to construct the new <code>JFrame</code> with;
 240      *          if <code>gc</code> is <code>null</code>, the system
 241      *          default <code>GraphicsConfiguration</code> is assumed
 242      * @exception IllegalArgumentException if <code>gc</code> is not from
 243      *          a screen device.  This exception is always thrown when
 244      *      GraphicsEnvironment.isHeadless() returns true.
 245      * @see java.awt.GraphicsEnvironment#isHeadless
 246      * @see JComponent#getDefaultLocale
 247      * @since     1.3
 248      */
 249     public JFrame(String title, GraphicsConfiguration gc) {
 250         super(title, gc);
 251         frameInit();
 252     }
 253 
 254     /** Called by the constructors to init the <code>JFrame</code> properly. */
 255     protected void frameInit() {
 256         enableEvents(AWTEvent.KEY_EVENT_MASK | AWTEvent.WINDOW_EVENT_MASK);
 257         setLocale( JComponent.getDefaultLocale() );
 258         setRootPane(createRootPane());
 259         setBackground(UIManager.getColor("control"));
 260         setRootPaneCheckingEnabled(true);
 261         if (JFrame.isDefaultLookAndFeelDecorated()) {
 262             boolean supportsWindowDecorations =
 263             UIManager.getLookAndFeel().getSupportsWindowDecorations();
 264             if (supportsWindowDecorations) {
 265                 setUndecorated(true);
 266                 getRootPane().setWindowDecorationStyle(JRootPane.FRAME);
 267             }
 268         }
 269         sun.awt.SunToolkit.checkAndSetPolicy(this, true);
 270     }
 271 
 272     /**
 273      * Called by the constructor methods to create the default
 274      * <code>rootPane</code>.
 275      */
 276     protected JRootPane createRootPane() {
 277         JRootPane rp = new JRootPane();
 278         // NOTE: this uses setOpaque vs LookAndFeel.installProperty as there
 279         // is NO reason for the RootPane not to be opaque. For painting to
 280         // work the contentPane must be opaque, therefor the RootPane can
 281         // also be opaque.
 282         rp.setOpaque(true);
 283         return rp;
 284     }
 285 
 286     /**
 287      * Processes window events occurring on this component.
 288      * Hides the window or disposes of it, as specified by the setting
 289      * of the <code>defaultCloseOperation</code> property.
 290      *
 291      * @param  e  the window event
 292      * @see    #setDefaultCloseOperation
 293      * @see    java.awt.Window#processWindowEvent
 294      */
 295     protected void processWindowEvent(WindowEvent e) {
 296         super.processWindowEvent(e);
 297 
 298         if (e.getID() == WindowEvent.WINDOW_CLOSING) {
 299             switch(defaultCloseOperation) {
 300               case HIDE_ON_CLOSE:
 301                  setVisible(false);
 302                  break;
 303               case DISPOSE_ON_CLOSE:
 304                  dispose();
 305                  break;
 306               case DO_NOTHING_ON_CLOSE:
 307                  default:
 308                  break;
 309               case EXIT_ON_CLOSE:
 310                   // This needs to match the checkExit call in
 311                   // setDefaultCloseOperation
 312                 System.exit(0);
 313                 break;
 314             }
 315         }
 316     }
 317 
 318 //    public void setMenuBar(MenuBar menu) {
 319 //        throw new IllegalComponentStateException("Please use setJMenuBar() with JFrame.");
 320 //    }
 321 
 322     /**
 323      * Sets the operation that will happen by default when
 324      * the user initiates a "close" on this frame.
 325      * You must specify one of the following choices:
 326      * <p>
 327      * <ul>
 328      * <li><code>DO_NOTHING_ON_CLOSE</code>
 329      * (defined in <code>WindowConstants</code>):
 330      * Don't do anything; require the
 331      * program to handle the operation in the <code>windowClosing</code>
 332      * method of a registered <code>WindowListener</code> object.
 333      *
 334      * <li><code>HIDE_ON_CLOSE</code>
 335      * (defined in <code>WindowConstants</code>):
 336      * Automatically hide the frame after
 337      * invoking any registered <code>WindowListener</code>
 338      * objects.
 339      *
 340      * <li><code>DISPOSE_ON_CLOSE</code>
 341      * (defined in <code>WindowConstants</code>):
 342      * Automatically hide and dispose the
 343      * frame after invoking any registered <code>WindowListener</code>
 344      * objects.
 345      *
 346      * <li><code>EXIT_ON_CLOSE</code>
 347      * (defined in <code>JFrame</code>):
 348      * Exit the application using the <code>System</code>
 349      * <code>exit</code> method.  Use this only in applications.
 350      * </ul>
 351      * <p>
 352      * The value is set to <code>HIDE_ON_CLOSE</code> by default. Changes
 353      * to the value of this property cause the firing of a property
 354      * change event, with property name "defaultCloseOperation".
 355      * <p>
 356      * <b>Note</b>: When the last displayable window within the
 357      * Java virtual machine (VM) is disposed of, the VM may
 358      * terminate.  See <a href="../../java/awt/doc-files/AWTThreadIssues.html">
 359      * AWT Threading Issues</a> for more information.
 360      *
 361      * @param operation the operation which should be performed when the
 362      *        user closes the frame
 363      * @exception IllegalArgumentException if defaultCloseOperation value
 364      *             isn't one of the above valid values
 365      * @see #addWindowListener
 366      * @see #getDefaultCloseOperation
 367      * @see WindowConstants
 368      * @throws  SecurityException
 369      *        if <code>EXIT_ON_CLOSE</code> has been specified and the
 370      *        <code>SecurityManager</code> will
 371      *        not allow the caller to invoke <code>System.exit</code>
 372      * @see        java.lang.Runtime#exit(int)
 373      *
 374      * @beaninfo
 375      *   preferred: true
 376      *       bound: true
 377      *        enum: DO_NOTHING_ON_CLOSE WindowConstants.DO_NOTHING_ON_CLOSE
 378      *              HIDE_ON_CLOSE       WindowConstants.HIDE_ON_CLOSE
 379      *              DISPOSE_ON_CLOSE    WindowConstants.DISPOSE_ON_CLOSE
 380      *              EXIT_ON_CLOSE       WindowConstants.EXIT_ON_CLOSE
 381      * description: The frame's default close operation.
 382      */
 383     public void setDefaultCloseOperation(int operation) {
 384         if (operation != DO_NOTHING_ON_CLOSE &&
 385             operation != HIDE_ON_CLOSE &&
 386             operation != DISPOSE_ON_CLOSE &&
 387             operation != EXIT_ON_CLOSE) {
 388             throw new IllegalArgumentException("defaultCloseOperation must be one of: DO_NOTHING_ON_CLOSE, HIDE_ON_CLOSE, DISPOSE_ON_CLOSE, or EXIT_ON_CLOSE");
 389         }
 390         if (this.defaultCloseOperation != operation) {
 391             if (operation == EXIT_ON_CLOSE) {
 392                 SecurityManager security = System.getSecurityManager();
 393                 if (security != null) {
 394                     security.checkExit(0);
 395                 }
 396             }
 397             int oldValue = this.defaultCloseOperation;
 398             this.defaultCloseOperation = operation;
 399             firePropertyChange("defaultCloseOperation", oldValue, operation);
 400         }
 401     }
 402 
 403 
 404    /**
 405     * Returns the operation that occurs when the user
 406     * initiates a "close" on this frame.
 407     *
 408     * @return an integer indicating the window-close operation
 409     * @see #setDefaultCloseOperation
 410     */
 411     public int getDefaultCloseOperation() {
 412         return defaultCloseOperation;
 413     }
 414 
 415     /**
 416      * Sets the {@code transferHandler} property, which is a mechanism to
 417      * support transfer of data into this component. Use {@code null}
 418      * if the component does not support data transfer operations.
 419      * <p>
 420      * If the system property {@code suppressSwingDropSupport} is {@code false}
 421      * (the default) and the current drop target on this component is either
 422      * {@code null} or not a user-set drop target, this method will change the
 423      * drop target as follows: If {@code newHandler} is {@code null} it will
 424      * clear the drop target. If not {@code null} it will install a new
 425      * {@code DropTarget}.
 426      * <p>
 427      * Note: When used with {@code JFrame}, {@code TransferHandler} only
 428      * provides data import capability, as the data export related methods
 429      * are currently typed to {@code JComponent}.
 430      * <p>
 431      * Please see
 432      * <a href="http://java.sun.com/docs/books/tutorial/uiswing/misc/dnd.html">
 433      * How to Use Drag and Drop and Data Transfer</a>, a section in
 434      * <em>The Java Tutorial</em>, for more information.
 435      *
 436      * @param newHandler the new {@code TransferHandler}
 437      *
 438      * @see TransferHandler
 439      * @see #getTransferHandler
 440      * @see java.awt.Component#setDropTarget
 441      * @since 1.6
 442      *
 443      * @beaninfo
 444      *        bound: true
 445      *       hidden: true
 446      *  description: Mechanism for transfer of data into the component
 447      */
 448     public void setTransferHandler(TransferHandler newHandler) {
 449         TransferHandler oldHandler = transferHandler;
 450         transferHandler = newHandler;
 451         SwingUtilities.installSwingDropTargetAsNecessary(this, transferHandler);
 452         firePropertyChange("transferHandler", oldHandler, newHandler);
 453     }
 454 
 455     /**
 456      * Gets the <code>transferHandler</code> property.
 457      *
 458      * @return the value of the <code>transferHandler</code> property
 459      *
 460      * @see TransferHandler
 461      * @see #setTransferHandler
 462      * @since 1.6
 463      */
 464     public TransferHandler getTransferHandler() {
 465         return transferHandler;
 466     }
 467 
 468     /**
 469      * Just calls <code>paint(g)</code>.  This method was overridden to
 470      * prevent an unnecessary call to clear the background.
 471      *
 472      * @param g the Graphics context in which to paint
 473      */
 474     public void update(Graphics g) {
 475         paint(g);
 476     }
 477 
 478    /**
 479     * Sets the menubar for this frame.
 480     * @param menubar the menubar being placed in the frame
 481     *
 482     * @see #getJMenuBar
 483     *
 484     * @beaninfo
 485     *      hidden: true
 486     * description: The menubar for accessing pulldown menus from this frame.
 487     */
 488     public void setJMenuBar(JMenuBar menubar) {
 489         getRootPane().setMenuBar(menubar);
 490     }
 491 
 492    /**
 493     * Returns the menubar set on this frame.
 494     * @return the menubar for this frame
 495     *
 496     * @see #setJMenuBar
 497     */
 498     public JMenuBar getJMenuBar() {
 499         return getRootPane().getMenuBar();
 500     }
 501 
 502     /**
 503      * Returns whether calls to <code>add</code> and
 504      * <code>setLayout</code> are forwarded to the <code>contentPane</code>.
 505      *
 506      * @return true if <code>add</code> and <code>setLayout</code>
 507      *         are fowarded; false otherwise
 508      *
 509      * @see #addImpl
 510      * @see #setLayout
 511      * @see #setRootPaneCheckingEnabled
 512      * @see javax.swing.RootPaneContainer
 513      */
 514     protected boolean isRootPaneCheckingEnabled() {
 515         return rootPaneCheckingEnabled;
 516     }
 517 
 518 
 519     /**
 520      * Sets whether calls to <code>add</code> and
 521      * <code>setLayout</code> are forwarded to the <code>contentPane</code>.
 522      *
 523      * @param enabled  true if <code>add</code> and <code>setLayout</code>
 524      *        are forwarded, false if they should operate directly on the
 525      *        <code>JFrame</code>.
 526      *
 527      * @see #addImpl
 528      * @see #setLayout
 529      * @see #isRootPaneCheckingEnabled
 530      * @see javax.swing.RootPaneContainer
 531      * @beaninfo
 532      *      hidden: true
 533      * description: Whether the add and setLayout methods are forwarded
 534      */
 535     protected void setRootPaneCheckingEnabled(boolean enabled) {
 536         rootPaneCheckingEnabled = enabled;
 537     }
 538 
 539 
 540     /**
 541      * Adds the specified child <code>Component</code>.
 542      * This method is overridden to conditionally forward calls to the
 543      * <code>contentPane</code>.
 544      * By default, children are added to the <code>contentPane</code> instead
 545      * of the frame, refer to {@link javax.swing.RootPaneContainer} for
 546      * details.
 547      *
 548      * @param comp the component to be enhanced
 549      * @param constraints the constraints to be respected
 550      * @param index the index
 551      * @exception IllegalArgumentException if <code>index</code> is invalid
 552      * @exception IllegalArgumentException if adding the container's parent
 553      *                  to itself
 554      * @exception IllegalArgumentException if adding a window to a container
 555      *
 556      * @see #setRootPaneCheckingEnabled
 557      * @see javax.swing.RootPaneContainer
 558      */
 559     protected void addImpl(Component comp, Object constraints, int index)
 560     {
 561         if(isRootPaneCheckingEnabled()) {
 562             getContentPane().add(comp, constraints, index);
 563         }
 564         else {
 565             super.addImpl(comp, constraints, index);
 566         }
 567     }
 568 
 569     /**
 570      * Removes the specified component from the container. If
 571      * <code>comp</code> is not the <code>rootPane</code>, this will forward
 572      * the call to the <code>contentPane</code>. This will do nothing if
 573      * <code>comp</code> is not a child of the <code>JFrame</code> or
 574      * <code>contentPane</code>.
 575      *
 576      * @param comp the component to be removed
 577      * @throws NullPointerException if <code>comp</code> is null
 578      * @see #add
 579      * @see javax.swing.RootPaneContainer
 580      */
 581     public void remove(Component comp) {
 582         if (comp == rootPane) {
 583             super.remove(comp);
 584         } else {
 585             getContentPane().remove(comp);
 586         }
 587     }
 588 
 589 
 590     /**
 591      * Sets the <code>LayoutManager</code>.
 592      * Overridden to conditionally forward the call to the
 593      * <code>contentPane</code>.
 594      * Refer to {@link javax.swing.RootPaneContainer} for
 595      * more information.
 596      *
 597      * @param manager the <code>LayoutManager</code>
 598      * @see #setRootPaneCheckingEnabled
 599      * @see javax.swing.RootPaneContainer
 600      */
 601     public void setLayout(LayoutManager manager) {
 602         if(isRootPaneCheckingEnabled()) {
 603             getContentPane().setLayout(manager);
 604         }
 605         else {
 606             super.setLayout(manager);
 607         }
 608     }
 609 
 610 
 611     /**
 612      * Returns the <code>rootPane</code> object for this frame.
 613      * @return the <code>rootPane</code> property
 614      *
 615      * @see #setRootPane
 616      * @see RootPaneContainer#getRootPane
 617      */
 618     public JRootPane getRootPane() {
 619         return rootPane;
 620     }
 621 
 622 
 623     /**
 624      * Sets the <code>rootPane</code> property.
 625      * This method is called by the constructor.
 626      * @param root the <code>rootPane</code> object for this frame
 627      *
 628      * @see #getRootPane
 629      *
 630      * @beaninfo
 631      *   hidden: true
 632      * description: the RootPane object for this frame.
 633      */
 634     protected void setRootPane(JRootPane root)
 635     {
 636         if(rootPane != null) {
 637             remove(rootPane);
 638         }
 639         rootPane = root;
 640         if(rootPane != null) {
 641             boolean checkingEnabled = isRootPaneCheckingEnabled();
 642             try {
 643                 setRootPaneCheckingEnabled(false);
 644                 add(rootPane, BorderLayout.CENTER);
 645             }
 646             finally {
 647                 setRootPaneCheckingEnabled(checkingEnabled);
 648             }
 649         }
 650     }
 651 
 652     /**
 653      * {@inheritDoc}
 654      */
 655     public void setIconImage(Image image) {
 656         super.setIconImage(image);
 657     }
 658 
 659     /**
 660      * Returns the <code>contentPane</code> object for this frame.
 661      * @return the <code>contentPane</code> property
 662      *
 663      * @see #setContentPane
 664      * @see RootPaneContainer#getContentPane
 665      */
 666     public Container getContentPane() {
 667         return getRootPane().getContentPane();
 668     }
 669 
 670     /**
 671      * Sets the <code>contentPane</code> property.
 672      * This method is called by the constructor.
 673      * <p>
 674      * Swing's painting architecture requires an opaque <code>JComponent</code>
 675      * in the containment hiearchy. This is typically provided by the
 676      * content pane. If you replace the content pane it is recommended you
 677      * replace it with an opaque <code>JComponent</code>.
 678      *
 679      * @param contentPane the <code>contentPane</code> object for this frame
 680      *
 681      * @exception java.awt.IllegalComponentStateException (a runtime
 682      *            exception) if the content pane parameter is <code>null</code>
 683      * @see #getContentPane
 684      * @see RootPaneContainer#setContentPane
 685      * @see JRootPane
 686      *
 687      * @beaninfo
 688      *     hidden: true
 689      *     description: The client area of the frame where child
 690      *                  components are normally inserted.
 691      */
 692     public void setContentPane(Container contentPane) {
 693         getRootPane().setContentPane(contentPane);
 694     }
 695 
 696     /**
 697      * Returns the <code>layeredPane</code> object for this frame.
 698      * @return the <code>layeredPane</code> property
 699      *
 700      * @see #setLayeredPane
 701      * @see RootPaneContainer#getLayeredPane
 702      */
 703     public JLayeredPane getLayeredPane() {
 704         return getRootPane().getLayeredPane();
 705     }
 706 
 707     /**
 708      * Sets the <code>layeredPane</code> property.
 709      * This method is called by the constructor.
 710      * @param layeredPane the <code>layeredPane</code> object for this frame
 711      *
 712      * @exception java.awt.IllegalComponentStateException (a runtime
 713      *            exception) if the layered pane parameter is <code>null</code>
 714      * @see #getLayeredPane
 715      * @see RootPaneContainer#setLayeredPane
 716      *
 717      * @beaninfo
 718      *     hidden: true
 719      *     description: The pane that holds the various frame layers.
 720      */
 721     public void setLayeredPane(JLayeredPane layeredPane) {
 722         getRootPane().setLayeredPane(layeredPane);
 723     }
 724 
 725     /**
 726      * Returns the <code>glassPane</code> object for this frame.
 727      * @return the <code>glassPane</code> property
 728      *
 729      * @see #setGlassPane
 730      * @see RootPaneContainer#getGlassPane
 731      */
 732     public Component getGlassPane() {
 733         return getRootPane().getGlassPane();
 734     }
 735 
 736     /**
 737      * Sets the <code>glassPane</code> property.
 738      * This method is called by the constructor.
 739      * @param glassPane the <code>glassPane</code> object for this frame
 740      *
 741      * @see #getGlassPane
 742      * @see RootPaneContainer#setGlassPane
 743      *
 744      * @beaninfo
 745      *     hidden: true
 746      *     description: A transparent pane used for menu rendering.
 747      */
 748     public void setGlassPane(Component glassPane) {
 749         getRootPane().setGlassPane(glassPane);
 750     }
 751 
 752     /**
 753      * {@inheritDoc}
 754      *
 755      * @since 1.6
 756      */
 757     public Graphics getGraphics() {
 758         JComponent.getGraphicsInvoked(this);
 759         return super.getGraphics();
 760     }
 761 
 762     /**
 763      * Repaints the specified rectangle of this component within
 764      * <code>time</code> milliseconds.  Refer to <code>RepaintManager</code>
 765      * for details on how the repaint is handled.
 766      *
 767      * @param     time   maximum time in milliseconds before update
 768      * @param     x    the <i>x</i> coordinate
 769      * @param     y    the <i>y</i> coordinate
 770      * @param     width    the width
 771      * @param     height   the height
 772      * @see       RepaintManager
 773      * @since     1.6
 774      */
 775     public void repaint(long time, int x, int y, int width, int height) {
 776         if (RepaintManager.HANDLE_TOP_LEVEL_PAINT) {
 777             RepaintManager.currentManager(this).addDirtyRegion(
 778                               this, x, y, width, height);
 779         }
 780         else {
 781             super.repaint(time, x, y, width, height);
 782         }
 783     }
 784 
 785     /**
 786      * Provides a hint as to whether or not newly created <code>JFrame</code>s
 787      * should have their Window decorations (such as borders, widgets to
 788      * close the window, title...) provided by the current look
 789      * and feel. If <code>defaultLookAndFeelDecorated</code> is true,
 790      * the current <code>LookAndFeel</code> supports providing window
 791      * decorations, and the current window manager supports undecorated
 792      * windows, then newly created <code>JFrame</code>s will have their
 793      * Window decorations provided by the current <code>LookAndFeel</code>.
 794      * Otherwise, newly created <code>JFrame</code>s will have their
 795      * Window decorations provided by the current window manager.
 796      * <p>
 797      * You can get the same effect on a single JFrame by doing the following:
 798      * <pre>
 799      *    JFrame frame = new JFrame();
 800      *    frame.setUndecorated(true);
 801      *    frame.getRootPane().setWindowDecorationStyle(JRootPane.FRAME);
 802      * </pre>
 803      *
 804      * @param defaultLookAndFeelDecorated A hint as to whether or not current
 805      *        look and feel should provide window decorations
 806      * @see javax.swing.LookAndFeel#getSupportsWindowDecorations
 807      * @since 1.4
 808      */
 809     public static void setDefaultLookAndFeelDecorated(boolean defaultLookAndFeelDecorated) {
 810         if (defaultLookAndFeelDecorated) {
 811             SwingUtilities.appContextPut(defaultLookAndFeelDecoratedKey, Boolean.TRUE);
 812         } else {
 813             SwingUtilities.appContextPut(defaultLookAndFeelDecoratedKey, Boolean.FALSE);
 814         }
 815     }
 816 
 817 
 818     /**
 819      * Returns true if newly created <code>JFrame</code>s should have their
 820      * Window decorations provided by the current look and feel. This is only
 821      * a hint, as certain look and feels may not support this feature.
 822      *
 823      * @return true if look and feel should provide Window decorations.
 824      * @since 1.4
 825      */
 826     public static boolean isDefaultLookAndFeelDecorated() {
 827         Boolean defaultLookAndFeelDecorated =
 828             (Boolean) SwingUtilities.appContextGet(defaultLookAndFeelDecoratedKey);
 829         if (defaultLookAndFeelDecorated == null) {
 830             defaultLookAndFeelDecorated = Boolean.FALSE;
 831         }
 832         return defaultLookAndFeelDecorated.booleanValue();
 833     }
 834 
 835     /**
 836      * Returns a string representation of this <code>JFrame</code>.
 837      * This method
 838      * is intended to be used only for debugging purposes, and the
 839      * content and format of the returned string may vary between
 840      * implementations. The returned string may be empty but may not
 841      * be <code>null</code>.
 842      *
 843      * @return  a string representation of this <code>JFrame</code>
 844      */
 845     protected String paramString() {
 846         String defaultCloseOperationString;
 847         if (defaultCloseOperation == HIDE_ON_CLOSE) {
 848             defaultCloseOperationString = "HIDE_ON_CLOSE";
 849         } else if (defaultCloseOperation == DISPOSE_ON_CLOSE) {
 850             defaultCloseOperationString = "DISPOSE_ON_CLOSE";
 851         } else if (defaultCloseOperation == DO_NOTHING_ON_CLOSE) {
 852             defaultCloseOperationString = "DO_NOTHING_ON_CLOSE";
 853         } else if (defaultCloseOperation == 3) {
 854             defaultCloseOperationString = "EXIT_ON_CLOSE";
 855         } else defaultCloseOperationString = "";
 856         String rootPaneString = (rootPane != null ?
 857                                  rootPane.toString() : "");
 858         String rootPaneCheckingEnabledString = (rootPaneCheckingEnabled ?
 859                                                 "true" : "false");
 860 
 861         return super.paramString() +
 862         ",defaultCloseOperation=" + defaultCloseOperationString +
 863         ",rootPane=" + rootPaneString +
 864         ",rootPaneCheckingEnabled=" + rootPaneCheckingEnabledString;
 865     }
 866 
 867 
 868 
 869 /////////////////
 870 // Accessibility support
 871 ////////////////
 872 
 873     /** The accessible context property. */
 874     protected AccessibleContext accessibleContext = null;
 875 
 876     /**
 877      * Gets the AccessibleContext associated with this JFrame.
 878      * For JFrames, the AccessibleContext takes the form of an
 879      * AccessibleJFrame.
 880      * A new AccessibleJFrame instance is created if necessary.
 881      *
 882      * @return an AccessibleJFrame that serves as the
 883      *         AccessibleContext of this JFrame
 884      */
 885     public AccessibleContext getAccessibleContext() {
 886         if (accessibleContext == null) {
 887             accessibleContext = new AccessibleJFrame();
 888         }
 889         return accessibleContext;
 890     }
 891 
 892     /**
 893      * This class implements accessibility support for the
 894      * <code>JFrame</code> class.  It provides an implementation of the
 895      * Java Accessibility API appropriate to frame user-interface
 896      * elements.
 897      */
 898     protected class AccessibleJFrame extends AccessibleAWTFrame {
 899 
 900         // AccessibleContext methods
 901         /**
 902          * Get the accessible name of this object.
 903          *
 904          * @return the localized name of the object -- can be null if this
 905          * object does not have a name
 906          */
 907         public String getAccessibleName() {
 908             if (accessibleName != null) {
 909                 return accessibleName;
 910             } else {
 911                 if (getTitle() == null) {
 912                     return super.getAccessibleName();
 913                 } else {
 914                     return getTitle();
 915                 }
 916             }
 917         }
 918 
 919         /**
 920          * Get the state of this object.
 921          *
 922          * @return an instance of AccessibleStateSet containing the current
 923          * state set of the object
 924          * @see AccessibleState
 925          */
 926         public AccessibleStateSet getAccessibleStateSet() {
 927             AccessibleStateSet states = super.getAccessibleStateSet();
 928 
 929             if (isResizable()) {
 930                 states.add(AccessibleState.RESIZABLE);
 931             }
 932             if (getFocusOwner() != null) {
 933                 states.add(AccessibleState.ACTIVE);
 934             }
 935             // FIXME:  [[[WDW - should also return ICONIFIED and ICONIFIABLE
 936             // if we can ever figure these out]]]
 937             return states;
 938         }
 939     } // inner class AccessibleJFrame
 940 }