View Javadoc
1   /*
2    * Copyright (c) 1998, 2013, 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  
26  package javax.swing;
27  
28  import java.awt.Component;
29  import java.awt.Container;
30  
31  
32  /**
33   * This interface is implemented by components that have a single
34   * JRootPane child: JDialog, JFrame, JWindow, JApplet, JInternalFrame.
35   * The methods in  this interface are just <i>covers</i> for the JRootPane
36   * properties, e.g. <code>getContentPane()</code> is generally implemented
37   * like this:<pre>
38   *     public Container getContentPane() {
39   *         return getRootPane().getContentPane();
40   *     }
41   * </pre>
42   * This interface serves as a <i>marker</i> for Swing GUI builders
43   * that need to treat components like JFrame, that contain a
44   * single JRootPane, specially.  For example in a GUI builder,
45   * dropping a component on a RootPaneContainer would be interpreted
46   * as <code>frame.getContentPane().add(child)</code>.
47   * <p>
48   * As a convenience, the standard classes that implement this interface
49   * (such as {@code JFrame}, {@code JDialog}, {@code JWindow}, {@code JApplet},
50   * and {@code JInternalFrame}) have their {@code add}, {@code remove},
51   * and {@code setLayout} methods overridden, so that they delegate calls
52   * to the corresponding methods of the {@code ContentPane}.
53   * For example, you can add a child component to a frame as follows:
54   * <pre>
55   *       frame.add(child);
56   * </pre>
57   * instead of:
58   * <pre>
59   *       frame.getContentPane().add(child);
60   * </pre>
61   * <p>
62   * The behavior of the <code>add</code> and
63   * <code>setLayout</code> methods for
64   * <code>JFrame</code>, <code>JDialog</code>, <code>JWindow</code>,
65   * <code>JApplet</code> and <code>JInternalFrame</code> is controlled by
66   * the <code>rootPaneCheckingEnabled</code> property. If this property is
67   * true (the default), then calls to these methods are
68    * forwarded to the <code>contentPane</code>; if false, these
69    * methods operate directly on the <code>RootPaneContainer</code>. This
70    * property is only intended for subclasses, and is therefore protected.
71   *
72   * @see JRootPane
73   * @see JFrame
74   * @see JDialog
75   * @see JWindow
76   * @see JApplet
77   * @see JInternalFrame
78   *
79   * @author Hans Muller
80   */
81  public interface RootPaneContainer
82  {
83      /**
84       * Return this component's single JRootPane child.  A conventional
85       * implementation of this interface will have all of the other
86       * methods indirect through this one.  The rootPane has two
87       * children: the glassPane and the layeredPane.
88       *
89       * @return this components single JRootPane child.
90       * @see JRootPane
91       */
92      JRootPane getRootPane();
93  
94  
95      /**
96       * The "contentPane" is the primary container for application
97       * specific components.  Applications should add children to
98       * the contentPane, set its layout manager, and so on.
99       * <p>
100      * The contentPane may not be null.
101      * <p>
102      * Generally implemented with
103      * <code>getRootPane().setContentPane(contentPane);</code>
104      *
105      * @exception java.awt.IllegalComponentStateException (a runtime
106      *            exception) if the content pane parameter is null
107      * @param contentPane the Container to use for the contents of this
108      *        JRootPane
109      * @see JRootPane#getContentPane
110      * @see #getContentPane
111      */
112     void setContentPane(Container contentPane);
113 
114 
115     /**
116      * Returns the contentPane.
117      *
118      * @return the value of the contentPane property.
119      * @see #setContentPane
120      */
121     Container getContentPane();
122 
123 
124     /**
125      * A Container that manages the contentPane and in some cases a menu bar.
126      * The layeredPane can be used by descendants that want to add a child
127      * to the RootPaneContainer that isn't layout managed.  For example
128      * an internal dialog or a drag and drop effect component.
129      * <p>
130      * The layeredPane may not be null.
131      * <p>
132      * Generally implemented with<pre>
133      *    getRootPane().setLayeredPane(layeredPane);</pre>
134      *
135      * @exception java.awt.IllegalComponentStateException (a runtime
136      *            exception) if the layered pane parameter is null
137      * @see #getLayeredPane
138      * @see JRootPane#getLayeredPane
139      */
140     void setLayeredPane(JLayeredPane layeredPane);
141 
142 
143     /**
144      * Returns the layeredPane.
145      *
146      * @return the value of the layeredPane property.
147      * @see #setLayeredPane
148      */
149     JLayeredPane getLayeredPane();
150 
151 
152     /**
153      * The glassPane is always the first child of the rootPane
154      * and the rootPanes layout manager ensures that it's always
155      * as big as the rootPane.  By default it's transparent and
156      * not visible.  It can be used to temporarily grab all keyboard
157      * and mouse input by adding listeners and then making it visible.
158      * by default it's not visible.
159      * <p>
160      * The glassPane may not be null.
161      * <p>
162      * Generally implemented with
163      * <code>getRootPane().setGlassPane(glassPane);</code>
164      *
165      * @see #getGlassPane
166      * @see JRootPane#setGlassPane
167      */
168     void setGlassPane(Component glassPane);
169 
170 
171     /**
172      * Returns the glassPane.
173      *
174      * @return the value of the glassPane property.
175      * @see #setGlassPane
176      */
177     Component getGlassPane();
178 
179 }