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 * @since 1.2
81 */
82 public interface RootPaneContainer
83 {
84 /**
85 * Return this component's single JRootPane child. A conventional
86 * implementation of this interface will have all of the other
87 * methods indirect through this one. The rootPane has two
88 * children: the glassPane and the layeredPane.
89 *
90 * @return this components single JRootPane child.
91 * @see JRootPane
92 */
93 JRootPane getRootPane();
94
95
96 /**
97 * The "contentPane" is the primary container for application
98 * specific components. Applications should add children to
99 * the contentPane, set its layout manager, and so on.
100 * <p>
101 * The contentPane may not be null.
102 * <p>
103 * Generally implemented with
104 * <code>getRootPane().setContentPane(contentPane);</code>
105 *
106 * @exception java.awt.IllegalComponentStateException (a runtime
107 * exception) if the content pane parameter is null
108 * @param contentPane the Container to use for the contents of this
109 * JRootPane
110 * @see JRootPane#getContentPane
111 * @see #getContentPane
112 */
113 void setContentPane(Container contentPane);
114
115
116 /**
117 * Returns the contentPane.
118 *
119 * @return the value of the contentPane property.
120 * @see #setContentPane
121 */
122 Container getContentPane();
123
124
125 /**
126 * A Container that manages the contentPane and in some cases a menu bar.
127 * The layeredPane can be used by descendants that want to add a child
128 * to the RootPaneContainer that isn't layout managed. For example
129 * an internal dialog or a drag and drop effect component.
130 * <p>
131 * The layeredPane may not be null.
132 * <p>
133 * Generally implemented with<pre>
134 * getRootPane().setLayeredPane(layeredPane);</pre>
135 *
136 * @exception java.awt.IllegalComponentStateException (a runtime
137 * exception) if the layered pane parameter is null
138 * @see #getLayeredPane
139 * @see JRootPane#getLayeredPane
140 */
141 void setLayeredPane(JLayeredPane layeredPane);
142
143
144 /**
145 * Returns the layeredPane.
146 *
147 * @return the value of the layeredPane property.
148 * @see #setLayeredPane
149 */
150 JLayeredPane getLayeredPane();
151
152
153 /**
154 * The glassPane is always the first child of the rootPane
155 * and the rootPanes layout manager ensures that it's always
156 * as big as the rootPane. By default it's transparent and
157 * not visible. It can be used to temporarily grab all keyboard
158 * and mouse input by adding listeners and then making it visible.
159 * by default it's not visible.
160 * <p>
161 * The glassPane may not be null.
162 * <p>
163 * Generally implemented with
164 * <code>getRootPane().setGlassPane(glassPane);</code>
165 *
166 * @see #getGlassPane
167 * @see JRootPane#setGlassPane
168 */
169 void setGlassPane(Component glassPane);
170
171
172 /**
173 * Returns the glassPane.
174 *
175 * @return the value of the glassPane property.
176 * @see #setGlassPane
177 */
178 Component getGlassPane();
179
180 }