How to Use Internal Frames

With the JInternalFrame class, you can display a JFrame-like window within another window. To create an internal frame that looks like a simple dialog, you can use the JOptionPane showInternalXxxDialog methods, as discussed in How to Make Dialogs.
Usually, you display internal frames within a JDesktopPane. JDesktopPane is a subclass of JLayeredPane that has added API for managing multiple overlapping internal frames. Generally, you put the desktop pane into the content pane of a JFrame. For information about using the API that JDesktopPane inherits from JLayeredPane, see How to Use Layered Panes.
Here's a picture of an application that has two internal frames inside a regular frame.
[PENDING: Update the screen shot to reflect the final example.]
As the figure shows, the internal frames use the window decorations for the Metal look and feel. However, the window that contains them has the decorations for the native look and feel (in this case, Motif).

Try this:

Compile and run the application. The source files are InternalFrameDemo.java and MyInternalFrame.java.
See Getting Started with Swing if you need help.
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 the place 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(); //a specialized layered pane
    createFrame(); //Create first window
    setContentPane(desktop);
...
protected void createFrame() {
    MyInternalFrame frame = new MyInternalFrame();
    desktop.add(frame);
    try {
        frame.setSelected(true);
    } catch (java.beans.PropertyVetoException e2) {}
}

...//In the constructor of MyInternalFrame, a JInternalFrame subclass:
static int openFrameCount = 0;
static final int xOffset = 30, yOffset = 30;

