10

Multiple Document Frame

Features of JCMDIPane and JCMDIFrame  Properties  Methods  Examples

---

10.1 Features of JCMDIPane and JCMDIFrame

The Multiple Document Interface (MDI) model is a common way of organizing and presenting information in windows-style environments. The MDI model makes it possible to arrange multiple child windows inside a parent window, such as multiple files in a text editor, or multiple charts in one frame. In effect, the parent window becomes the desktop within which the children operate. Before Swing, there was no way of building MDI applications using the Abstract Windowing Toolkit (AWT).

If you were limited to using raw Swing components, you would likely build your primary GUI application within a JFrame. The container used to hold a multiple-document interface is a JDesktopPane, which you would put into the content pane of your JFrame. Finally, you would add JInternalFrames as needed for your document windows.

The JClass Elements components JCMDIPane and JCMDIFrame augment the functionality of JDesktopPane and JInternalFrame respectively. Simply replace JDesktopPane with JCMDIPane, and JInternalFrame with JCMDIFrame, and your job is almost complete! The only other thing you need to do is to use the setMDIMenuBar() method to set individual menu bars on each of your internal frames. These menu bars will replace the default menu bar that you set on JCMDIPane.

JClass Elements's multiple document JCMDIPane interface component extends Swing's JDesktopPane view to provide the following standard MDI features:

• True maximization. Instead of keeping two menu bars when an internal pane is maximized, JCMDIPane optimizes screen real estate by placing menus on the desktop's menu bar. All necessary functionality is preserved.
• Automatically adds a localized Windows menu containing two sections.
• The upper section of the Windows menu allows you to select from one of three window tiling algorithms: Cascade, Tile Horizontally, or Tile Vertically.
• The upper section of the Windows menu also allows you to Minimize/Maximize the selected frame, or to (re)Arrange Icons of the minimized frames.
• The lower section of the Windows menu provides a list of the titles of the internal frames, giving the user the ability to switch focus to any internal frame by selecting its name from the menu.
• Adds unmaximize/close icons to the far right of the menu bar when one of the frames is maximized.

  
  
  

Figure 37 :  The differences between a JCMDIPane (lower image) and a JInternalFrame (upper image).

Public classes:

JCMDIPane - subclass of JDesktopPane
JCMDIFrame - subclass of JInternalFrame

JCMDIPane is API compatible with JDesktopPane, but the behavior differs in that it automatically generates a Windows menu on the first toolbar it finds in its ancestral hierarchy. This Windows menu has arrangement options Cascade, Tile Horizontally, Tile Vertically, and Arrange Icons, and a selectable list of all the existing internal frames. When frames are maximized the first child of an internal frame's content pane is reparented to a panel that is mapped on top of all the frames so that the maximized frame makes maximal use of the existing window real estate.

Default dragging and resizing behavior is done speedily by drawing wire frames.

JCMDIFrame, when calling getContentPane, returns an additional child that is the single child of the true content pane. This is done for easy reparenting purposes as well as for support routines that aid in the manipulation of this child.

Figure 38 :  A JFrame containing a JCMDIPane and multiple JCMDIFrames.

Figure 39 :  A maximized internal frame-the iconify and close buttons have moved to the menu bar.

Figure 40 :  One frame is maximized. The Iconify, Maximize, and Close buttons appear on the menu bar.

---

10.2 Properties

For a full listing of these components' properties, see Properties of JCMDIFrame and Properties of JCMDIPane, in Appendix A.

JCMDIFrame has the same properties as JInternalFrame.

Along with the properties inherited from JDesktopPane, there are two additional properties in JCMDIPane: frameManipulationStyle and considerIconsWhenTiling. Setting frameManipulationStyle allows you to control how a frame is painted when it is dragged within the desktop. The default style, JCMDIPane.DEFAULT, causes JCMDIPane to repaint the entire frame when dragging. The second style, called wireframe, causes JCMDIPane to repaint a rectangle that matches the size of the frame. The wireframe dragging style is used when frameManipulationStyle is set to JCMDIPane.WIREFRAME. The considerIconsWhenTiling property controls the way that windows are tiled (false means that windows will be tiled using the entire desktop area; true means that windows will not be tiled over any icons that appear on the desktop).

---

10.3 Methods

Methods of JCMDIFrame

getMDIMenuBar() setMDIMenuBar()	Gets or sets the menu bar associated with this frame. If the parent of this frame is a JCMDIPane, then this menu bar will become the containing frame's menu bar when this frame becomes active. setMDIMenuBar() takes a JMenuBar as a parameter.
getMDIToolBar() setMDIToolBar()	Gets or sets the toolbar associated with this frame. If the parent of this frame is a JCMDIPane, then this toolbar will become the containing frame's toolbar when this frame becomes active. setMDIToolBar() takes a JToolBar as a parameter.
getContentPane()	Overrides getContentPane() to provide a container one level removed so that the frame can be maximized by reparenting its children to a different parent.

