How to Use Internal Frames

How to Use Internal Frames

With the JInternalFrame ^[73] class, you can display a JFrame -like window within another window. Usually, you add internal frames to a desktop pane, which in turn might be used as the content pane of a JFrame . The desktop pane is an instance of JDesktopPane , ^[74] which is a subclass of JLayeredPane ^[75] that has added API for managing multiple overlapping internal frames.

^[73] InternalFrame API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JInternalFrame.html.

^[74] JDesktopPane API documentation is on the CD and online at: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JDesktopPane.html.

^[75] Layered panes are discussed in How to Use Layered Panes (page 258).

Consider carefully whether to base your program's GUI around frames or internal frames. Switching from internal frames to frames or vice versa isn't necessarily a simple task. By experimenting, you can get an idea of the tradeoffs involved in choosing one over the other.

Figure 25 shows an application that has two internal frames (one of which is iconified ) inside a regular frame.

Figure 25. The InternalFrameDemo application.

Try This:

1. 

   Run InternalFrameDemo using Java Web Start or compile and run the example yourself. ^[76]

   ^[76] To run InternalFrameDemo using Java Web Start, click the InternalFrameDemo link on the RunExamples/ components .html page on the CD. You can find the source files here: JavaTutorial/uiswing/components/example-1dot4/index.html#InternalFrameDemo .

2. Create new internal frames using the Create item in the Document menu. Each internal frame comes up 30 pixels lower and to the right of where the previous internal frame first appeared. This functionality is implemented in the MyInternalFrame class, which is the custom subclass of JInternalFrame .

The following code, taken from InternalFrameDemo.java , creates the desktop and internal frames in the previous example.

 ...  //In the constructor of InternalFrameDemo, a JFrame subclass:  desktop = new JDesktopPane();     createFrame(); //Create first window     setContentPane(desktop);     ...     //Make dragging faster:     //desktop.putClientProperty("JDesktopPane.dragMode", //pre-1.3 code                                 "outline");     desktop.setDragMode(JDesktopPane.OUTLINE_DRAG_MODE); //1.3+ code ... protected void createFrame() {     MyInternalFrame frame = new MyInternalFrame();     frame.setVisible(true); //necessary as of 1.3     desktop.add(frame);     try {         frame.setSelected(true);     } catch (java.beans.PropertyVetoException e) {} }  ...//In the constructor of MyInternalFrame, a JInternalFrame subclass:  static int openFrameCount = 0; static final int xOffset = 30, yOffset = 30; public MyInternalFrame() {     super("Document #" + (++openFrameCount),           true, //resizable           true, //closable           true, //maximizable           true);//iconifiable  //...Create the GUI and put it in the window...   //...Then set the window size or call pack...  ...     //Set the window's location.     setLocation(xOffset*openFrameCount, yOffset*openFrameCount); } 

Internal Frames versus Regular Frames

The code for using internal frames is similar in many ways to that for using regular Swing frames. Because internal frames have root panes, setting up the GUI for a JInternalFrame is very similar to setting up the GUI for a JFrame . JInternalFrame also provides other API, such as pack , that makes it similar to JFrame .

Note: Just as for a regular frame, you must invoke setVisible(true) or show() on an internal frame to display it. In early versions of the Java 2 platform (such as 1.2.2), this code has no effect because the internal frame is visible by default. However, starting in the v1.3 release, the internal frame doesn't appear until you explicitly make it visible.

That internal frames aren't windows or top-level containers makes them different from frames. For example, you must add an internal frame to a container (usually a JDesktopPane ); an internal frame can't be the root of a containment hierarchy. Also, internal frames don't generate window events. Instead, the user actions that cause a frame to fire window events cause an internal frame to fire internal frame events.

Because internal frames are implemented with platform-independent code, they add functionality that frames can't give you. For example, internal frames give you more control over their state and capabilities than frames do. You can programatically iconify or maximize an internal frame. You can also specify what icon goes in the internal frame's title bar. You can even specify whether the internal frame has the window decorations to support resizing, iconifying, closing, and maximizing.

Another feature is that internal frames are designed to work within desktop panes. The JInternalFrame API contains methods , such as moveToFront , that work only if the internal frame's container is a layered pane such as a JDesktopPane .

