The JModalWindow Project Blog



    Parent and Child Windows
    The InputBlockerInterface
    Visualization and Blocking
    Construction ofModalWindows
    Activation and Blocking of the Parent Window
    Deactivation and Unblocking of Parent Window
    Blocked by Child Window
    Behavior when Blocked
    Unblocked by Child Window
    Window Drag Support
    Decorated Window Border
    Support Utility
    Latest Developments and Ideas
    Conclusion and Credits

    There are times when you want a modal window that implements window-specific modality rather than the application-wide modality provided by the standard JDialog class. This article explains the workings of the JModalWindow project, which provides two top-level components, calledModalWindows, that introduce such modality. The first ModalWindow class,JModalWindow, is a subclass of JWindowthat's generally used for dialogs that block other windows. The second, JModalFrame, is a subclass ofJFrame that can be used either as a blocked window or as a blocking window. Both classes implement an interface namedInputBlocker.

    Why create a ModalWindow instead of using the standard JDialog component? We were working on a pension-planner application to give users insight into their financial situations before and after retirement. This was done with the aid of a financial graphic. Throughout the application, help information for various pension-specific terms was available in a separate help window. In order to make comparisons, the user should be able to change different variables that influence pension savings. While doing this, the underlying financial graphic had to be blocked. A JDialog could have been used, but then the necessary help window would have also been blocked, and thus useless. Furthermore, the title bar presented byJDialog didn't fit in with the rest of the look and feel of the application.

    I searched the Internet for a possible solution for our problem and found several suggestions, but they all had drawbacks or loopholes. That is why I decided to create my own modal window implementation based on the ideas that came closest to our needs. The JModalWindow project is an open source version of our solution to this challenge and is part of the JavaDesktopcommunity at

    Parent and Child Windows

    It helps to have a common language when referring to the various windows involved. The window to be blocked is known as theparent window or owner; another term forblocked is busy. The window blocking the parent is the child window. A parent window can have more than one child window blocking it. Each child can block its parent and, in recently added functionality, some additional windows. Ideally, the parent window and the child window should both beModalWindows; at the very least, they should both implement the InputBlocker interface.

    An example will clarify these concepts. Here is a snapshot of a GUI produced by a JModalWindow that is modal with respect to a JModalFrame:

    Figure 1
    Figure 1. A snapshot of a GUI produced by a JModalWindow that is modal with respect to a JModalFrame.

    As the preceding figure shows, a JModalFrame's busy status is marked using a blur effect and stop cursor. You can customize the following aspects of the display:

    • Stop cursor: By default, this is a stop sign, but you can specify a custom cursor.
    • Busy effect: The built-in effects are raster or line.
    • Initial position of dialog: The dialog can be initially centered onscreen, centered over a window, relative to a component, or at a specific X,Y location.

    The following figure shows the same GUI as the preceding one, but with a line busy effect, custom stop cursor, and initialY position relative to the bottom of the Update button that brought up the dialog. The X position of the dialog depends on the JModalWindow release. The dialog is be positioned at the same X position as the button, as long as the dialog stays onscreen; otherwise it will be moved to the left to keepWindowCompletelyOnScreen.

    Figure 2
    Figure 2. The same GUI as the preceding one, but with a line busy effect, custom stop cursor, and initial Y position relative to the bottom of the Update button that brought up the dialog.

    The following code creates a dialog that is modal relative to the window (owner) containingreturnFocusComponent and that is optionally placed relative to returnFocusComponent. The dialog has a single button, which closes the dialog.

    private JModalWindow createStatusWindow( Component returnFocusComponent, boolean relative, String text) { Window owner = SwingUtilities.windowForComponent(returnFocusComponent); final JModalWindow jmw = new JModalWindow(owner, returnFocusComponent); jmw.getContentPane().setBackground(bg); jmw.getContentPane().setForeground(fg); jmw.getContentPane().setLayout(new GridBagLayout()); JButton jbClose = createJButton("Cancel"); jbClose.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent ae) { jmw.dispose(); } }); BorderLayout bl = new BorderLayout(); jmw.getContentPane().setLayout(bl); jmw.getContentPane().add(createLabel(text), BorderLayout.CENTER); jmw.getContentPane().add(jbClose, BorderLayout.SOUTH); jmw.setSize(300, 75); if (relative) { jmw.relativeToOwnerChild(returnFocusComponent); } else { jmw.centerOfOwner(); // jmw.centerOfScreen(); //another positioning possibility } return jmw; }

    For the best results, the owner should be aModalWindow. In the preceding code, theJModalWindow constructor sets up the dialog, and therelativeToOwnerChild method causes the dialog to be positioned just under the returnFocusComponent's onscreen representation.

    The InputBlocker Interface

    Both JModalFrame and JModalWindowimplement an interface called InputBlocker. The interface defines the following two methods:

    • public boolean isBusy();
    • public void setBusy(boolean busy, Window blockingWindow);

    With those methods, it is possible to check whether a window is currently blocked and let any child window signal that it is blocking or unblocking its parent.

    Note: The draft version of this article was written based on the sources of version 1.02. But since then I have added some new functionality that is detailed in the section Latest Developments and Ideas. One of those new functionalities led to a third method definition in theInputBlocker interface:

    • public void addAdditionalModalToWindow(Window window);

    With this method, it is possible to add additional windows that should be blocked at the same time as the parent window. This is the reason why in the next paragraphs the variablemodalToWindows is plural instead ofmodalToWindow, which you would expect because a child window only has one parent window.

    The isBusy and setBusy methods are useful for the parent window; theaddAdditionalModalToWindow method is useful for the child window.

    Visualization and Blocking

    To block all keyboard and mouse action for the underlying window, a JBusyPanel object can be used as aGlassPane for the blocked window. TheJBusyPanel, when activated, consumes all keyboard strokes for the underlying window and grabs the focus for any mouse action on it.

    To make it obvious that the window is blocked, you can apply one of two types of blurring:

    Blurring with horizontal lines. A bit of a legacy style, because the first raster implementation (drawing the separate dots) was too slow on older computers.
    Blurring with diagonal, parallel lines from top left to bottom right, which leads to a raster effect.

    The desired blur style, gap, and color are applied by thepaint method of the JBusyPanel. When blocked, the ModalWindow also changes the shape of the cursor (see getBusyCursor).

    To block the FocusManager in JavaTM 1.3,JBusyPanel overrides the deprecated methodisManagingFocus.

    Construction ofModalWindows

    The constructors for JModalWindow andJModalFrame accept the following parameters, as needed:

    Window owner
    To set the parent window for the newly constructed window.
    Component returnFocus
    To set the component that should get the focus when this window is closed.
    String title (JModalFrameonly)
    To set a title for the frame.
    boolean modal
    To change the default modal setting for the window.

    Each ModalWindow constructor performs the following actions:

    1. The appropriate super is called to set thetitle for the JFrame and theowner for the JWindow. (Note: If no owner is specified, the SwingSharedOwnerFrame is used.)

    2. The optional returnFocus is stored.

    3. The list modalToWindows is set to contain the supplied owner when this Window is constructed as being modal. Because the parent isn't blocked yet, the status variable notifiedModalToWindow is set totrue.

    4. The list with blockingWindows is initialized. ThisVector is used to make it possible to have multiple modal child windows.

    5. The JBusyPanel that will block this window is initialized with the following settings:

      • A color that is a bit darker than the default white background color.
      • A fixed BLUR_STEP of 2.
      • A BLUR_STYLE of the type raster.

      These settings were chosen because that combination looks best, in my humble opinion. However, if performance is an issue, these values can be changed in your own copy of the source code.

    6. Finally, the WINDOW_EVENT_MASK is used to activate the processing of WindowEvents.

    Each JModalWindow also performs the following initialization:

    • Creates a raised border to indicate that the window can be dragged.

    • Activates MOUSE_MOTION_EVENT_MASK for the processing of MouseEvents, to support dragging of the window.

    Each JModalFrame performs the following additional initialization:

    • Sets up a MinimumFrameSizeAdapter to keep the frame from being resized smaller than minWidth byminHeight when those values are supplied through the method setMinSize.

    • Checks whether a default icon, for which the resource location can be filed under the key swingx.frame.icon in theUIManager, is available. If this is the case, the support utility is used to fetch it.

    Activation and Blocking of the Parent Window

    As soon as a child ModalWindow is activated through a call to the method show, it checks whether it is modal to a parent window stored in the listmodalToWindows. When this is the case and the parent window implements the interface InputBlocker, itssetBusy method is called to notify that parent window that it is blocked by this child window. Should the parent window not implement the interface InputBlocker, then the parent window is only disabled.

    Unlike the JDialog behavior, calling the methodshow doesn't halt the calling thread. To create the same effect, call the method wait_for_close after calling show. (Note: This method will be renamed to waitForClose in a later release.)

    Note: Activating the window with a call to the methodsetVisible(boolean visible) results in an indirect call to the method show. That is the reason why the situation for visible is true isn't handled in the setVisible method itself.

    Placement of the ModalWindow is aided with the following helper methods: centerOfScreen,centerOfOwner, and relativeToOwnerChild. (See support utility for a description of these methods.)

    Deactivation and Unblocking of Parent Window

    Upon closing a child ModalWindow through aWindowEvent.WINDOW_CLOSED (see the methodsprocessWindowEvent and close), or a call to the method setVisible, the ModalWindowcalls the method restoreOwner to check whether it is modal to a parent window stored in the listmodalToWindows. When this is the case, the parent window is notified that this child window is no longer blocking it by a call to the parent window's method setBusy or, if the parent window doesn't implement the InputBlocker, by enabling it.

    Because a call to setVisible(false) results in aWindowEvent.WINDOW_CLOSED event and thus in multiple calls to the method restoreOwner, the variablenotifiedModalToWindow is used to prevent multiple calls to the parent window's method setBusy. This helps when the parent window's setBusy implementation doesn't handle multiple invocations by the same child window well. (My first implementation, for example, decremented ablockedCounter.)

    If the parent window is no longer blocked by any child window, the focus is returned to the optional returnFocuscomponent, if it's supplied.

    Finally, a call to the method release is made to notify any waiting threads that were halted by a call to the methodwaitForClose.

    Blocked by Child Window

    When a ModalWindow is blocked by a child window calling its setBusy method, the following actions are taken:

    1. Retrieve the default or the custom busy cursor.

    2. If the ModalWindow is not already blocked, save the current cursor and set the cursor to the busy cursor.

    3. JModalFrame only: Save current resizable status if the frame is not already blocked, and disable the resizing of the frame.

    4. Enable the JBusyPanel glass pane.

    5. Add the calling child window to the list ofblockingWindows.

    6. Force the glass pane to get the focus so that it consumesKeyEvents.

    7. Set the cursor for the glass pane to the busy cursor.
      Note: Setting the window cursor and the glass pane cursor in this order works around the Win32 problem where you have to move the mouse one pixel to get the cursor to change.

    Behavior when Blocked

    To check whether a ModalWindow is currently blocked, a call to the method isBusy results in a confirmation if there are any known blockingWindows. As soon as a ModalWindow is blocked, its behavior changes in the following situations:

    • JModalFrame only: A call togetDefaultCloseOperation always returnsJFrame.DO_NOTHING_ON_CLOSE.

    • The following WindowEvents are handled differently by processWindowEvent:
      • JModalFrame only:WindowEvent.WINDOW_ICONIFIED is reversed by setting the state back to NORMAL (see the methodcheckIconifyAllowed). This behavior will be changed with the release of version 1.05. (For more information, see the section Latest Developments and Ideas.)

      • JModalFrame only:WindowEvent.WINDOW_ACTIVATED results in moving its child windows to the front and in restoring the state of its child frames to NORMAL. (See the methodcheckForBlockingWindows, which will be renamed tocheckActivationAllowed in a later release.)

      • WindowEvent.WINDOW_CLOSING is not allowed (see the method tryToDispose).

    Unblocked by Child Window

    When a ModalWindow is unblocked by a child window calling its setBusy method, the following actions occur:

    1. Remove the calling child window from the list ofblockingWindows.

    2. Reset the cursor for the glass pane to the old cursor and disable the glass pane.

    3. Try to retrieve focus in the ModalWindow.

    4. JModalFrame only: Reset the resizable status to the stored wasResizable value.

    5. Reset the ModalWindow's cursor to the old cursor.
      Note: Setting the glass pane cursor and the window cursor in this order works around the Win32 problem where you have to move the mouse one pixel to get the cursor to change.

    Window Drag Support

    To support the dragging of a JModalWindow, the method processMouseMotionEvent checks the following things:

    If the mouse is moved near the edge of the window (based on the value of the variable DRAG_BORDER_DISTANCE; currently only a value of 1 seems to work properly), then the cursor is changed to the MOVE_CURSOR to indicate the possibility of dragging the window across the screen, and the current mouse position is stored in priorDragLocation.
    If the mouse is dragged, and the cursor has theMOVE_CURSOR shape and a priorDragLocationis available, then the window is moved along the deltax and delta y relative to the current mouse position, and the priorDragLocation is reset tonull to signal that the last mouse-drag event is handled completely. If there was no priorDragLocationavailable, then the current mouse position is saved for the next mouse drag event.

    Decorated Window Border

    To decorate JModalWindows with a raised border the following methods are overridden: paint,setBackground, and setForeground.

    Support Utility

    The Utils class handles various handy functions forJModalWindow and JModalFrame:

    Retrieves the busy cursor. You can define a custom busy cursor under the key swingx.busy.cursor inUIManager. A Win32 problem requires the cursor to be32 x 32.
    Retrieves the specified image resource as an icon. If the resource can't be found, returns the missing image icon.
    getStopImageStop Cursor
    Creates a stop sign as the default busy cursor.
    Creates a red cross on a white background to indicate that the specified icon/image couldn't be found.
    Positions a window in the center of the screen.
    Positions a window so it's centered above the parent window. This method uses some slack at the edges of the screen, with the currently hard coded variable SCREEN_SAFETY_MARGIN, just in case of operating system toolbars situated there.
    Positions a window just below the supplied component, similar to how a combo box's drop-down list is positioned. This method also uses some slack at the edges of the screen withSCREEN_SAFETY_MARGIN.
    Positions a Window at the specifiedx,y location, adjusting the location if it results in the window falling outside of the screen and becoming unreachable. This method also uses some slack at the edges of the screen with SCREEN_SAFETY_MARGIN. (Note: This method will be renamed to keepWindowPartiallyOnScreenbecause of the introduction of another method calledkeepWindowCompletelyOnScreen.)

    The Utils class also provides the following functionality, which isn't currently used by theJModalWindow and JModalFrame classes:

    Updates the component tree on changes in the look and feel. It works from the bottom up instead of the top down as in the Swing version, because some of our required look and feel changes otherwise didn't show without user intervention.

    Latest Developments and Ideas

    Recent additions to the JModalWindow project have been guided by discussions in a variety of forums. For example, one question on whether it is possible to make a dialog modal for some frames and non-modal for others led to the addition of the methodaddAdditionalModalToWindow(Window window) to theInputBlocker interface (link to post).

    A comment on a Spanish-language forum pointed out an additional use of modal windows due to the feature that a blockedJModalFrame, upon activation, automatically moves the blocking child window to the front. (Note: In a later release this feature will also be added for the mouse click in a blocked JModalWindow.) Here is a translated excerpt:

    When using a modal dialog in a Swing application the following undesirable effect takes place: when the user changes to another application and back to the Java application, the modal window is hidden under the main window. Due to the nature of modality, you cannot interact with the main one, and to top it all, the only way to return to the modal dialog is to use the combination of Alt+Tab keys ( link to original ).

    This discussion also triggered me to complete the project with aJModalDialog with the same functionality as theJDialog; in other words, blocking all active frames and windows, but using the same approach as theJModalFrame and thus creating the same visual effect. Because the InputBlocker now had the additional methodaddAdditionalModalToWindow(Window window), it was possible to create a simple JModalDialog by extending it from the JModalFrame and justmarkAllWindows(), except for the dialog itself and the Swing shared owner frame, to the list of windows that must be blocked. For a JModalDialog to work properly, all used windows should be ModalWindows or, at the very least, implement InputBlocker, because you can callsetEnabled(false) only so many times.

    Another user asked in a forum posting if I had noticed a severe flicker when one or two modal windows are opened. Once I knew where to look, I saw a rather annoying flicker that I had never noticed before. The flicker was caused by the call tosetResizable(false). That is why I changed the way resizing is prohibited when the frame is blocked (link to post).

    As a result of an issue reported on a problem with the use of window positioning relativeToOwnerChild in a dual-monitor environment, I added support for theGraphicsConfiguration and the use of its suppliedgetBounds() method for correct window positioning.

    The following cosmetic changes were made, which in some cases provide more leeway than one would normally expect for modal windows:

    • To keep the duplication of code to a minimum, a helper class named JModalHelper was introduced.
    • Resizing and moving of blocked windows was enabled.
    • The methodactivateFirstAvailableBlockingWindow(WindowEvent windowEvent) was added to the InputBlocker for the prior mentioned feature that a blocked JModalFrameupon activation automatically moves the blocking child window to the front.
    • To enable the use of "Show Desktop", it is necessary that a blocked JModalFrame is allowed to be iconified.
    • A fix for the incomplete repainting of a frame that sometimes occurs when a frame is de-iconified immediately after it was iconified. When the frame is first moved toFrontbefore is it de-iconified, this problem doesn't manifest itself anymore.

    If you want to find out about some of the dirty details that led to some of the choices, just check the issue list.

    Conclusion and Credits

    As always, if a standard Swing component meets your needs, you are encouraged to use it. In the case where you are looking for a window that does not block the entire application but is modal only with respect to some of your open windows, you may want to consider using JModalWindow. Visit the JModalWindow projecthome. I look forward to your feedback and suggestions for further enhancements and comments on how you may be using this project in ways that we may not have anticipated.

    Finally, if you want to use modal windows with JavaTM1.3, contact me for the 1.3 source code. If there is enough interest we could also create a project branch for a 1.3 version.

    A runnable .jar, which was used to create the screenshots and is based on the above shown sample code, is available for downloadat the JModalWindow project.

    I would like to mention the people whose ideas contributed to the creation of this project (in alphabetical order):

    • Sandip Chitale, for his ideas on creating a modal window.
    • Maks Smits, web designer at Quobell, for his suggestion to blur the blocked window.
    • Dan Syrstad, for his idea on creating a busy frame.

    I would like to thank the people whose support contributed to the existence of this project (in alphabetical order):

    • Ise Douwes at Quobell, my former employer, for letting me have the copyright on the source code, based on, as he put it, "intellectual ownership."
    • Oleg N. Sukhodolsky at Sun, for reviewing the source code and for his suggestion for added functionality.
    • Scott Violet at Sun, for noticing my email, among other things.
    • Kathy Walrath at Sun, for editing this article.