Methods of JCMDIPane

getAllNonIconifiedFrames() getAllIconifiedFrames()	Returns all non-iconified/iconified JCMDIFrames currently displayed in the desktop.
getDragMode() setDragMode()	Sets the dragging style of the frames on the desktop. Because JCMDIPane uses its own Desktop Manager, it does not use the dragging implementation of JDesktopPane; instead, it uses the dragging implementation of frameManipulationStyle. However, setting this property actually sets the frameManipulationStyle to the equivalent style. Valid styles are: OUTLINE_DRAG_MODE - corresponds to WIREFRAME LIVE_DRAG_MODE - corresponds to DEFAULT
getFrameManipulationStyle() setFrameManipulationStyle()	Sets the frame manipulation style. Valid styles are: WIREFRAME - drags and resizes as a wire frame, DEFAULT - default style specified by the PLAF you are using. The default style causes JCMDIPane to paint the entire frame when dragging it.
setInitialLayout()	Allows the layout of the MDIFrame windows to be set before the MDIPane window has been displayed. This has no effect after the MDIPane has been displayed for the first time.
isMaximized() setMaximized()	Methods to manage the maximized pane.
getMDIMenuBar() setMDIMenuBar()	The parameterless version of getMDIMenuBar() returns the menu bar used if we have no internal frames, whereas a JInternalFrame parameter is used to return the menu bar used for the specified frame. If the frame is a JCMDIFrame with a non-null MDIMenuBar, then this is returned. Otherwise, the MDIMenuBar for the this pane is returned.   setMDIMenuBar() with a JMenuBar parameter sets the toolbar to use if there are no internal frames.
getMDIToolBar() setMDIToolBar()	Returns the toolbar used for the specified frame. If the frame is a JCMDIFrame with a non-null MDIToolBar, then this is returned; otherwise, the MDIToolBar for the this pane is returned. getMDIToolBar() takes a JInternalFrame as a parameter.   Sets the toolbar to use if there are no internal frames. setMDIToolBar() takes a JToolBar as a parameter.
getNonSelectedIcon() setNonSelectedIcon()	Gets or sets the non-selected icon, which appears before the non-selected items in the menu. The default is an empty icon that acts as a placeholder so menu items will be aligned properly. Setting both these icons to null restores the previous behavior.
getSelectedIcon() setSelectedIcon()	Gets or sets the icon which is to appear beside the selected window item in the Windows menu. The default icon is a check mark.
getPreferredSize()	If this pane has an ancestor that's a scroll pane or it has no children, then it returns the default preferred size. If it has children and no scroll pane for an ancestor, then it returns a size big enough to show all its children in their current locations.
getTopFrame()	Returns the topmost frame.
setInitialLayout()	Allows the layout of the MDIFrame windows to be set before the MDIPane window has been displayed. This has no effect after the MDIPane has been displayed for the first time. If not called, the initial layout is unpredictable.   Pass one of these constants to the method: JCMDIPane.TILE_HORIZONTAL, JCMDIPane.TILE_VERTICAL, JCMDIPane.CASCADE.
activateFrame() arrangeIcons() cascadeWindows()   closeFrame() deactivateFrame()   maximize()   tileWindowsHorizontally() tileWindowsVertically() unmaximize()	Makes this frame the active frame. Arranges "iconified" panes along the bottom. Arranges non-iconified panes in cascade form.   Closes or deactivates a frame.   Maximizes a pane, filling the host frame.   Tiles the frames in the specified direction   Returns the frame to its former size.   Note: These methods were protected in version 4.0 and have been made public in version 4.0.1.

There are a number of protected methods available to application programmers who wish to subclass a JCMDIPane. Consult the API for a list of these methods.

---

10.4 Examples

This code snippet highlights the few things that need to be done to convert your MDI application based on JInternalFrame into one based on JCMDIFrame.

import com.klg.jclass.swing.JCMDIPane;
import com.klg.jclass.swing.JCMDIFrame;

/**
* The class extends JClass Elements' JCExitFrame so you don't have to
* write repetitive window closing code.
*/
public class MDIInternalFrameDemo extends JCExitFrame implements
ActionListener {
/**
* The internal frames reside inside a JCMDIPane
*/
public MDIInternalFrameDemo() {
   super("JCMDIPane Demo");
...
desktop = new JCMDIPane(); // a custom layered pane
createFrame(); // Create first window
...
}
/**
* Each frame can have its own menu bar, whose elements are
* defined by you. A "Window" menu is added automatically.
*/
protected void createFrame() {
   JCMDIFrame iframe = new JCMDIFrame(
"MDI Frame #" + (++MDIFrameCount),
   true, //resizable
   true, //closable
   true, //maximizable
   true);//iconifiable
...
/**
* Use this method to set the menu bar on the frame, even though
* it appears on the desktop rather than on the individual frame.
*/
iframe.setMDIMenuBar(mbar);
...