Rules of Using Internal Frames

If you've built any programs using JFrame and the other Swing components, you already know a lot about how to use them. The following list summarizes the rules for using internal frames. For additional information, see How to Make Frames (Main Windows) (page 236) earlier in this chapter and The JComponent Class (page 53) in Chapter 3.

You must set the size of the internal frame.

If you don't, it will have zero size and thus never be visible. You can set the size using setSize , pack , or setBounds .

As a rule, you should set the location of the internal frame.

If you don't, it will come up at 0,0 (the upper left of its container). You can use set-Location or setBounds to specify the upper left point of the internal frame, relative to its container.

To add components to an internal frame, add them to its content pane.

This is exactly like the JFrame situation. See Adding Components to the Content Pane (page 48) in Chapter 3 for details.

Dialogs that are internal frames should be implemented using JOptionPane or JInternalFrame , not JDialog .

To create a simple dialog, you can use the JOptionPane showInternal Xxx Dialog methods, as described in How to Make Dialogs (page 187).

You must add an internal frame to a container.

If you don't add the internal frame to a container (usually a JDesktopPane ), the internal frame won't appear.

You need to call show or setVisible on internal frames.

Beginning with the v1.3 release, internal frames are invisible by default. You must invoke setVisible(true) or show() to make them visible.

Internal frames fire internal frame events, not window events.

Handling internal frame events is almost identical to handling window events. See How to Write an Internal Frame Listener (page 670) in Chapter 10 for more information.

Performance Tip: Because dragging internal frames can be slow, Swing 1.1.1 and the Java 2 platform, v1.2.2, added a way to make it zippy: outline dragging. With outline dragging, only the outline of the internal frame is painted at the current mouse position while the window is being dragged. The internal frame's innards are not repainted at a new position until the dragging stops. The default, slow behavior is to reposition and repaint the entire internal frame continuously while it's being moved.

In releases before v1.3, you can specify outline dragging by setting a client property of the desktop pane, like this:

 desktop.putClientProperty("JDesktopPane.dragMode", "outline"); 

The code has no effect in JFC implementations before Swing 1.1.1 Beta 1. As of version 1.3, use the new JDesktopPane method setDragMode to specify outline dragging. For example:

 desktop.setDragMode(JDesktopPane.OUTLINE_DRAG_MODE); 

The Internal Frame API

Tables 32 through 37 list the commonly used JInternalFrame constructors and methods, as well as a few methods that JDesktopPane provides. Besides the API listed in this section, JInternalFrame inherits useful API from its superclasses: JComponent , Component , and Container . See The JComponent Class (page 53) in Chapter 3 for lists of methods from those classes.

Like JInternalFrame , JDesktopPane descends from JComponent and thus provides the methods described in The JComponent Class (page 53) in Chapter 3. Because JDesktopPane extends JLayeredPane , it also supports the methods described in The Layered Pane API (page 264) later in this chapter. Also consult the API documentation for JInternalFrame and JDesktopPane at:

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JInternalFrame.html

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JDesktopPane.html

Table 32. Creating the Internal Frame

Constructor or Method	Purpose
JInternalFrame() JInternalFrame(String) JInternalFrame(String, boolean) JInternalFrame(String, boolean, boolean) JInternalFrame(String, boolean, boolean, boolean) JInternalFrame(String, boolean, boolean, boolean, boolean)	Create a JInternalFrame instance. The first argument specifies the title (if any) to be displayed by the internal frame. The rest of the arguments specify whether the internal frame should contain decorations that allow the user to resize, close, maximize, and iconify the internal frame (specified in that order). The default value for each boolean argument is false, which means that the operation is not allowed.
static int showInternalConfirmDialog( Component, Object) static String showInternalInputDialog( Component, Object) static Object showInternalMessageDialog( Component, Object) static int showInternalOptionDialog( Component, Object, String, int, int, Icon, Object[], Object)	Create a JInternalFrame that simulates a dialog. See How to Make Dialogs (page 187) for details.

Table 33. Adding Components to the Internal Frame