public MyInternalFrame() {
    super("Internal Frame #" + (++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 vs. Regular Frames

The code for using internal frames is similar in many ways to the code 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.
Because internal frames aren't windows, however, they're different from frames in some ways. For example, you must add an internal frame to a container (usually a JDesktopPane). And internal frames don't generate window events; instead, the user actions that would 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 some features that frames can't give you. One such feature is that 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 layered panes. The JInternalFrame API contains methods such as moveToFront that work only if the internal frame's container is a layered pane.

Rules of Using Internal Frames

If you've built any programs using JFrame and the other Swing components, then you already know a lot about how to use internal frames. The following list summarizes the rules for using internal frames. For additional information, see [PENDING: the frame add/show discussion] and [PENDING: the JComponent discussion].

You must set the size of the internal frame.
If you don't set the size of the internal frame, it will have zero size and thus never be visible. You can set the size using one of the following methods: setSize, pack, or setBounds.
As a rule, you should set the location of the internal frame.
If you don't set the location of the internal frame, it will come up at 0,0 (the upper left of its container). You can use the setLocation or setBounds method to specify the upper left point of the internal frame, relative to its container.
To add components to an internal frame, you add them to the internal frame's content pane.
This is exactly like the JFrame situation. See Adding Components to a Frame 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 showInternalXxxDialog methods, as described in How to Make Dialogs. Note that internal frame dialogs are not modal.
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 don't usually need to call show or setVisible on internal frames.
Like a button, an internal frame automatically is shown either when it's added to a visible container or when its previously invisible container is made 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 for more information.

Note: Due to a bug (#4128975), once an internal frame has appeared and then been hidden, the internal frame can't appear again. If you want to show the internal frame again, you must recreate it, as InternalFrameEventDemo.java does.

The Internal Frame API

The following tables list the commonly used JInternalFrame constructors and methods. The API for using internal frames falls into these categories:

Creating the internal frame
Adding components to the internal frame
Specifying the internal frame's size and location
Performing window operations on the internal frame
Controlling window decorations and capabilities
Using the JDesktopPane API

Besides the API listed below, JInternalFrame inherits useful API from JComponent, Container, and Component. JInternalFrame also provides methods for getting and setting additional objects in its root pane. See How to Use Root Panes for details.

Creating the Internal Frame
Constructor 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 allowing 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.
JOptionPane class methods:showInternalConfirmDialog showInternalInputDialog showInternalMessageDialog showInternalOptionDialog Create a JInternalFrame that simulates a dialog. See How to Make Dialogs for details.

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 setMenuBar(JMenuBar) JMenuBar getMenuBar() Set or get the internal frame's menu bar. Note that these method names contain no "J", unlike the equivalent JFrame methods. In the next Swing and JDK 1.2 releases, JInternalFrame will add setJMenuBar and getJMenuBar, which you should use instead of the existing methods.

Specifying the Internal Frame's Size and Location
Method Purpose
void pack() Size the internal frame so that its components are at their preferred sizes.
void setLocation(Point) void setLocation(int, int) Set the position of the internal frame. (Inherited from Component).
void setBounds(Rectangle) void setBounds(int, int, int, int) Explicitly set the size and location of the internal frame. (Inherited from Component).
void setSize(Dimension) void setSize(int, int) Explicitly set the size of the internal frame. (Inherited from Component).

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 [PENDING: discussion in How to Make Frames] for details.
void addInternalFrameListener( InternalFrameListener) void removeInternalFrameListener( InternalFrameListener) Add or remove an internal frame listener (JInternalFrame's equivalent of a window listener). See How to Write an Internal Frame Listener for more information.
void moveToFront() void moveToBack() If the internal frame's parent is a layered pane, moves 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.

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 setText(String) String getText() Set or get the window title.
void setWarningString(String) String getWarningString() Set or get any warning string displayed by the window.

Using the JDesktopPane API
Constructor or Method Purpose
JDesktopPane() Creates a new instance of JDesktopPane.
JInternalFrame[] getAllFrames() Returns all JInternalFrame objects that the desktop contains.
JInternalFrame[] getAllFramesInLayer(int) Returns all JInternalFrame objects that the desktop contains that are in the specified layer. See How to Use Layered Panes for information about layers.

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 JFrame.

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

Creating the Internal Frame
Constructor	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 allowing 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.
`JOptionPane` class methods:`showInternalConfirmDialog showInternalInputDialog showInternalMessageDialog showInternalOptionDialog`	Create a `JInternalFrame` that simulates a dialog. See How to Make Dialogs for details.

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 setMenuBar(JMenuBar) JMenuBar getMenuBar()`	Set or get the internal frame's menu bar. Note that these method names contain no "J", unlike the equivalent `JFrame` methods. In the next Swing and JDK 1.2 releases, `JInternalFrame` will add `setJMenuBar` and `getJMenuBar`, which you should use instead of the existing methods.

Specifying the Internal Frame's Size and Location
Method	Purpose
`void pack()`	Size the internal frame so that its components are at their preferred sizes.
`void setLocation(Point) void setLocation(int, int)`	Set the position of the internal frame. (Inherited from `Component`).
`void setBounds(Rectangle) void setBounds(int, int, int, int)`	Explicitly set the size and location of the internal frame. (Inherited from `Component`).
`void setSize(Dimension) void setSize(int, int)`	Explicitly set the size of the internal frame. (Inherited from `Component`).

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 [PENDING: discussion in How to Make Frames] for details.
`void addInternalFrameListener( InternalFrameListener) void removeInternalFrameListener( InternalFrameListener)`	Add or remove an internal frame listener (`JInternalFrame`'s equivalent of a window listener). See How to Write an Internal Frame Listener for more information.
`void moveToFront() void moveToBack()`	If the internal frame's parent is a layered pane, moves 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.

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 setText(String) String getText()`	Set or get the window title.
`void setWarningString(String) String getWarningString()`	Set or get any warning string displayed by the window.

Using the `JDesktopPane` API
Constructor or Method	Purpose
`JDesktopPane()`	Creates a new instance of `JDesktopPane`.
`JInternalFrame[] getAllFrames()`	Returns all `JInternalFrame` objects that the desktop contains.
`JInternalFrame[] getAllFramesInLayer(int)`	Returns all `JInternalFrame` objects that the desktop contains that are in the specified layer. See How to Use Layered Panes for information about layers.

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

Using the JFC/Swing Packages