/*
* Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.swing;
import java.awt.Component;
import java.awt.Container;
/**
* This interface is implemented by components that have a single
* JRootPane child: JDialog, JFrame, JWindow, JApplet, JInternalFrame.
* The methods in this interface are just <i>covers</i> for the JRootPane
* properties, e.g. <code>getContentPane()</code> is generally implemented
* like this:<pre>
* public Container getContentPane() {
* return getRootPane().getContentPane();
* }
* </pre>
* This interface serves as a <i>marker</i> for Swing GUI builders
* that need to treat components like JFrame, that contain a
* single JRootPane, specially. For example in a GUI builder,
* dropping a component on a RootPaneContainer would be interpreted
* as <code>frame.getContentPane().add(child)</code>.
* <p>
* As a convenience, the standard classes that implement this interface
* (such as {@code JFrame}, {@code JDialog}, {@code JWindow}, {@code JApplet},
* and {@code JInternalFrame}) have their {@code add}, {@code remove},
* and {@code setLayout} methods overridden, so that they delegate calls
* to the corresponding methods of the {@code ContentPane}.
* For example, you can add a child component to a frame as follows:
* <pre>
* frame.add(child);
* </pre>
* instead of:
* <pre>
* frame.getContentPane().add(child);
* </pre>
* <p>
* The behavior of the <code>add</code> and
* <code>setLayout</code> methods for
* <code>JFrame</code>, <code>JDialog</code>, <code>JWindow</code>,
* <code>JApplet</code> and <code>JInternalFrame</code> is controlled by
* the <code>rootPaneCheckingEnabled</code> property. If this property is
* true (the default), then calls to these methods are
* forwarded to the <code>contentPane</code>; if false, these
* methods operate directly on the <code>RootPaneContainer</code>. This
* property is only intended for subclasses, and is therefore protected.
*
* @see JRootPane
* @see JFrame
* @see JDialog
* @see JWindow
* @see JApplet
* @see JInternalFrame
*
* @author Hans Muller
* @since 1.2
*/
public interface RootPaneContainer
{
/**
* Return this component's single JRootPane child. A conventional
* implementation of this interface will have all of the other
* methods indirect through this one. The rootPane has two
* children: the glassPane and the layeredPane.
*
* @return this components single JRootPane child.
* @see JRootPane
*/
JRootPane getRootPane();
/**
* The "contentPane" is the primary container for application
* specific components. Applications should add children to
* the contentPane, set its layout manager, and so on.
* <p>
* The contentPane may not be null.
* <p>
* Generally implemented with
* <code>getRootPane().setContentPane(contentPane);</code>
*
* @exception java.awt.IllegalComponentStateException (a runtime
* exception) if the content pane parameter is null
* @param contentPane the Container to use for the contents of this
* JRootPane
* @see JRootPane#getContentPane
* @see #getContentPane
*/
void setContentPane(Container contentPane);
/**
* Returns the contentPane.
*
* @return the value of the contentPane property.
* @see #setContentPane
*/
Container getContentPane();
/**
* A Container that manages the contentPane and in some cases a menu bar.
* The layeredPane can be used by descendants that want to add a child
* to the RootPaneContainer that isn't layout managed. For example
* an internal dialog or a drag and drop effect component.
* <p>
* The layeredPane may not be null.
* <p>
* Generally implemented with<pre>
* getRootPane().setLayeredPane(layeredPane);</pre>
*
* @param layeredPane the layered pane
* @exception java.awt.IllegalComponentStateException (a runtime
* exception) if the layered pane parameter is null
* @see #getLayeredPane
* @see JRootPane#getLayeredPane
*/
void setLayeredPane(JLayeredPane layeredPane);
/**
* Returns the layeredPane.
*
* @return the value of the layeredPane property.
* @see #setLayeredPane
*/
JLayeredPane getLayeredPane();
/**
* The glassPane is always the first child of the rootPane
* and the rootPanes layout manager ensures that it's always
* as big as the rootPane. By default it's transparent and
* not visible. It can be used to temporarily grab all keyboard
* and mouse input by adding listeners and then making it visible.
* by default it's not visible.
* <p>
* The glassPane may not be null.
* <p>
* Generally implemented with
* <code>getRootPane().setGlassPane(glassPane);</code>
*
* @param glassPane the glass pane
* @see #getGlassPane
* @see JRootPane#setGlassPane
*/
void setGlassPane(Component glassPane);
/**
* Returns the glassPane.
*
* @return the value of the glassPane property.
* @see #setGlassPane
*/
Component getGlassPane();
}