Method	Purpose
void setContentPane(Container) Container getContentPane()	Set or get the internal frame's content pane, which generally contains all of the internal frame's GUI, with the exception of the menu bar and window decorations.
void setJMenuBar(JMenuBar) JMenuBar getJMenuBar()	Set or get the internal frame's menu bar. (Some very early Swing releases do not include this method.)

Table 34. Specifying the Internal Frame's Visibility, Size, and Location

Method	Purpose
void setVisible(boolean) ( in Component)	Make the internal frame visible (if true) or invisible (if false). Invoke setVisible(true) on each JInternalFrame before adding it to its container.
void pack() ( in JInternalFrame)	Size the internal frame so that its components are at their preferred sizes.
void setLocation(Point) void setLocation(int, int) ( in Component)	Set the position of the internal frame.
void setBounds(Rectangle) void setBounds(int, int, int, int) ( in Component)	Explicitly set the size and location of the internal frame.
void setSize(Dimension) void setSize(int, int) ( in Component)	Explicitly set the size of the internal frame.

Table 35. Performing Window Operations on the Internal Frame

Method	Purpose
void setDefaultCloseOperation(int) int getDefaultCloseOperation()	Set or get what the internal frame does when the user attempts to "close" the internal frame. The default value is HIDE_ON_CLOSE . Other possible values are DO_NOTHING_ON_CLOSE and DISPOSE_ON_CLOSE . See Responding to Window-Closing Events (page 240) for details.
void addInternalFrameListener( InternalFrameListener) void removeInternalFrameListener( InternalFrameListener)	Add or remove an internal frame listener ( JInternal-Frame 's equivalent of a window listener). See How to Use Internal Frames (page 245) for more information.
void moveToFront() void moveToBack()	If the internal frame's parent is a layered pane such as a desktop pane, move the internal frame to the front or back (respectively) of its layer.
void setClosed(boolean) boolean isClosed()	Set or get whether the internal frame is currently closed.
void setIcon(boolean) boolean isIcon()	Iconify or deiconify the internal frame, or determine whether it's currently iconified.
void setMaximum(boolean) boolean isMaximum()	Maximize or restore the internal frame, or determine whether it's maximized.
void setSelected(boolean) boolean isSelected()	Set or get whether the internal frame is the currently "selected" (activated) internal frame.

Table 36. Controlling Window Decorations and Capabilities

Method	Purpose
void setFrameIcon(Icon) Icon getFrameIcon()	Set or get the icon displayed in the title bar of the internal frame (usually in the top left corner).
void setClosable(boolean) boolean isClosable()	Set or get whether the user can close the internal frame.
void setIconifiable(boolean) boolean isIconifiable()	Set or get whether the internal frame can be iconified.
void setMaximizable(boolean) boolean isMaximizable()	Set or get whether the user can maximize this internal frame.
void setResizable(boolean) boolean isResizable()	Set or get whether the internal frame can be resized.
void setTitle(String) String getTitle()	Set or get the window title.

Table 37. Using the JDesktopPane API

Constructor or Method	Purpose
JDesktopPane()	Create a new instance of JDesktopPane .
JInternalFrame[] getAllFrames()	Return all JInternalFrame objects that the desktop contains.
JInternalFrame[] getAllFramesInLayer(int)	Return all JInternalFrame objects that the desktop contains that are in the specified layer. See How to Use Layered Panes (page 258) for information about layers .
void setDragMode(int) int getDragMode()	Set or get the drag mode used for internal frames in this desktop. The integer can be either JDesktopPane.LIVE_DRAG_MODE or JDesktopPane.OUTLINE_DRAG_MODE . The default for the Java look and feel is live-drag mode.

Examples That Use Internal Frames

The following examples use internal frames. Because internal frames are similar to regular frames, you should also look at Examples That Use Frames (page 244) earlier in this chapter.

Example	Where Described	Notes
MyInternalFrame	This section.	Implements an internal frame that appears at an offset to the previously created internal frame.
InternalFrameDemo	This section.	Lets you create internal frames (instances of MyInternalFrame ) that go into the application's JDesktopPane .
InternalFrameEventDemo	How to Write an Internal Frame Listener (page 670)	Demonstrates listening for internal frame events. Also demonstrates positioning internal frames within a desktop pane.