Last update: 2012/05/20 23:38 [index.html]

The JModalWindow Project
Title: JModalWindow
Author: Jene Jasper
Description: The JModalWindow project was created to support modal functionality, similar to JDialog, without blocking all frames. Source code, binaries, API documentation, and a demo are all available for download.
Article: or local copy
Downloads: latest
Issue Tracking: JIRA
Source Code Repository: SVN


Development Production Line - The Short Story [single html html chunks and pdf].

Just a setup manual triggered by a hard drive crash in 2007, which made it painfully obvious how much time it costs to install and get the different components up and running. But it already proved to be helpful when upgrading certain components because of the documented version numbers.

Thanks to the unmentioned posters/bloggers whose comments and installation pointers helped getting everything up and running, but alas keeping track where I found all those 'little snippets' would be a project in itself.

Note: As you can see in the statistics at the bottom of this page the manual upped the html count of the jmodalwindow project a bit. Maybe I should look for a different location to host this. ;-)


Version Status Source Binary JavaDoc Demo Issues &
1.00 milestone swingx_v0100_src.jar swingx_v0100.jar swingx_v0100_doc.jar swingx_v0100_demo.jar Initial JDK 1.3 version
1.02 stable swingx_v0102_src.jar swingx_v0102.jar swingx_v0102_doc.jar swingx_v0102_demo.jar Initial JDK 1.4 release
1.03 stable swingx_v0103_src.jar swingx_v0103.jar swingx_v0103_doc.jar swingx_v0103_demo.jar 1, 2 & 3
1.04 stable swingx_v0104_src.jar swingx_v0104.jar swingx_v0104_doc.jar swingx_v0104_demo.jar 4 & 5
1.05 milestone swingx_v0105_src.jar swingx_v0105.jar swingx_v0105_doc.jar swingx_v0105_demo.jar 6, 7, 9, 10, 11, 12 & 8
Revisited 1
1.06 stable swingx_v0106_src.jar swingx_v0106.jar swingx_v0106_doc.jar swingx_v0106_demo.jar 14 (see also FAQ 1)
1.07 stable swingx_v0107_src.jar swingx_v0107.jar swingx_v0107_doc.jar swingx_v0107_demo.jar 15 & 16
2.01 milestone swingx_v0201_src.jar swingx_v0201.jar swingx_v0201_doc.jar swingx_v0201_demo.jar 17, 18 & 19 (see also FAQ 2)
2.02 stable swingx_v0202_src.jar swingx_v0202.jar swingx_v0202_doc.jar swingx_v0202_demo.jar 20
2.03 stable swingx_v0203_src.jar swingx_v0203.jar swingx_v0203_doc.jar swingx_v0203_demo.jar 21 & 22
Sample Invalid Issues
swingx_v0105_sample.jar 13 & 23

To run demo type: java -jar swingx_v0203_demo.jar

To run with minimal configuration type: java -jar swingx_v0203_demo.jar -minimal (no blurring of blocked window, no busy cursor when moving the mouse cursor over the blocked window and disabled iconify of a blocked internal frame.)

To run article sample type: java -jar swingx_v0105_sample.jar



Question 1

I can't change the STOP-icon! I've tried:

UIManager.put("swingx.busy.cursor", "/home/images/custom-cursor.gif");1)

but then the STOP-icon is only changed to a smaller red square with a white X in it, which is not my icon… How can I fix this?

1) Since enhancement 14 it is possible to use JModalConfiguration.setBusyCursor(java.awt.Cursor) as well.


The white cross on the red background is generated with Utils.getMissingImage() to indicate that the specified icon/image couldn't be found.

To make the image available on the classpath there are two options:

  1. Place the image busy_cursor.gif in for example a subdirectory …/classes/images and add the following line to your code:

    UIManager.put("swingx.busy.cursor", "images/busy_cursor.gif");

    Note: if the class files are packaged in a jar make sure the images are also packaged in that jar.

  2. The image cursor.gif is available in the directory /usr/images. Create a zip or jar file …/dist/lib/ containing the image and including the subfolders /usr/images. Then add the following line to your code:

    UIManager.put("swingx.busy.cursor", "usr/images/cursor.gif")

    And suppose the application is packaged in …/dist/swingx_v0104_demo.jar then run the application with the following command:

    java -classpath "swingx_v0104_demo.jar;lib/" nl.jj.swingx.gui.modal.test.TestModalFrame

Note: In UIManager.put("swingx.busy.cursor", "/home/images/custom-cursor"); remove the first slash, because there is a difference between

  •      getInstance().getClass().getClassLoader().getResource(…); which I used and
  •      getInstance().getClass().getResource(…);

in the way they retrieve the resource.

By the way: Due to a Win32 problem the cursor to must be 32 x 32. To create a 16 x 16 icon use for example the upper left 16 x 16 pixels and fill the rest with a transparent color.

Question 2

I'm having a problem using the waitForClose() method. Basically, when I use this method, the entire application freezes and won't respond to events or repaint itself.


This is due to the fact that wait() shouldn't be called on the event dispatch thread (see How to Use Threads). Which means the waitForClose() is useless in ActionListeners and the like. For this reason waitForClose() now throws the following Error("Cannot call wait from the event dispatcher thread")2) when the method is called on the event dispath thread.

If you need to implement some action, when the window is closed, use the windowClosed method of for example the WindowAdapter and supply this to the addWindowListener method of the window, you want to monitor. For an example of its usage see: TestModalFrame method init() jbNormalWindow.addActionListener(…);

2) Since enhancement 19 it is now also possible to simulate wait on the event dispatch thread (EDT). Just call the enableWaitOnEDT() method of the JModalConfiguration class to activate this. Note: Because this method could throw a java.lang.SecurityException if a security manager exists and its SecurityManager.checkAwtEventQueueAccess() method denies access to the EventQueue, it isn't activated by default.