| JavaTM 2 Platform Std. Ed. v1.6.0
javax.swing
Class JRootPane
java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JRootPane
- All Implemented Interfaces:
- ImageObserver, MenuContainer, Serializable, Accessible
public class JRootPane - extends JComponent
- implements Accessible
A lightweight container used behind the scenes by
JFrame, JDialog, JWindow,
JApplet, and JInternalFrame.
For task-oriented information on functionality provided by root panes
see How to Use Root Panes,
a section in The Java Tutorial.
The following image shows the relationships between
the classes that use root panes.

The "heavyweight" components (those that delegate to a peer, or native
component on the host system) are shown with a darker, heavier box. The four
heavyweight JFC/Swing containers (JFrame, JDialog,
JWindow, and JApplet) are
shown in relation to the AWT classes they extend.
These four components are the
only heavyweight containers in the Swing library. The lightweight container
JInternalFrame is also shown.
All five of these JFC/Swing containers implement the
RootPaneContainer interface,
and they all delegate their operations to a
JRootPane (shown with a little "handle" on top).
Note: The JComponent method getRootPane
can be used to obtain the JRootPane that contains
a given component.
The diagram at right shows the structure of a JRootPane.
A JRootpane is made up of a glassPane,
an optional menuBar, and a contentPane.
(The JLayeredPane manages the menuBar
and the contentPane.)
The glassPane sits over the top of everything,
where it is in a position to intercept mouse movements.
Since the glassPane (like the contentPane)
can be an arbitrary component, it is also possible to set up the
glassPane for drawing. Lines and images on the
glassPane can then range
over the frames underneath without being limited by their boundaries.
Although the menuBar component is optional,
the layeredPane, contentPane,
and glassPane always exist.
Attempting to set them to null generates an exception.
To add components to the JRootPane (other than the
optional menu bar), you add the object to the contentPane
of the JRootPane, like this:
rootPane.getContentPane().add(child);
The same principle holds true for setting layout managers, removing
components, listing children, etc. All these methods are invoked on
the contentPane instead of on the JRootPane.
Note: The default layout manager for the contentPane is
a BorderLayout manager. However, the JRootPane
uses a custom LayoutManager.
So, when you want to change the layout manager for the components you added
to a JRootPane, be sure to use code like this:
rootPane.getContentPane().setLayout(new BoxLayout());
If a JMenuBar component is set on the JRootPane,
it is positioned along the upper edge of the frame.
The contentPane is adjusted in location and size to
fill the remaining area.
(The JMenuBar and the contentPane are added to the
layeredPane component at the
JLayeredPane.FRAME_CONTENT_LAYER layer.)
The layeredPane is the parent of all children in the
JRootPane -- both as the direct parent of the menu and
the grandparent of all components added to the contentPane.
It is an instance of JLayeredPane,
which provides the ability to add components at several layers.
This capability is very useful when working with menu popups,
dialog boxes, and dragging -- situations in which you need to place
a component on top of all other components in the pane.
The glassPane sits on top of all other components in the
JRootPane.
That provides a convenient place to draw above all other components,
and makes it possible to intercept mouse events,
which is useful both for dragging and for drawing.
Developers can use setVisible on the glassPane
to control when the glassPane displays over the other children.
By default the glassPane is not visible.
The custom LayoutManager used by JRootPane
ensures that:
- The
glassPane fills the entire viewable
area of the JRootPane (bounds - insets).
- The
layeredPane fills the entire viewable area of the
JRootPane. (bounds - insets)
- The
menuBar is positioned at the upper edge of the
layeredPane.
- The
contentPane fills the entire viewable area,
minus the menuBar, if present.
Any other views in the JRootPane view hierarchy are ignored.
If you replace the LayoutManager of the JRootPane,
you are responsible for managing all of these views.
So ordinarily you will want to be sure that you
change the layout manager for the contentPane rather than
for the JRootPane itself!
The painting architecture of Swing requires an opaque
JComponent
to exist in the containment hieararchy above all other components. This is
typically provided by way of the content pane. If you replace the content
pane, it is recommended that you make the content pane opaque
by way of setOpaque(true). Additionally, if the content pane
overrides paintComponent, it
will need to completely fill in the background in an opaque color in
paintComponent.
Warning: Swing is not thread safe. For more
information see Swing's Threading
Policy.
Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing. As of 1.4, support for long term storage
of all JavaBeansTM
has been added to the java.beans package.
Please see XMLEncoder.
- See Also:
JLayeredPane,
JMenuBar,
JWindow,
JFrame,
JDialog,
JApplet,
JInternalFrame,
JComponent,
BoxLayout,
Mixing Heavy and Light Components
|
Nested Class Summary |
protected class |
JRootPane.AccessibleJRootPane
This class implements accessibility support for the
JRootPane class. |
protected class |
JRootPane.RootLayout
A custom layout manager that is responsible for the layout of
layeredPane, glassPane, and menuBar. |
|
Field Summary |
static int |
COLOR_CHOOSER_DIALOG
Constant used for the windowDecorationStyle property. |
protected Container |
contentPane
The content pane. |
protected JButton |
defaultButton
The button that gets activated when the pane has the focus and
a UI-specific action like pressing the Enter key occurs. |
protected javax.swing.JRootPane.DefaultAction |
defaultPressAction
Deprecated. As of Java 2 platform v1.3. |
protected javax.swing.JRootPane.DefaultAction |
defaultReleaseAction
Deprecated. As of Java 2 platform v1.3. |
static int |
ERROR_DIALOG
Constant used for the windowDecorationStyle property. |
static int |
FILE_CHOOSER_DIALOG
Constant used for the windowDecorationStyle property. |
static int |
FRAME
Constant used for the windowDecorationStyle property. |
protected Component |
glassPane
The glass pane that overlays the menu bar and content pane,
so it can intercept mouse movements and such. |
static int |
INFORMATION_DIALOG
Constant used for the windowDecorationStyle property. |
protected JLayeredPane |
layeredPane
The layered pane that manages the menu bar and content pane. |
protected JMenuBar |
menuBar
The menu bar. |
static int |
NONE
Constant used for the windowDecorationStyle property. |
static int |
PLAIN_DIALOG
Constant used for the windowDecorationStyle property. |
static int |
QUESTION_DIALOG
Constant used for the windowDecorationStyle property. |
static int |
WARNING_DIALOG
Constant used for the windowDecorationStyle property. |
|
Constructor Summary |
JRootPane()
Creates a JRootPane, setting up its
glassPane, layeredPane,
and contentPane. |
| Methods inherited from class javax.swing.JComponent |
addAncestorListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update |
| Methods inherited from class java.awt.Container |
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree |
| Methods inherited from class java.awt.Component |
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle |
NONE
public static final int NONE
- Constant used for the windowDecorationStyle property. Indicates that
the
JRootPane should not provide any sort of
Window decorations.
- Since:
- 1.4
- See Also:
- Constant Field Values
FRAME
public static final int FRAME
- Constant used for the windowDecorationStyle property. Indicates that
the
JRootPane should provide decorations appropriate for
a Frame.
- Since:
- 1.4
- See Also:
- Constant Field Values
PLAIN_DIALOG
public static final int PLAIN_DIALOG
- Constant used for the windowDecorationStyle property. Indicates that
the
JRootPane should provide decorations appropriate for
a Dialog.
- Since:
- 1.4
- See Also:
- Constant Field Values
INFORMATION_DIALOG
public static final int INFORMATION_DIALOG
- Constant used for the windowDecorationStyle property. Indicates that
the
JRootPane should provide decorations appropriate for
a Dialog used to display an informational message.
- Since:
- 1.4
- See Also:
- Constant Field Values
ERROR_DIALOG
public static final int ERROR_DIALOG
- Constant used for the windowDecorationStyle property. Indicates that
the
JRootPane should provide decorations appropriate for
a Dialog used to display an error message.
- Since:
- 1.4
- See Also:
- Constant Field Values
COLOR_CHOOSER_DIALOG
public static final int COLOR_CHOOSER_DIALOG
- Constant used for the windowDecorationStyle property. Indicates that
the
JRootPane should provide decorations appropriate for
a Dialog used to display a JColorChooser.
- Since:
- 1.4
- See Also:
- Constant Field Values
FILE_CHOOSER_DIALOG
public static final int FILE_CHOOSER_DIALOG
- Constant used for the windowDecorationStyle property. Indicates that
the
JRootPane should provide decorations appropriate for
a Dialog used to display a JFileChooser.
- Since:
- 1.4
- See Also:
- Constant Field Values
QUESTION_DIALOG
public static final int QUESTION_DIALOG
- Constant used for the windowDecorationStyle property. Indicates that
the
JRootPane should provide decorations appropriate for
a Dialog used to present a question to the user.
- Since:
- 1.4
- See Also:
- Constant Field Values
WARNING_DIALOG
public static final int WARNING_DIALOG
- Constant used for the windowDecorationStyle property. Indicates that
the
JRootPane should provide decorations appropriate for
a Dialog used to display a warning message.
- Since:
- 1.4
- See Also:
- Constant Field Values
menuBar
protected JMenuBar menuBar
- The menu bar.
contentPane
protected Container contentPane
- The content pane.
layeredPane
protected JLayeredPane layeredPane
- The layered pane that manages the menu bar and content pane.
glassPane
protected Component glassPane
- The glass pane that overlays the menu bar and content pane,
so it can intercept mouse movements and such.
defaultButton
protected JButton defaultButton
- The button that gets activated when the pane has the focus and
a UI-specific action like pressing the Enter key occurs.
defaultPressAction
@Deprecated
protected javax.swing.JRootPane.DefaultAction defaultPressAction
- Deprecated. As of Java 2 platform v1.3.
- As of Java 2 platform v1.3 this unusable field is no longer used.
To override the default button you should replace the
Action
in the JRootPane's ActionMap. Please refer to
the key bindings specification for further details.
- See Also:
defaultButton
defaultReleaseAction
@Deprecated
protected javax.swing.JRootPane.DefaultAction defaultReleaseAction
- Deprecated. As of Java 2 platform v1.3.
- As of Java 2 platform v1.3 this unusable field is no longer used.
To override the default button you should replace the
Action
in the JRootPane's ActionMap. Please refer to
the key bindings specification for further details.
- See Also:
defaultButton
JRootPane
public JRootPane()
- Creates a
JRootPane, setting up its
glassPane, layeredPane,
and contentPane.
setDoubleBuffered
public void setDoubleBuffered(boolean aFlag)
- Sets whether this component should use a buffer to paint.
If set to true, all the drawing from this component will be done
in an offscreen painting buffer. The offscreen painting buffer will
the be copied onto the screen.
If a
Component is buffered and one of its ancestor
is also buffered, the ancestor buffer will be used.
- Overrides:
setDoubleBuffered in class JComponent
- Parameters:
aFlag - if true, set this component to be double buffered- Since:
- 1.6
getWindowDecorationStyle
public int getWindowDecorationStyle()
- Returns a constant identifying the type of Window decorations the
JRootPane is providing.
- Returns:
- One of
NONE, FRAME,
PLAIN_DIALOG, INFORMATION_DIALOG,
ERROR_DIALOG, COLOR_CHOOSER_DIALOG,
FILE_CHOOSER_DIALOG, QUESTION_DIALOG or
WARNING_DIALOG. - Since:
- 1.4
- See Also:
setWindowDecorationStyle(int)
setWindowDecorationStyle
public void setWindowDecorationStyle(int windowDecorationStyle)
- Sets the type of Window decorations (such as borders, widgets for
closing a Window, title ...) the
JRootPane should
provide. The default is to provide no Window decorations
(NONE).
This is only a hint, and some look and feels may not support
this.
This is a bound property.
- Parameters:
windowDecorationStyle - Constant identifying Window decorations
to provide.
- Throws:
IllegalArgumentException - if style is
not one of: NONE, FRAME,
PLAIN_DIALOG, INFORMATION_DIALOG,
ERROR_DIALOG, COLOR_CHOOSER_DIALOG,
FILE_CHOOSER_DIALOG, QUESTION_DIALOG, or
WARNING_DIALOG.- Since:
- 1.4
- See Also:
JDialog.setDefaultLookAndFeelDecorated(boolean),
JFrame.setDefaultLookAndFeelDecorated(boolean),
LookAndFeel.getSupportsWindowDecorations()
getUI
public RootPaneUI getUI()
- Returns the L&F object that renders this component.
- Returns:
LabelUI object- Since:
- 1.3
setUI
public void setUI(RootPaneUI ui)
- Sets the L&F object that renders this component.
- Parameters:
ui - the LabelUI L&F object- Since:
- 1.3
- See Also:
UIDefaults.getUI(javax.swing.JComponent)
updateUI
public void updateUI()
- Resets the UI property to a value from the current look and feel.
- Overrides:
updateUI in class JComponent
- See Also:
JComponent.updateUI()
getUIClassID
public String getUIClassID()
- Returns a string that specifies the name of the L&F class
that renders this component.
- Overrides:
getUIClassID in class JComponent
- Returns:
- the string "RootPaneUI"
- See Also:
JComponent.getUIClassID(),
UIDefaults.getUI(javax.swing.JComponent)
createLayeredPane
protected JLayeredPane createLayeredPane()
- Called by the constructor methods to create the default
layeredPane.
Bt default it creates a new JLayeredPane.
- Returns:
- the default
layeredPane
createContentPane
protected Container createContentPane()
- Called by the constructor methods to create the default
contentPane.
By default this method creates a new JComponent add sets a
BorderLayout as its LayoutManager.
- Returns:
- the default
contentPane
createGlassPane
protected Component createGlassPane()
- Called by the constructor methods to create the default
glassPane.
By default this method creates a new JComponent
with visibility set to false.
- Returns:
- the default
glassPane
createRootLayout
protected LayoutManager createRootLayout()
- Called by the constructor methods to create the default
layoutManager.
- Returns:
- the default
layoutManager.
setJMenuBar
public void setJMenuBar(JMenuBar menu)
- Adds or changes the menu bar used in the layered pane.
- Parameters:
menu - the JMenuBar to add
setMenuBar
@Deprecated
public void setMenuBar(JMenuBar menu)
- Deprecated. As of Swing version 1.0.3
replaced by
setJMenuBar(JMenuBar menu).
- Specifies the menu bar value.
- Parameters:
menu - the JMenuBar to add.
getJMenuBar
public JMenuBar getJMenuBar()
- Returns the menu bar from the layered pane.
- Returns:
- the
JMenuBar used in the pane
getMenuBar
@Deprecated
public JMenuBar getMenuBar()
- Deprecated. As of Swing version 1.0.3
replaced by
getJMenuBar().
- Returns the menu bar value.
- Returns:
- the
JMenuBar used in the pane
setContentPane
public void setContentPane(Container content)
- Sets the content pane -- the container that holds the components
parented by the root pane.
Swing's painting architecture requires an opaque JComponent
in the containment hiearchy. This is typically provided by the
content pane. If you replace the content pane it is recommended you
replace it with an opaque JComponent.
- Parameters:
content - the Container to use for component-contents
- Throws:
IllegalComponentStateException - (a runtime
exception) if the content pane parameter is null
getContentPane
public Container getContentPane()
- Returns the content pane -- the container that holds the components
parented by the root pane.
- Returns:
- the
Container that holds the component-contents
setLayeredPane
public void setLayeredPane(JLayeredPane layered)
- Sets the layered pane for the root pane. The layered pane
typically holds a content pane and an optional
JMenuBar.
- Parameters:
layered - the JLayeredPane to use
- Throws:
IllegalComponentStateException - (a runtime
exception) if the layered pane parameter is null
getLayeredPane
public JLayeredPane getLayeredPane()
- Gets the layered pane used by the root pane. The layered pane
typically holds a content pane and an optional
JMenuBar.
- Returns:
- the
JLayeredPane currently in use
setGlassPane
public void setGlassPane(Component glass)
- Sets a specified
Component to be the glass pane for this
root pane. The glass pane should normally be a lightweight,
transparent component, because it will be made visible when
ever the root pane needs to grab input events.
The new glass pane's visibility is changed to match that of
the current glass pane. An implication of this is that care
must be taken when you want to replace the glass pane and
make it visible. Either of the following will work:
root.setGlassPane(newGlassPane);
newGlassPane.setVisible(true);
or:
root.getGlassPane().setVisible(true);
root.setGlassPane(newGlassPane);
- Parameters:
glass - the Component to use as the glass pane
for this JRootPane
- Throws:
NullPointerException - if the glass parameter is
null
getGlassPane
public Component getGlassPane()
- Returns the current glass pane for this
JRootPane.
- Returns:
- the current glass pane
- See Also:
setGlassPane(java.awt.Component)
isValidateRoot
public boolean isValidateRoot()
- If a descendant of this
JRootPane calls
revalidate, validate from here on down.
Deferred requests to layout a component and its descendents again.
For example, calls to revalidate, are pushed upwards to
either a JRootPane or a JScrollPane
because both classes override isValidateRoot to return true.
- Overrides:
isValidateRoot in class JComponent
- Returns:
- true
- See Also:
JComponent.isValidateRoot()
isOptimizedDrawingEnabled
public boolean isOptimizedDrawingEnabled()
- The
glassPane and contentPane
have the same bounds, which means JRootPane
does not tiles its children and this should return false.
On the other hand, the glassPane
is normally not visible, and so this can return true if the
glassPane isn't visible. Therefore, the
return value here depends upon the visiblity of the
glassPane.
- Overrides:
isOptimizedDrawingEnabled in class JComponent
- Returns:
- true if this component's children don't overlap
addNotify
public void addNotify()
- Register oursel
|