LockableUI is definitely one of the most challenging feature in the JXLayer library. I have already written about why it was difficult and suggested several solutions and discuss the potential problems. So it was a long way to make it right and now I am satisfied with the result.

In this entry I compiled all up-to-date information about this feature, so forget about the blocking glassPanes, input verifiers, old JXLayer API and let's start.

Overview

The fact that disabling a Swing container doesn't mean disabling its child components, has always been surprising for Swing beginners (see this thread and this one), it surprises me as well, by the way.

Consider the following code:

JPanel panel = new JPanel(); 
panel.add(new JButton("Hello"));       
frame.add(panel); 
         
panel.setEnabled(false);

Despite the fact that the panel is disabled, its child button remains perfectly accessible. Actually, Swing doesn't provide a way to "disable" a container with all its child components. Recursive disabling or glassPane tricks have serious restrictions and that was the reason why I started to work on a LockableUI, which provides an elegant and safe way to temporary block a specific Swing container.

Check it out with the webstart link to the LockableDemo from the jxlayer demo package:

How to use it

As with all core LayerUI's, LockableUI is very easy to use:

// the component to be locked
JPanel panel = getMyPanel();
        
LockableUI lockableUI = new LockableUI();        
// wrap the panel with JXLayer and the lockableUI 
JXLayer<JComponent> l = new JXLayer<JComponent>(panel, lockableUI);        
// lock the layer
lockableUI.setLocked(true);

// add the layer as any other component
frame.add(l);

After that, your panel and all its children won't receive focus , mouse or keyboard events and when you move the mouse over it, you'll see the wait mouse cursor(on Windows it is hourglass cursor), and after the

// unlock the layer        
lockableUI.setLocked(false);        

the panel and all its children will work as usual. This is particularly useful when you read a big chunk of data from the network or database for a particular component - you lock it untill the data transfer has completed, leaving the rest of the GUI alive.

This is pretty cool, but to make it better we should use some visual effect for the locked layer, to notify the user that the component is locked. In my jxlayer demos I usually take advantage of standard BufferedImageOp mechanism from the core Java2D library.

With the BufferedImageOps you can have various effects like blurring, color conversion etc... For examplle, the following code snippet makes the locked layer black-and-white:

LockableUI ui = new LockableUI();
JXLayer<JComponent> l = new JXLayer<JComponent>(new JButton("Hello"), ui);

// Java2D grayScale BufferedImageOp
ColorConvertOp grayScale =
        new ColorConvertOp(ColorSpace.getInstance(ColorSpace.CS_GRAY), null);
// wrap it with the jxlayer's BufferedImageOpEffect 
BufferedImageOpEffect effect = new BufferedImageOpEffect(grayScale);
// set it as the locked effect        
ui.setLockedEffects(effect);
        
ui.setLocked(true);
frame.add(l);

LockableDemo

In the LockableDemo I use the beautiful set of image effects from Jerry Huxtable, here is his BlurFilter and plain LockableUI in action:

You can also customize the LockableUI and put the unlock button directly to the layer's glassPane, see the EnhancedLockableUI implementation from the LockableDemo, also note the EmbossFilter from Jerry:

The last LockableUI's subclass shows how JXLayer and SwingX painters work together. The BusyPainterUI from the LockableDemo uses BusyPainter from SwingX librarary and animates it to provide a nice busy effect for the locked layer:

Implementation

As all other core LayerUI's, the LockableUI neither use frame's glassPane or layeredPane, nor any other global settings like custom RepaintManager or EventQueue, it doesn't use JComponenent.print() methods, which was a problem for the old versions of this feature. All input events, including the keyboard actions, are effectively blocked for the layer's children when it is locked.

All information about the JXLayer library you can find on jxlayer.dev.java.net

See you on the JXLayer forum

Thanks
alexp