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 }