Using Swing Components |
In general, you don't directly create aJRootPane
object. Instead, you get aJRootPane
(whether you want it or not!) when you instantiateJInternalFrame
or one of the top-level Swing containers --JApplet
,JDialog
,JFrame
, andJWindow
.The section [PENDING] tells you the basics of using root panes -- getting the content pane, setting its layout manager, and adding Swing components to it. This section tells you more about root panes, including the components that make up a root pane and how you can use them. Another place to get information about root panes is The Swing Connection, especially the article Understanding Containers.
[PENDING: Insert figure that shows front and side views of a JRootPane in a JFrame.]
As the preceding figure shows, a root pane has four parts:
- The glass pane
- Hidden, by default. If you make the glass pane visible, then it's like a sheet of glass over all the other parts of the root pane. It's completely transparent (unless you implement the glass pane's
paint
method so that it does something) and it intercepts input events for the root pane. In the next section, you'll see an example of using a glass pane.- The layered pane
- Serves to position its contents, which consist of the content pane and the optional menu bar. Can also hold other components in a specified Z order. For information, see How to Use Layered Panes.
- The content pane
- The container of the root pane's visible components, excluding the menu bar. For information on using the content pane, see Setting Up the Top-Level Container and [PENDING: link to what was previously in "generalCompRules.html#rootpane"--Building a Swing GUI. [PENDING: consolidate, clarify content pane coverage.]
- The optional menu bar
- The home for the root pane's container's menus. If the container has a menu bar, you generally use the container's
setMenuBar
orsetJMenuBar
method to put the menu bar in the appropriate place. For more information on using menus and menu bars, see How to Use Menus.The Glass Pane
The glass pane is useful when you want to be able to catch events or draw over an area that already contains one or more components. For example, you can deactivate mouse events for a multi-component region by having the glass pane intercept the events. Or you can display a wait cursor over an entire root pane using the glass pane.Here's a picture of an application that demonstrates glass pane features. It contains a check box that lets you set whether the glass pane is "visible" -- whether it can get events and paint itself onscreen. When the glass pane is visible, it blocks all input events from reaching the components in the content pane. It also draws a red dot in the place where it last detected a mouse-pressed event.
Try this:
- Compile and run the application. The source file is
GlassPaneDemo.java
.
See Getting Started with Swing if you need help.- Click Button 1.
The button's appearance changes to show that it's been clicked.- Click the check box so that the glass pane becomes "visible," and then click Button 1 again.
The button does not detect the mouse-pressed event because the glass pane intercepts it. When the glass pane detects the event, it beeps and draws a red circle where you clicked.- Click the check box again so that the glass pane is hidden.
When the root pane detects an event over the check box, it forwards it to the check box. Otherwise, the check box would not respond to clicks.
The following code from
GlassPaneDemo.java
shows and hides the glass pane. This program happens to create its own glass pane, setting it using theJFrame
setGlassPane
method. However, if a glass pane doesn't do any drawing, the program might simply attach listeners to the default glass pane, as returned bygetGlassPane
....//where GlassPaneDemo's UI is initialized: JCheckBox changeButton = new JCheckBox("Glass pane \"visible\""); changeButton.setSelected(false); changeButton.addItemListener(new ItemListener() { public void itemStateChanged(ItemEvent e) { myGlassPane.setVisible(e.getStateChange() == ItemEvent.SELECTED); } });The next code snippet implements the mouse-event handling for the glass pane. If a mouse event occurs over the check box or menu bar, then the glass pane redispatches the event so that the check box or menu component receives it. So that the check box and menu behave properly, they also receive all drag events that started with a press in the button or menu bar. [PENDING: Does that matter for the menu? Should I also track drags that start within the popped up menu?]
Here is the code that implements the drawing for the glass pane:...//In the implementation of the glass pane's mouse listener: public void mouseMoved(MouseEvent e) { redispatchMouseEvent(e, false); } .../* The mouseDragged, mouseClicked, mouseEntered, * mouseExited, and mousePressed methods have the same * implementation as mouseMoved*/... public void mouseReleased(MouseEvent e) { redispatchMouseEvent(e, true); inDrag = false; } private void redispatchMouseEvent(MouseEvent e, boolean repaint) { boolean inButton = false; boolean inMenuBar = false; Point glassPanePoint = e.getPoint(); Component component = null; Container container = contentPane; Point containerPoint = SwingUtilities.convertPoint( glassPane, glassPanePoint, contentPane); int eventID = e.getID(); if (containerPoint.y < 0) { inMenuBar = true; //...set container and containerPoint accordingly... testForDrag(eventID); } component = SwingUtilities.getDeepestComponentAt( container, containerPoint.x, containerPoint.y); if (component.equals(liveButton)) { inButton = true; testForDrag(eventID); } if (inMenuBar || inButton || inDrag) { ...//Redispatch the event to component... } if (repaint) { toolkit.beep(); glassPane.setPoint(glassPanePoint); glassPane.repaint(); } } private void testForDrag(int eventID) { if (eventID == MouseEvent.MOUSE_PRESSED) { inDrag = true; } }...//where GlassPaneDemo's UI is initialized: myGlassPane = new MyGlassPane(...); frame.setGlassPane(myGlassPane); ... /** * We have to provide our own glass pane so that it can paint. */ class MyGlassPane extends JComponent { Point point = null; public void paint(Graphics g) { if (point != null) { g.setColor(Color.red); g.fillOval(point.x - 10, point.y - 10, 20, 20); } } ... }The Root Pane API
The tables that follow list the API for using root panes, glass panes, and content panes. For more information on using content panes, go [PENDING: where?]. Here are the tables in this section:The API for using other parts of the root pane is described elsewhere:
Using a Root Pane Method Purpose JRootPane getRootPane()
(inJApplet
,JDialog
,JFrame
,JInternalFrame
, andJWindow
)Get the root pane of the applet, dialog, frame, internal frame, or window. JRootPane SwingUtilities.getRootPane(Component)
If the component contains a root pane, returns that root pane. Otherwise, returns the root pane (if any) that contains the component. JRootPane getRootPane()
(inJComponent
)Invokes the SwingUtilities
getRootPane
method on theJComponent
.void setDefaultButton(JButton)
JButton getDefaultButton()Set or get which button (if any) is the default button in the root pane. A look-and-feel-specific action, such as pressing Enter, causes the button's action to be performed.
Setting or Getting the Glass Pane Method Purpose setGlassPane(Component)
Component getGlassPane()
(inJApplet
,JDialog
,JFrame
,JInternalFrame
,JRootPane
, andJWindow
)Sets or gets the glass pane.
Using the Content Pane Method Purpose setContentPane(Container)
Container getContentPane()
(inJApplet
,JDialog
,JFrame
,JInternalFrame
,JRootPane
, andJWindow
)Set or get the content pane. Examples that Use Root Panes
Every Swing program uses a root pane. The examples in the following list illustrate some of the common or interesting uses. Also see these:
- Examples that Use Layered Panes
- Examples that Use Menus
- Examples that Use Frames (for examples of using content panes)
Example Where Described Notes GlassPaneDemo.java
This page Uses a glass pane. Redispatches events.
Using Swing Components |