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()} 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)}. 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} and 63 * {@code setLayout} methods for 64 * {@code JFrame}, {@code JDialog}, {@code JWindow}, 65 * {@code JApplet} and {@code JInternalFrame} is controlled by 66 * the {@code rootPaneCheckingEnabled} property. If this property is 67 * true (the default), then calls to these methods are 68 * forwarded to the {@code contentPane}; if false, these 69 * methods operate directly on the {@code RootPaneContainer}. 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);} 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 * @param layeredPane the layered pane 137 * @exception java.awt.IllegalComponentStateException (a runtime 138 * exception) if the layered pane parameter is null 139 * @see #getLayeredPane 140 * @see JRootPane#getLayeredPane 141 */ 142 void setLayeredPane(JLayeredPane layeredPane); 143 144 145 /** 146 * Returns the layeredPane. 147 * 148 * @return the value of the layeredPane property. 149 * @see #setLayeredPane 150 */ 151 JLayeredPane getLayeredPane(); 152 153 154 /** 155 * The glassPane is always the first child of the rootPane 156 * and the rootPanes layout manager ensures that it's always 157 * as big as the rootPane. By default it's transparent and 158 * not visible. It can be used to temporarily grab all keyboard 159 * and mouse input by adding listeners and then making it visible. 160 * by default it's not visible. 161 * <p> 162 * The glassPane may not be null. 163 * <p> 164 * Generally implemented with 165 * {@code getRootPane().setGlassPane(glassPane);} 166 * 167 * @param glassPane the glass pane 168 * @see #getGlassPane 169 * @see JRootPane#setGlassPane 170 */ 171 void setGlassPane(Component glassPane); 172 173 174 /** 175 * Returns the glassPane. 176 * 177 * @return the value of the glassPane property. 178 * @see #setGlassPane 179 */ 180 Component getGlassPane(); 181 182 }