The Rabbit Hole

WebStart unit tests

2009-10-10T08:32:00.006-04:00

I had a few bits of JNA functionality that were only active when in a web start environment, which made it a bit tricky to add tests for them that could be run at the same time as all my other tests. The functionality also showed up as a big splot of missing code coverage under clover, so I decided to tinker just a bit to see if I could somehow simulate a web start environment for the unit tests.

I managed to come up with a JUnit-based test fixture which ensures its test methods are all run in a web start environment. This works well under Windows and OSX; unfortunately *nix variations use NetX which needs some extra hand-holding when first run.

Finding the right hooks involved standard hacking to find whether the most configurability was offered by invoking the javaws executable or adding the javaws classes to my classpath and hooking directly into the Java. I ended up doing a Runtime.exec to ensure the running environment wouldn't interfere with that of Web Start.

The main obstacle to be overcome was signed code. You can get web start to run unsigned code by tweaking the local policy file to allow the code we're testing, but when you include any native code via the <nativelib> tag, JNLP requires the <all-permission> tag, which seems to re-trigger the requirement for signed code. Self-signing the code is no big deal, but that triggers web-starts authorization dialogs to allow the unknown CA to be used. Fortunately, the somewhat obscure deployment properties file can be used to temporarily allow the self-signed certs and bypass the dialogs. The tests can be run entirely without user input (except in the case of *nix, where NetX is not sufficiently configurable -- you have to dismiss the dialog on the first test run).

Unfortunately the exit codes for javaws don't correspond to the codes passed to System.exit by Java code, so I had to have the test fixture communicate to the running javaws instance via socket. Failures are transmitted by the fixture in such a way that you can't tell that the test is running in a separate process.

I encapsulated the deployment config, JNLP file creation, javaws launch, and test case execution into a single class, WebStartTest, which runs a few self tests and can be extended to add whatever other tests you need to run under web start. The JNLP is partly hard-coded to include files set up sepecifically for JNA testing, but should be trivial to change to accommodate a different project.

There are probably other ways to test WebStart code, but this fit nicely with the project's existing tests, allowing its WebStart features to be tested by test methods identical to those for the rest of the project.

Full source is here. This has been tested under Sun and IBM JDKs, on Windows, OSX, Solaris/sparc, and GNU/Linux.

JNA: increasing performance with large Structures

2008-09-11T21:24:00.003-04:00

If you're using very large structures and using them often, here's a tip that can boost performance by several orders of magnitude. Note that you should follow this tip *only* if you really need the performance boost; otherwise you may wind up obfuscating your code.

By default, when JNA makes a native call it will copy the full contents of a Java Structure to native memory prior to the call and read it all back after the call. If your Structure is very large, this can result in significant overhead reflecting all the fields of the Structure. The reflection dwarfs the actual native communication time.

If you're only reading or writing a single field, it's much faster (although somewhat less elegant) to use the readField(String) and writeField(String) methods to access the data, while disabling the normal read and write. Depending on the size of your structure, you may see two orders of magnitude or more improvement in the native function call time.

Here's an example of performing the same operation two different ways:


class Big extends Structure {
    public int toNative;
    public int fromNative;
    // plus lots more fields
    // the more, the bigger the difference in performance
}

class FastBig extends Big {
    public void read() { }
    public void write() { }
}

Big big = new Big();
big.toNative = 42;
lib.callMyNativeFunction(big);
System.out.println("Got " + big.fromNative);

Big fast = new FastBig();
fast.toNative = 42;
fast.writeField("toNative");
lib.callMyNativeFunction(fast);
System.out.println("Got " + fast.readField("fromNative"));

If you wrap a loop and time these, you'll see what kind of difference it makes. On a test structure with 25 "int" fields, the fast version reduces time by a factor of 10.

Trivia: some other "struct" implementations (e.g. Javolution) use objects for all fields and require an explicit "write" or "set" on each. This reduces data transfer and/or reflection overhead, at the expense of simplicity of assignment and initialization.

JNA:
s.field = 1;
call(s.field);

Javolution:
s.field.set(1);
call(s.field.get());

JNA win64 port

2008-09-04T11:12:00.003-04:00

JNA now supports 64-bit windows. The the build is a bit nonstandard, but it's automatic and reproducible. I was hoping to use mingw-64, but that project is not yet sufficient for JNA's purposes. Fortunately, the MS has a free 64-bit cross compiler which does work.

Thanks to the fine folks at Aquafold (actually mostly Niels G. the CTO) for making it possible.

Thanks also to T. Heller of python's ctypes for the initial glue bits.

Decorator Update

2008-08-10T20:26:00.006-04:00

Thanks to some input from a few users, the AbstractComponentDecorator has been updated to fix a few visual and behavior artifacts.

Get the latest from Sourceforge SVN.

The decorator component allows you to apply arbitrary decorations to a component without affecting its layout or (necessarily) response to events.

This blog has many different examples of usage beyond simple decorations, including drag images and per-component input blocking.

Embedding DLL File Version Information with mingw32/cygwin

2008-01-19T17:57:00.000-05:00

If you look at the properties window for a DLL file in Windows, you'll see a few bits about the file version and copyright info. I couldn't find any information on the web about how to embed that information into a DLL. Not terribly surprising, since it's probably something MSVC inserts automatically, so why would any one need to know how it's done?

Well, I'm building a DLL with cygwin/mingw32, so I do need to know how it's done. Fortunately, Mumit Khan, author of mingw32, wrote a utility called "windres", which compiles w32 resources for use in an executable or DLL. It'll compile directly to object format, which you can simply add to your final link.

For example:

% windres -i version.rc -o version.o
So the only thing I needed to figure out was the version resource format (I really didn't want to go grok the resource spec and write it from scratch). Luckily, Java's main DLL (java.dll, what else) has version information in it, and windres can also conveniently dump an exe or dll back into text format.

The java.dll resource info looks like this:


% windres -i java.dll -O rc

// Type: version
// Name: 1
LANGUAGE 0, 0
1 VERSIONINFO
 FILEVERSION 6, 0, 30, 5
 PRODUCTVERSION 6, 0, 30, 5
 FILEFLAGSMASK 0x3f
 FILEOS 0x4
 FILETYPE 0x2
BEGIN
  BLOCK "StringFileInfo"
  BEGIN
    BLOCK "000004b0"
    BEGIN
      VALUE "CompanyName", "Sun Microsystems, Inc."
      VALUE "FileDescription", "Java(TM) Platform SE binary"
      VALUE "FileVersion", "6.0.30.5"
      VALUE "Full Version", "1.6.0_03-b05"
      VALUE "InternalName", "java"
      VALUE "LegalCopyright", "Copyright \251 2004"
      VALUE "OriginalFilename", "java.dll"
      VALUE "ProductName", "Java(TM) Platform SE 6 U3"
      VALUE "ProductVersion", "6.0.30.5" 
  END 
END

With just a few tweaks to do a regexp replace on the new template and include the new obj in my build, my released dll now has visible version information (and in this case I'm perfectly happy having absolutely no clue what any of the resource file text actually means :).

Run your Java program as an NT service

2007-09-12T11:52:00.000-04:00

Thomas Boerkel has contributed some mappings and code to the JNA project to facilitate access to Windows' user accounts, registry, and NT services. Included is an abstract class which is capable of installing, uninstalling, and running itself as an NT service. What sets this little gem apart from most available wrappers is that you don't need a Windows executable stub; the complete Windows service API is available to your Java program, including all system events and callbacks.

You can browse the source here. A NetBeans project is included.

I was working on an abstract service class as well but Thomas beat me to completion. Great work, Thomas!

Update: Make sure your classpath and classes are accessible by the local system account, or the service won't be able to start. To see if this is the issue, you can temporarily change the service to start using your user identity; if it works, then the problem is that the local system account doesn't have access.

Is final not final, or just not the final I wanted?

2007-09-06T14:33:00.000-04:00

While adding some VM crash protection to JNA, I ran into this situation:


public class Pointer {
    public static final int SIZE = Native.POINTER_SIZE;
}

public class Native {
    public static final int POINTER_SIZE;
    static {
        initIDs();
        POINTER_SIZE = pointerSize();
    }
    private static native int pointerSize();
}

I had just moved the native initialization code from Pointer to Native. All the native methods were private, so the only changes were to update those two classes and rename the native methods. But when I reran the test suite, I started getting a host of errors.

There errors were all caused by Pointer.SIZE having a zero value. I figured that since Pointer.SIZE was final, the value it was assigned from must also have been zero. A quick inspection on Native.POINTER_SIZE, however, showed that it was propertly initialized and non-zero. How, then, could Pointer.SIZE be zero if Native.POINTER_SIZE was not?

Anyone who has done any JNI is probably aware that Java access modifiers don't mean anything to native code. My first thought was that perhaps "final" modifiers don't mean anything either. Only problem is that I was never touching that Pointer.SIZE field in native code. Never even accessed it.

Scanning though the native initialization code, I noticed that, among a host of standard JRE classes, a reference to the Pointer class was being created. This turns out to be the cause of my problem: during Native class initialization, the Pointer class was loaded from JNI. When the pointer final field was initialized, it got the value from a not-yet-initialized Native class.

Turns out, this can be duplicated with pure Java code:


public class LoadTest {
    public static final int VALUE;
    static {
        System.out.println("value=" + Secondary.VALUE);
        VALUE = 1;
        System.out.println("value=" + Secondary.VALUE);
    }
}

class Secondary {
    public static final int VALUE = LoadTest.VALUE;
}

When loaded, the class prints "value=0" twice, so final is final, just not the value I intended. Here, the problem is more apparent because the class dependency is clearly visible, which wasn't the case with the JNI initialization.

Maybe I'll call this antipattern something curiously obscure, like "Law of the Polygamist's Second Wife".

Demo sources

2007-07-23T15:14:00.001-04:00

All source for demos in previous blog entries is now available via SVN on SourceForge. The project page is here.

All sources are provided under the LGPL.

Improved Window Shaping

2007-06-27T14:05:00.001-04:00

Thanks to contributions from Olivier Chafik and Chris Deckers, the overhead for setting a window shape mask has been reduced by about two orders of magnitude. In this case, the balloon tip windows no longer have such a noticeable delay before showing.

Linux users should also have fewer issues with this version; some of the library setup previously required is now taken care of automatically by the JNA library.

Easier Alpha Masks

2007-05-12T00:10:00.001-04:00

The per-pixel alpha masking in this post has been codified into a simple API.

WindowUtils.setWindowTransparent(Window w, boolean transparent);

This effectively gives the window a transparent background. The alpha levels of the window's contents are preserved.

The demo is similar to the previous one but adds a few standard components to the mix.

UPDATE If you have a linux system and this for some reason doesn't work, please post a comment to that effect, or post a message to users@jna.dev.java.net so we can ensure this works reliably across all linux systems (64-bit is in the works).

Improved Drag Images

2007-04-25T17:19:00.001-04:00

A while back I posted some drag/drop handling code that included drag images that were closer to real drag image support, but were restricted to only showing up on windows belonging to the same VM.

Now, thanks to the window masking and transparency utilities provided by JNA, the drag images can escape the bounds of java windows.

This wasn't quite as easy as expected, even with the shaped, transparent windows already taken care of.

First, I had intended to use Swing's built-in drag support, given that Shannon Hickey has put so much work into improving it. Unfortunately, that built-in support, while making some operations very easy, makes others impossible. Namely, drag image support requires updating the image's location in response to cursor motion. While it's technically possible to listen for motion outside the drag operation using a global DragSource listener, that's a hacky workaround. So instead, I fall back to raw DnD with DragGestureListener, DragSourceListener, et al. These provide the necessary hooks to move the drag image, and I already have some abstract base classes that provide a basic, customizable implementation.

Next, I uncovered a bug in the JNA example code converting an Icon into a region mask. It turns out that a BufferedImage of type TYPE_BYTE_BINARY applies something like a 50% luminance threshold, when what I really wanted was a zero/non-zero threshold based on the alpha component of the icon's pixels. I tried writing my own binary Composite to do just that, but wound up with errors downstream of the actual composite operation. Fortunately, BufferedImage.getAlphaRaster on a standard ARGB image gives me pretty much what I want.

Finally, once I instantiated a window under the current drag operation, I could no longer drop anywhere. Which makes sense when you consider there is now a window in between the cursor and any place you'd like to drop. I almost gave up thinking this was an intractable problem given that DnD is so tightly wound up with native implementations, but I'm always game for one more variation. Remember that a window region can have holes in it, where events pass through to whatever lies beneath. Well, what if we put a hole right where the cursor is? Since it's directly under the cursor, it's not really apparent, but it allows events to pass through to the underlying drop target. We only need a single pixel, because that's all the DnD system cares about (I initially made it much bigger just so I could be sure I put it in the right place). Voila! It works.

Alpha-mask Transparency for a Window

2007-04-18T11:45:00.001-04:00

Finally got per-pixel alpha mask working on w32. The included image isn't the greatest for showing an antialiased edge (it does have one), but if you have something with a drop shadow lying about, just drop it on the demo window and that'll be used instead.

Update This demo works on Windows, OSX and Linux (Linux requires JRE1.5+).

Update Here's another image to drop on the demo window, which better demonstrates the alpha blending, in case you don't have any handy

I've got some working X11 code, too, but I need to figure out a decent API to make it happen. OSX lets you just set the window background pixel transparent and then everything you paint in the window is automatically composited with whatever alpha mask you paint with. That could probably work with Swing as well, but you have to magically drop anything with a default background. OSX does this by checking for a magic UIResource color; anything painted with that color is fully transparent.

Update Source is available on BRANCH_V2 from JNA.

I realize I may be an utter dolt, but I find it really hard to follow Microsoft APIs. I've worked with Qt, X11/Xt, and Mac, each of which has its peculiarities of architecture, but those have a consistency (might I say design) that spans more than two or three functions.

Java Transparent Windows (X11 update)

2007-04-13T22:36:00.000-04:00

Update: If your X11 setup supports it (XFCE, metacity + xcompmgr, compiz, etc), the JNA shaped window demo now has window transparency.

Thanks to Romain Guy for some initial testing and VMWare for making experimental linux installations easier.

Update: BTW, the linux setup I used was ubuntu (after installing xubuntu packages to get xfce; should have started with xubuntu). Note that the transparency is similar to that on OS X and w32, i.e. a single alpha level for the entire window. Next up is to apply a per-pixel alpha mask, if I can scrounge up some samples of how to do it on each platform.

I added some features to JNA to facilitate working with the X11 visual lookups (it returns an array of structures), so a few more files got changed than just the examples jar. If you want the latest and greatest, you'll need to check out from CVS and do 'ant examples-jar'.

Another thing that sucks about applets...

2007-04-05T12:40:00.000-04:00

You can't easily make the background color match the web page. You'd think that Applet.setBackground() would just Do the Right Thing.

You don't necessarily want to hard-code a value into the applet, but even if you set a value via javascript/livescript, you've got to do extra work to make it propagate down the hierarchy.

This is also applicable to Swing; you can't set a background color on a parent component and have it propagate to descendants. The first non-opaque component you run into is going to get its background from the UIManager. I really don't want to have to figure out which UIManager colors I have to override just to set the bloody background color of my app.

Maybe the new JSR 296 will do something about this, maybe not, but it'd be nice to have something akin to the old X toolkit's resource specifiction:

*.background: red
*.JCheckBox.background: red
JApplet.*.background: red
named-applet.*.background: red

The idea is that you can isolate or aggregate just about anything in the hierarchy by name or by class, and apply a resource setting to it (I guess they're calling it "injection" these days).

Animated Per-panel Options Pane

2007-04-05T11:26:00.000-04:00

Here's another example in the search for an unobtrusive property editor. This one looks a little like the Google Maps thumbnail navigator (at least with respect to its activator).

Contents

Toggle Button Positioning
Layout Animation

The API is simple:


// This component's preferred size will normally be that of its content
container.add(new OptionsPanel(content, options));

The purpose of this component is to unobtrusively associate a nontrivial set of options with some content whose display is typically larger than the options themselves. The options display is kept close the the content it modifies, which avoids the user having to go search through menus or play dialog positioning games. Since the options are hidden by default, you also don't have them always using up screen real estate. This sort of thing is often wedged into a docking solution, which is inappropriate if the information doesn't need to be visible at all times. A docking solution also insists on allocating the whole edge of the dock, so if you don't have other junk that has to be in there, you're wasting a lot of space.

The OptionsPane component wraps the content in the center of a BorderLayout and keeps the PAGE_END slot available for the options themselves.

Toggle Button Positioning

Notice that the toggle button isn't affected by the border layout (or any other content, for that matter). The toggle button has been placed in a layer above the rest of the content, so it's always visible and doesn't contribute to any layout complexity.


JRootPane root = SwingUtilities.getRootPane(this);
if (root != null) {
    layered = root.getLayeredPane();
    if (layered != null) {
        int layer = JLayeredPane.DEFAULT_LAYER.intValue();
        layered.add(toggle, new Integer(layer + 1));
        updateButtonLocation();
    }
}

We also want to update the button location whenever the OptionsPane moves. While we could use a ComponentListener, that would update the button's location after the OptionsPane was moved/resized, resulting in some jerkiness to the display. So instead, the button gets moved at the same time as the parent component:


public void setBounds(int x, int y, int w, int h) {
    super.setBounds(x, y, w, h);
    updateButtonLocation();
}

Layout Animation

Rather than instantly making the options visible and doing a single relayout, we use a javax.swing.Timer to gradually grow the options from the lower right corner into its final position. The bottom slot of BorderLayout will respect a component's height, but stretch or squash the component to the pane's current width. So changing the height gradually will work, but changing the width will have no effect (the component simply appears to rise from the bottom of the panel, rather than from the lower right).

Rather than changing the width, we use an empty border in a JPanel wrapped around the options component. By changing the width of the left border, the options appear to grow from the left to the right.

The animation increment is simple (move half the remaining distance), which is pretty good for most purposes. This is the Timer configuration in response to the expansion button click:


final int INTERVAL = 50;
final int FRACTION = 2;
final boolean expanded = isExpanded;
Timer timer = new Timer(INTERVAL, new ActionListener() {
    public void actionPerformed(ActionEvent e) {
        Insets insets = optionsBox.getInsets();
        Insets delta = targetInsets(expanded);
        Dimension targetSize = targetSize(expanded);
        int dx = (delta.left - insets.left)/FRACTION;
        if (dx != 0) {
            insets.left += dx;
            optionsBox.setBorder(new EmptyBorder(insets));
            optionsBox.revalidate();
            repaint();
        }
        int dy = (targetSize.height - optionsBox.getHeight())/FRACTION;
        if (dy != 0) {
            Dimension size = optionsBox.getSize();
            size.height += dy;
            optionsBox.setPreferredSize(size);
            optionsBox.revalidate();
            revalidate();
            repaint();
        }
        if (Math.abs(dx) <= 1 && Math.abs(dy) <= 1) {
            ((Timer)e.getSource()).stop();
            toggle.setEnabled(true);
            if (!expanded) {
                remove(optionsBox);
            }
            revalidate();
            repaint();
        }
    }
});
timer.setRepeats(true);
timer.start();

You can play around with the FRACTION and INTERVAL constants to see the effect it has on the animation.

Source is available in the applet jar file in the article link.

Speech Bubble Update (with Drop Shadow)

2007-04-02T12:19:00.000-04:00

I added a drop shadow to the speech bubble. You don't need it on OSX (OSX provides one automatically), and I don't have compiz or similar compositing window manager installed on linux at the moment (although if anyone is willing to submit/test the corresponding code, I'm happy to include it).

Nothing fancy, just black with 50% alpha. The shadow mask is just the original mask, sheared, scaled, and offset. The drop shadow would probably look nicer with a blurred edge, but that likely requires a variable alpha setting for the window (although you might be able to fake it by varying the edge color). Applying per-pixel alpha masks prior to Windows Vista seems to be non-trivial (this example uses a single alpha value for the entire window).

The JNA function definitions are trivial:


    int GetWindowLongA(Pointer hWnd, int nIndex);
    int SetWindowLongA(Pointer hWnd, int nIndex, int dwNewLong);
    boolean SetLayeredWindowAttributes(Pointer hwnd, int crKey, 
                                       byte bAlpha, int dwFlags);

As is the actual usage:


    Pointer hWnd = getHWnd(w);
    User32 user = User32.INSTANCE;
    int flags = user.GetWindowLongA(hWnd, User32.GWL_EXSTYLE) | User32.WS_EX_LAYERED;
    user.SetWindowLongA(hWnd, User32.GWL_EXSTYLE, flags);
    user.SetLayeredWindowAttributes(hWnd, 0, (byte)(255*alpha), User32.LWA_ALPHA);

The only real trick is that DirectDraw must be disabled in order to get the transparency effect and avoid leaving behind painting artifacts.

java -Dsun.java2d.noddraw=true ...

NOTE: thanks to l2fprod for the hint and the original round, transparent clock!

Update: Demo is now available from the JNA homepage.

Give your application a speech bubble

2007-03-28T18:45:00.000-04:00

As a result of an argument about the best way to present meta-information about complex application objects presented to the user, I had to come up with some concrete alternatives.

The problem is that for a given item in the application (in this case an SVN-based revision control client that aggregates and presents large amounts of meta-information about the repository), there may exist information that just doesn't fit in the display. You want to provide the user with a route to the desired information with as few inputs as possible.

Tooltips is one alternative, but aren't always appropriate. While you can set (globally) the delay before appearance and the time before dismissal, dismissing them is implicit. In my application, I need the meta information to be displayed or hidden explicitly, so that rules out tooltips (at least without substantial modification of the tooltip manager).

A dedicated "inspector" window is another alternative, but kind of heavyweight. We definitely don't want a component that can be activated, since that introduces focus issues. I also didn't want to make it appear to the user that there was a generic "container" that kept resizing and moving, as if it were a tool palette that couldn't decide on its purpose. At a minimum the window has to be undecorated and pretty much behave like a tooltip.

What I really wanted was something in between the two. A simple Popup with a unique appearance which could be shown or hidden at will. Apple introduced something like this as Balloon Help years ago, although I think the main problem was that they didn't get the trigger quite right. One reason a lot of expert users don't like tooltips (or balloon help) is that they show up when you don't expect it and you have to wave the mouse to make them go away (usually causing another one to be triggered).

Google maps does a nice job with their balloon tips. The trigger is obvious, and the tip itself provides a close button (and now I notice a maximize button as well).

So I started out with Popups via PopupFactory and wound up with another demonstration of non-rectangular clipping, brought to you by the JNA project. The API is pretty simple:


Component myComponent;
Component myBubble;
Point where; // location relative to myComponent
final Popup popup = BalloonManager.getBalloon(myComponent, myBubble, where.x, where.y);
popup.show();
// Hide the popup on mouse clicks
myBubble.addMouseListener(new MouseAdapter() {
    public void mouseClicked(MouseEvent e) {
        popup.hide();
    }
});

The balloon is a simple rounded rectangle with a triangle stuck to the bottom, with the corresponding Area used as the window mask.

I originally tried using PopupFactory directly, but it doesn't provide enough control over the intermediate components (the ancestors of the content that you don't really see; there's a pesky medium-weight popup that uses java.awt.Panel, which can't be easily masked). This implementation uses a window for any popup, regardless of whether its fully contained within the parent component.

Drop shadows would be nice (maybe someone wants to contribute some compositing code?).

Building w32 JNI DLLs with gcc

2007-03-13T12:41:00.000-04:00

After a bit of trial and error, I got JNA's native shared library to build (and run, and run tests) using gcc. Unfortunately the available documentation didn't quite work for me (might be a problem with my cygwin installation, but I wasn't the only one with an issue).

gcc-mingw is a version of cygwin gcc that can compile directly to the w32 api, without any of the cygwin emulation layer.


% gcc -dumpspecs | sed s%dllcrt2%/lib/mingw/dllcrt2%g > specs.new
% gcc -mno-cygwin -D_REENTRANT -D_GNU_SOURCE \
      -D__int64="long long" -D_JNI_IMPLEMENTATION \
       -o 
      -shared -Wl,--kill-at -specs specs.new -L /lib/mingw

The -mno-cygwin flag tells the compiler to run in mingw mode, i.e. omit all the cygwin unix compatibility layer and compile directly against the w32 api.

GCC's built-in 64-bit type is long long, so we map the type used in the JNI headers, __int64, to that type. Defining _JNI_IMPLEMENTATION ensures the JNI implementation exports its native method declarations.

Defining _REENTRANT and _GNU_SOURCE cause certain additional declarations of C library functions to be included. If you've never heard of them, most likely you don't need them.

The --kill-at flag to the linker ensures all symbols are exported undecorated, i.e. _my_func instead of _my_func@NN, which is the default when a function is declared as __stdcall. You could also use --add-stdcall-alias, which includes both versions of the symbol.

The GCC specs need tweaking or gcc-mingw doesn't find its initialization code for dlls, dllcrt2.o. We also have to nudge gcc-mingw to find the mingw libraries. Normally this is taken care of automatically by gcc, but for some reason my installation of cygwin gcc wouldn't find them, and no amount of -L or explicit object linkage would fix it.

Anyhow, with that out of the way, you don't have to have Microsoft's tools to build JNA or any other JNI library on w32.

I have noted that GCC apparently handles floating point a little differently, since the JNA tests that use FP return values/arguments are failing with the GCC-build dll.

Non-rectangular Windows Update

2007-02-27T17:30:00.002-05:00

Updated to include support for OSX and linux.

While OSX doesn't actually use any native code to do the window mask, JNA support is there if it needed to. Source (and per-platform binaries) is available at http://jna.dev.java.net.

Update
Transparent version of the demo is available here.

Non-rectangular Windows

2007-02-23T22:22:00.003-05:00

I've been meaning to play around with shaped windows for a while, but didn't relish the thought of walking through the tedium of JNI configurations and builds. Doing it on one platform is bad enough, but on several? No thanks.

So I thought I'd write a little scriptable shared library access stub once and be done with JNI entirely. Well, turns out it's already been done. Several times.

JNative
NLink
JNA

JNative has some interesting features not found in the others, but actually using it is only slightly better than JNI. NLink is currently w32-only, and has a bit of a COM bent. JNA fit most closely with my objectives, already had implementations for w32 and solaris, and was already platform-agnostic. So I took a couple days to hack in some more features (mostly to get an understanding of the codebase), and here is what I got. The following code is what it takes to make a frame take an arbitrary shape.


    User32 user32 = User32.INSTANCE;
    GDI32 gdi32 = GDI32.INSTANCE;
    JFrame frame = new JFrame(getName());
    Pointer p = gdi32.CreateRoundRectRgn(0, -150, 300, 300, 300, 300);
    int hWnd = user32.FindWindowA(null, getName());
    user32.SetWindowRgn(hWnd, p, true);

Looking up the appropriate w32 calls probably took the most time. How are the w32 libraries defined? How is this for trivial:


    public interface User32 extends StdCallLibarary {
        User32 INSTANCE = (User32)Native.loadLibary("user32", User32.class);
        int FindWindowA(String winClass, String title);
        void setWindowRgn(int hWnd, Pointer p, boolean redraw);
    }
    public interface GDI32 extends StdCallLibrary {
        GDI32 INSTANCE = (GDI32)Native.loadLibrary("gdi32", GDI32.class);
        Pointer CreateRoundRectRgn(int left, int top, int right, int bottom, int w, int h);
    }

Now, somebody's probably going to point me to how SWT has had this functionality for years (does it?), but this is nicely abstracted and based on a very small number of classes. I'll be updating the code at jna.dev.java.net (or maybe opening a new location if I can't get the existing project moved to subversion), but for now, check out the demo by clicking on everyone's favorite orange launch button.

Permissions required, because this runs some custom native code.

Oh, BTW, this is windows-only for the moment. I'll do X11 next and anyone's free to send me some code snippets for setting window masks on other platforms. I could also use some help porting to PPC and other platforms (a very small amount of native ASM to push arguments to the stack, not too hard).

JDK 1.6 Applet Madness

2007-02-16T14:04:00.000-05:00

I had a few applets on the main page showing some interesting eye candy. Then I upgraded my JDK to 1.6 and they lock up the java plugin (IE or firefox). If anyone has encountered a similar issue, please let me know, I'd really like to fix it.

I've gotten a variety of errors, but I can't seem to come up with an effective workaround or consistent analysis (JDK 1.6 doesn't let you pick a different VM to use for applets).

Waiting and Blocking Input

2006-11-27T17:52:00.001-05:00

Those pesky users are always trying to submit forms more than once, or creating new files willy nilly while they're waiting for feedback.

This article addresses two strategies for avoiding Impatient User Syndrome. First, provide some feedback to show that the program is busy, and second, don't allow any additional input.

Now, Java provides a JProgressBar, which you can throw up in a Dialog, but those aren't always appropriate. Sure if you want to block all application input (or in the case of Java 1.6, all frame input), that'll work, and you can always disable one component at a time. But suppose, for instance, that you've got a single frame, with a couple of different sections or docked panels. If their operation is independent of one another, you certainly don't want to block them all with a dialog.

The following demo shows how to block input on individual components, groups of components, or an entire frame, as well as providing "busy" feedback. The class WaitIndicator installs a component in the JLayeredPane above the target component, which prevents any mouse input from reaching the target component, and displays an hourglass cursor over the target component. It also installs a key event handler to ensure that no key events reach the target component.

The WaitIndicator also provides a paint method, which you can use to provide whatever visual feedback is appropriate to your program. The default implementation fades to the target component's background color. The demo itself uses a SpinningDialWaitIndicator, which paints an Apple-like spinner (which you can also see in the animated icon demo applet a few entries back).

Source

Tree (and tree table) with checkboxes

2006-11-27T13:39:00.000-05:00

When the user needs to select a non-trivial number of items from a hierarchy, normal tree item selection is too prone to losing the selection through mistaken clicks. The standard solution to provide a more robust selection method is to include check boxes next to each selectable item in the tree.

Hat tip to some previous online implementations (each has a different implementation):

Bare bones

With a TreeCellEditor

More recent variations

After a couple of iterations of checkbox trees (and tree tables), I rolled this up into a standalone TreeCellRenderer so that it can be applied more easily to any tree-oriented component. This implementation also properly handles rollover effects on the checkbox, which is lacking in the above implementations (most visible under w32; Java's Metal LAF has no checkbox rollover effects).

The checkbox painting is handled by using a real checkbox and painting its contents into an icon. The state of the checkbox is set just prior to painting to ensure the proper rollover state. The original cell renderer's icon is replaced with a composite icon of the original plus the checkbox (hit ^-shift-O to switch component orientation).

The renderer provides the current checked selection as an array of TreePath or an array of int representing the rows.

I also applied this to my own tree table implementation (similar to SwingX JXTreeTable) by just overriding a few protected methods which translate mouse coordinates into rows/paths.

Source

Iconic Inversion

2006-10-10T21:46:00.001-04:00

Here's a problem and solution described in an applet.

The goal here is to make the icon look consistent with the selected text, which means using the JList's selection fg/bg colors where the icon uses the component's normal fg/bg colors.

This applet uses a SelectionIcon, which applies a custom composite to the original icon. The custom composite looks for the list fg/bg colors in the original icon (and some colors "nearby"), and swaps them out for the selection fg/bg. It also applies a slight tint based on the selection background.

The SelectionIcon can be applied to any existing icon. It's useful for selections because you don't know a priori what your selection colors are, so it's hard to make a dedicated selection version of your original icons that will look good in all cases. Assuming that the selection fg/bg are set reasonably, your icon will look at least as good as the selection text. The high contrast colors in the above example are from Win2k, but you never know what the user may have set.

Source

Animated Icon Redux

2006-09-15T19:55:00.002-04:00

Lately we've been putting animated icons all over the UI to provide feedback about actions that are in progress. The spinning arrows are an animated GIF, while the spinning dial is dynamically generated with Java2D. Both icons are used just like any other icon (set and forget). No special coding is needed to get them to animate. This is how animated icons should behave.

The Icon interface's paintIcon method carries enough information for the icon to trigger its own repaint when it needs to display the next frame. Internally, the spinning arrows icon tracks the component on which it was painted as well as the location. Using this information, each time we want to display a new animation frame, we just walk the list of repaint locations and request a repaint on each of the stored items.

After testing this method out on a variety of components, I realized that this would be a superior method of animating icons in trees, tables, and lists (or any other component that makes use of CellRendererPane. With just a few tweaks, the logic was refactored to wrap animated GIF icons so that when they are used within a tree, table, or list, they are automatically refreshed as necessary. This is a much cleaner solution than the one I posted earlier.

I have a generic icon loader for my apps, so if the loader detects an animated GIF, it automatically wraps it in an AnimatedIcon and I don't have to worry about manually tracking animations.

Source

Swing Drag Images, Improved

2006-08-30T10:55:00.000-04:00

Performance is improved, generating the drag image once instead of repeatedly.

Source

Drop Target Navigation, or You Drag Your Bags, Let the Doorman Get the Door

2006-08-12T09:16:00.001-04:00

When I'm dragging a 75lb bag and a five year old, it's rather nice to have someone open the door. When I'm dragging things around in my application, it's also nice not to have to open all the doors on the way to my destination before I start dragging.

Specifically, I've got a set of forms in an instance of JTabbedPane. I know one of the tabs holds a field that defines my preferred download directory, which I happen to have open in my file browser. Drag from the file browser onto the JTabbedPane, and -- oops, I'm not on the right pane. It'd be nice to have the tabs change as I drag across them so that I can find the right destination.

Since this is system-wide behavior, I'd like to enable the behavior once at application startup and forget about it, rather than having to add listeners or subclass every instance of JTabbedPane and JTree that's going to accept a drop.


DropTargetNavigator.enableDropTargetNavigation();

In order to make this happen, we install a global listener to the default DragSource, which lets us respond to any drags initiated within the same VM. Since that provides us with the current drag location, we can scan through the currently available components using Frame.getFrames() and SwingUtilities.getDeepestComponentAt() to see if what's under the cursor needs to be navigated. If we do make a modification, a Runnable which will undo the modification is added to a queue so that we can restore the component to its original state if the drop ends up going somewhere else or being canceled.

To handle drags originating from outside the VM requires a little hacking, since there isn't any sort of global drop target listener. During a native drag, you won't see any MouseEvents. As of 1.4+, there is a MouseEvent (actually a SunDropTargetEvent) that gets processed by Component.dispatchEventImpl(), but it gets swallowed before the component passes events off to AWTEventListeners. You can't override dispatchEvent, and wouldn't want to anyway because you'd have to do it on every component. Instead, we can install a custom EventQueue which can watch for the drop target events and forward them to our drop target listener.

The navigator class has built-in support for JTabbedPanes and JTrees. Custom classes that wish to support navigation can register themselves with a simple interface that performs custom navigation and rollback. This way you can enable auto navigation on whatever tree table implementation you happen to be using.

In order to avoid unintended navigation when the mouse is dragged rapidly across a component, I've added a configurable delay to when the navigation starts. You need to hover over the same spot for roughly half a second to activate the navigation.

Mighty Mitochondria! Them Cells Are Animated!

2006-08-08T13:52:00.000-04:00

Java provides effortless loading and display of animated GIFs. Just tell ImageIcon where it can find the file, then plug the ImageIcon into a JLabel or JButton. Couldn't be simpler.

Now how about putting that animated icon into a JTree as feedback for loading status.

Oops. What happened? Did we get the right icon? Why isn't it animated? Try selecting one of the tree nodes, then rapidly move the selection up and down. Watch what happens.

What happened is that no one told the JTree it needed to repaint itself after it painted the initial image. Selection changes trigger repaint messages, which is why the icons move a little bit when you move the selection around. Any animation is driven by regular repaints of the component where it is drawn. JLabels and JButtons are no exception. Take a look at the source for ImageIcon.paintIcon:


public synchronized void paintIcon(Component c, Graphics g, int x, int y) {
    if(imageObserver == null) {
       g.drawImage(image, x, y, c);
    } else {
       g.drawImage(image, x, y, imageObserver);
    }
}

When you create your ImageIcon, it doesn't have an image observer, so the component where it's being drawn is used instead (note that java.awt.Component implements ImageObserver):


public boolean imageUpdate(Image img, int infoflags,
                           int x, int y, int w, int h) {
    int rate = -1;
    if ((infoflags & (FRAMEBITS|ALLBITS)) != 0) {
        rate = 0;
    }
    // ...
    if (rate >= 0) {
        repaint(rate, 0, 0, width, height);
    }
    return (infoflags & (ALLBITS|ABORT)) == 0;
}

So whenever the image reports that it has another frame ready (infoflags&FRAMEBITS != 0), it calls this method.

That's just fine for a label or button which only displays a single icon, but what about a tree, which might display this icon in every row? We need an image observer which can call repaint with the cell bounds of every cell that contains the animated icon. Using the tree itself as the observer could work, but we'd end up redrawing the entire tree on every frame. It's preferable to use a decorator which keeps track of which individual cells need updating.

In this case, let's use the tree cell renderer as the entry point or trigger to start or stop animation, since that's normally where a tree's icons get customized.


JTree tree = ...;
TreeCellRenderer r = new DefaultTreeCellRenderer() {
    public Component getTreeCellRendererComponent(JTree tree, Object value, 
                                                  boolean selected, boolean expanded,
                                                  boolean leaf, int row, boolean focused) {
        Component c = 
            super.getTreeCellRendererComponent(tree, value, selected, expanded, 
                                               leaf, row, focused);
        TreePath path = tree.getPathForRow(row);
        if (isLoading(path.getLastPathComponent()))
            setIcon(LOADING_ICON);
        // The following line is what you'd normally use; the rest is just illustrative
        //CellAnimator.animate(tree, c, path); 
        // Let the CellAnimator utility figure out if there's an animated icon here
        ImageIcon icon = (ImageIcon)getIcon();
        if (CellAnimator.isAnimated(icon)) {
            CellAnimator.animate(tree, new CellAnimator.TreeUpdater(tree, row), icon);
        }
        else {
            CellAnimator.stop(tree, row);
        }
        return c; 
    }
};
tree.setCellRenderer(r);

The CellAnimator needs to do several things. At any point if it is determined that no animation is required, the animation support is disposed for the current location.

Obtain the icon in use, if any
If the icon is animated, install an ImageObserver
Identify the location to receive repaint notifications, and add it to the observer's list

Whenever the animated icon posts an update, the ImageObserver for that icon will walk its list of repaint locations and trigger repaints. The actual implementation takes care of a number of other details, like using weak references for UI components and remove locations if the location or component is no longer valid.

The CellAnimator provides one-line methods to enable animation on standard Swing components and is easily extensible to enable animation on custom components that use the cell renderer technique.

Here is a demo of the cell animator applied to a lazy-loading tree.

The source includes JUnit-based unit tests which use the Abbot library.

UI Testing on the Sly

2006-08-04T11:33:00.000-04:00

One of the drawbacks of testing your UI components (you are testing them, right?) is that to properly run a test, it needs to run on a display. Unfortunately, if you want to use that display for something else (like writing code and fixing bugs), you run into problems with either the tests writing your code, or the code you're writing supplying input to your UI tests.

One good solution is to have a dedicated machine for the tests, which you can continually monitor and can easily be updated with changes from your dev machine. Since that isn't always an option, I'll present a few alternatives for several different platforms which allow you to run UI tests without having a separate machine to run them on.

OS X

VNC is a great tool for controlling remote computers of any platform. If you have fast user switching enabled, you can actually use OSXvnc to display the desktop for a user other than the one currently using the display. If you configure OSXvnc to not quit when switching to another user, you will always be able to connect to the desktop where OSXvnc was first launched.

Set up a "test" user, and set up OSXvnc to launch when that user logs in. Set up the "Startup" tab like this:

Once OSXvnc is running, you can access the "test" desktop while using your normal desktop. Run your tests in the background, peek in on them to check the results.

Linux

Run vncserver, either manually or as a daemon. This will give you an additional X display which is totally separate from your physical one. Connect to the new display with vncviewer, and you have a window onto your "test machine".

Windows

Windows isn't quite as functional when it comes to sharing a display, but you can still get some mileage out of UI testing on the same machine. There's a peculiar little mode in windows, I'll call it "service mode", where you think you have a display but you don't. This prevents java.awt.Robot from working properly, but you can still get some mileage from UI tests that don't depend on screen captures or native drag and drop. Abbot (a UI testing library) will work just fine in this mode, and does so by artificially generating events directly into the AWT event queue in order to drive a UI.

The easiest way to run tests in this manner is to install cygwin sshd. It runs as a service, so by default it doesn't have access to the desktop (there is a checkbox in the services admin control panel that indicates whether a service is allowed desktop access). Once that is installed and configured (google "cygwin sshd install"), you can use ssh to get a shell prompt within the service mode "sandbox". If you've got an ant script to run your tests, just invoke it. Abbot automatically detects whether this mode is in effect, so if you're using that library, everything works out of the box. If you only run your tests interactively through an IDE, you're out of luck, since you won't be able to interact with the IDE if you launch it in service mode.

Drag Images for Everyone...and we do mean Everyone

2006-07-17T20:40:00.000-04:00

You may have seen Sun's tutorial on using Swing's built-in drag and drop support. One of the demos from the tutorial looks like this:

or:hand;width: 320px;" src="http://java.sun.com/docs/books/tutorial/figures/uiswing/misc/BasicDND.gif" border="0" alt="" />

Today's demo puts a drag image on each of the displayed drag-enabled components, and does so without modifying the original jar file. It also does so without any special knowledge of the components that are drag enabled. (Web start doesn't let you reference a file on another host, so you'll have to trust me when I say the original jar is used unmodified).

A few sights to take in after you've checked that "Turn on Drag and Drop" checkbox.

Try a drag from each component.
Try dragging a multiple, discontiguous selection from each component.
Watch what happens when your drop is rejected.
Move the main window, and drag some more. Notice the nice images across both windows (the original main has simply been called twice).

Source Here.

The technique depends on all drag sources to use the default DragSource as the drag initiator. To date, all drags implemented within the JRE use the default, as do all the drag & drop examples I've seen on the web, so it always works in practice.

The global drag source listener technique used here could also be used to automatically switch the visible tab in a JTabbedPane, expand a node in a JTree, or even autoscroll components that don't implement Autoscroll. Watch for an upcoming article to address those options.

Bugs in the Library

2006-07-11T18:20:00.000-04:00

One of the great benefits of Java is the availability of a wide variety of libraries providing all sorts of functionality. However, managing bugs, workarounds, and fixes becomes more complicated when tracking multiple third-party libraries.

With a simple source code base or a single application, it's relatively simple to take library updates to get bug fixes, or even to apply patches to a local copy of a library. There are many situations where this isn't possible and you need to determine for a given section of client code whether a bug is present. One codebase may need to support several VM releases and what's a workaround in one may introduce a bug in another.

I keep track of library-based bugs with a class Bugs which comprises static methods which check the environment for the presence of a given bug. For instance, Mac OSX between Java releases 1.4 and 1.5 incorrectly mapped mouse button events generated by java.awt.Robot. So Bugs would have a corresponding method,


// This bug has been submitted to Apple, bug #XXXXXXX
// It was officially fixed in version 1.5
public static boolean hasRobotButtonSwapBug() {
    return Platform.isMac() && Platform.JAVA_VERSION >= 0x1400
        && Platform.JAVA_VERSION < 0x1500;
}

The method contains checks which describe as precisely as possible the environment where the bug is present. In this case, several java releases were tested; the bug first appeared in the Java 1.4 release and persisted until 1.5. The method should narrowly identify only those environments shown to produce the bug (see below).

In the corresponding BugsTest, we implement a method which actually checks for the bug. This serves several purposes. First, it provides a test case to submit along with a bug report to whoever is responsible for the bug. Second, it provides a standard check when used with other automated tests to flag changes in released libraries. Checking the "bug presence" method at the start of the test avoids test failures where we already know the bug exists, and tests for its presence in any environment we haven't yet tested. A system property may be set to force running the test.


public void testRobotButtonSwapBug() throws Exception {
    // skip the test if we already know the bug exists, unless forcing a bug check
    if (!Boolean.getBoolean("check_all_bugs") || hasRobotButtonSwapBug()) return;
    // perform tests to reproduce the bug
    final List events = new ArrayList();
    Robot robot = new java.awt.Robot();
    Window w = new Window();
    w.add(new JLabel("Swap test"));
    w.addMouseListener(new MouseAdapter() {
        public void mouseClicked(MouseEvent e) {
            events.add(e);
        }
    });
    showWindow(w);
    Point where = w.getLocationOnScreen();
    where.x += w.getWidth()/2;
    where.y += h.getWidth()/2;
    robot.mouseMove(where.x, where.y);
    robot.mousePress(InputEvent.BUTTON2_MASK);
    robot.mouseRelease(InputEvent.BUTTON2_MASK);
    robot.waitForIdle();
    assertEquals("Robot generated incorrect button event for button 2",
                 InputEvent.BUTTON2_MASK, 
                 ((MouseEvent)events.get(0)).getModifiers());
    // and so on...
}

With each new library release, the test is run. If it fails with a new version or a new platform, extra checks can be added to the method in Bugs.

The Bugs method test can now be used in client code to determine whether workarounds need to be applied. Such checking allows the client code to be used consistently regardless of the environment in use on the project where it is used. If you release an application that runs on Java 1.2 and above, you may need to selectively apply workarounds depending on the actual JRE in use by a user. In the example above, a workaround to swap button definitions was applied (and still is) if the user happens to be using the affected Java release on OSX.

This pattern makes bug checks and workarounds very explicit. Compare these two implementations. First, the ad hoc workaround:


JTree tree;
...
// tree row size isn't updated automatically, so hack it
tree.setRowSize(tree.getRowSize());
tree.revalidate();
tree.repaint();

Or this, which is only slightly more structured, but entirely clear in intent. You can also tell exactly what code can go away when the bug does:


JTree tree;
...
if (Bugs.hasTreeRowSizeUpdateBug()) {
    tree.setRowSize(tree.getRowSize());
    tree.revalidate();
    tree.repaint();
}

The code explicitly identifies a bug that has been at least partially analyzed, and indicates workaround code. If a programmer needs further information on the bug, she can just look up the corresponding information in Bugs or BugsTest

Fancy Drops

2006-06-28T09:59:00.000-04:00

Just run the demo.

Again, a very simple method override to enable drop target functionality. Paint a marquee on the full list if it's empty, otherwise mark a space at the end of the list. Most of the code is just futzing with the data model on a drop or moving/sizing the decoration.


JList list = ...;
DataFlavor[] acceptableFlavors = { DataFlavor.stringFlavor };
new DropHandler(list, DnDConstants.ACTION_COPY, acceptableFlavors) {
    private Marquee marquee;
    /** Always drop at the end of the list. */
    protected void drop(DropTargetDropEvent e, int action) throws UnsupportedFlavorException, IOException {
        final List data = new ArrayList();
        for (int i=0;i < list.getModel().getSize();i++) {
            data.add(list.getModel().getElementAt(i));
        }
        data.add(e.getTransferable().getTransferData(DataFlavor.stringFlavor));
        list.setModel(new AbstractListModel() {
            public int getSize() {
                return data.size();
            }
            public Object getElementAt(int index) {
                return data.get(index);
            }
        });
    }
    protected void paintDropTarget(DropTargetEvent e, int action, Point location) {
        if (action != DnDConstants.ACTION_NONE && location != null) {
            if (marquee == null) {
                marquee = new Marquee(list);
            }
            int count = list.getModel().getSize();
            if (count == 0) {
                Dimension size = list.getSize();
                marquee.setDecorationBounds(new Rectangle(0, 0, size.width, size.height));
            }
            else {
                Rectangle r = list.getCellBounds(count-1, count-1);
                r.y += r.height;
                marquee.setDecorationBounds(r);
            }
        }
        else if (marquee != null) {
            marquee.dispose();
            marquee = null;
        }
    }    
};

Compare that API with the raw D&D APIs (which are still available to override in DropHandler, by the way):

// DropHandler
void drop(DropTargetDropEvent e, int action);

// DropTargetListener
void dragEnter(DropTargetDragEvent);
void dragOver(DropTargetDragEvent);
void dropActionChanged(DropTargetDragEvent);
void dropExit(DropTargetEvent);
void drop(DropTargetDropEvent);

Most of the complexity comes in figuring out the appropriate sequence of calling back methods on the DropTargetEvents, which communicates whether a drag is acceptable and if so, which action is actually to be accepted. This could be clarified a great deal in the Javadoc APIs, or by a thorough example, but ultimately it's boilerplate code that rarely, if ever, needs changes to its behavior.

Back to the example. The JTree drop handler code is more complex, but only to determine what should happen when dropping on any given location. Non-leaf nodes accept drops, but leaf nodes refuse drops, and the spaces between leaf nodes accept drops.

Some DropHandler features:

Automatically get the copy action when it's the only one allowed
Automatically disable user actions which are not allowed
Some parts of the drop target allow drops, some don't
Paint any drop target indication you please, regardless of the target component (no subclassing of components)

Usually, in order to get non-trivial drop target painting, you have to override one of the target component's paint methods and invoke paintImmediately within the drop handler. That's avoided by use of a decorator, which uses the existing component hierarchy and layout to paint over the target component. The Marquee class uses a dashed stroke to draw a rectangle. A timer regularly increases the phase and triggers a repaint, which gives the "marching ants" effect.

Unfortunately, you still have to make the component implement Autoscrolls, although you could probably call the methods yourself from within the drop handler. It'd be nice if the D&D code which calls into the Autoscrolls interface instead looked for a client property. That functionality could probably be implemented in the DropHandler.

Next step: hook this up to the list and tree animators.

Dead Simple Drags

2006-06-27T14:30:00.000-04:00

Here is a demo of usage of the Drag & Drop Library, which provides D&D support on top of Java's basic D&D in much the way Xt provided toolkit functionality on top of X11.

Here is the code to add drag handling to a JLabel:

final JLabel label = new JLabel("Drag Me");
label.setBorder(BorderFactory.createEmptyBorder(4,4,4,4));
new DragHandler(label, DnDConstants.ACTION_COPY) {
  protected Transferable getTransferable(DragGestureEvent e) {
      return new StringSelection(label.getText());
  }
  protected Icon getDragIcon(DragGestureEvent e, Point offset) {
      return new ComponentIcon(label, true);
  }
};

The only thing absolutely required by the API is getTransferable. However, overloading getDragIcon will automatically give you a nice ghosted drag image, regardless of whether your platform supports one natively (the ComponentIcon used to render the JLabel is just a simple class which renders its given component as an icon).

Drag and Drop has been in Java since version 1.2 when a functional but very complex set of interfaces was introduced. Compare the previous DragHandler interface for dragging with the following interfaces, which must be implemented carefully to get consistent results (note also the conspicuous absence of any methods which explicitly indicate the data to be dragged):


// DragGestureListener
void dragGestureRecognized(DragGestureEvent);
// DragSourceListener
void dragEnter(DragSourceDragEvent);
void dragOver(DragSourceDragEvent);
void dropActionChanged(DragSourceDragEvent);
void dragExit(DragSourceEvent);
void dragDropEnd(DragSourceDropEvent);
//DragSourceMotionListener
void dragMouseMoved(DragSourceDragEvent);

Not a trivial thing to get right, especially without an in-depth understanding of how the system works. Not something I'd expect of every developer. Unfortunately, there is no abstract implementation to provide a base level of functionality or useful example (I'm sure everyone has at least looked at Rockhopper or JavaWorld for functional examples). These examples provide working implementations, but not one that makes extension or reuse clear and simple. Sun has tried to make D&D simpler by introducing the TransferHandler and setting up default drag and drop handlers on Swing components. I consider the TransferHandler a mistaken attempt to merge two operations that just happened to have a little functionality in common. Copy and drag both need to produce a Transferable, and Paste and drop both need to absorb a Transferable, but the edit actions operate in a sufficiently different manner that merging the two doesn't really buy you much in practice.

Copy/paste actions are fairly trivial to construct in the first place, and the clipboard transfer is a few lines of boilerplate.

Drag and drop, on the other hand, is a lot more lines of boilerplate, some of which can introduce subtle differences in behavior if you don't get it just right.

Back to the library. An example on a JTree is a bit more involved, but only because you now need to choose which part of the JTree is going to be dragged. For illustrative purposes, I've disabled dragging of non-leaf nodes, and enabled dragging of the entire tree if you drag outside of any rows. I futz with the ComponentIcon to draw either the whole tree or just one row, as needed. You could conceivably construct a drag from a multiple selection by painting the whole tree but adding an appropriate clipping mask when painting the icon.

final JTree tree = new JTree();
// Turn off selection of rows by dragging
tree.setDragEnabled(true);
// Turn off built-in swing drag handling
tree.setTransferHandler(null);
new DragHandler(tree, DnDConstants.ACTION_COPY) {
  protected boolean canDrag(DragGestureEvent e) {
      Point where = e.getDragOrigin();
      int row = tree.getRowForLocation(where.x, where.y);
      if (row != -1) {
          TreePath path = tree.getPathForRow(row);
          return tree.getModel().isLeaf(path.getLastPathComponent());
      }
      return true;
  }
  protected Transferable getTransferable(DragGestureEvent e) {
      Point where = e.getDragOrigin();
      final int row = tree.getRowForLocation(where.x, where.y);
      if (row == -1) {
          return new StringSelection("full tree");
      }
      Object value = tree.getPathForRow(row).getLastPathComponent();
      return new StringSelection(String.valueOf(value));
  }
  protected Icon getDragIcon(DragGestureEvent e, Point offset) {
      Point where = e.getDragOrigin();
      final int row = tree.getRowForLocation(where.x, where.y);
      if (row != -1) {
          Rectangle r = tree.getRowBounds(row);
          offset.setLocation(r.x, r.y);
      }
      return new ComponentIcon(tree, true) {
          public void paintIcon(Component c, Graphics g, int x, int y) {
              g = g.create();
              if (row != -1) {
                  Rectangle r = tree.getRowBounds(row);
                  g.translate(-r.x, -r.y);
                  g.setClip(new Rectangle(x+r.x, y+r.y, r.width, r.height));
                  super.paintIcon(c, g, x, y);
              }
              else {
                  super.paintIcon(c, g, x, y);
              }
              g.dispose();
          }
      };
  }
};

Again, this implementation doesn't have to worry about any of the mechanics of drag and drop. The implementation decides whether an item can be dragged, what the dragged item looks like, and what is the appropriate Transferable. This API hides all the boilerplate, but you can still get access to the basic Java D&D API if you need to, if for some reason you need to augment or override dragOver or dragGestureRecognized.

Next installment will demonstrate the DropHandler, which facilitates decorating your drop target as well as accepting or rejecting incoming data.

Source.

Decorator Update

2006-06-26T13:21:00.000-04:00

This fixes some display glitches that showed up on X11-based systems. The decorators are also properly clipped (or not) if they extend beyond the target component bounds. This showed up with the marquee, which would get clipped by a scroll pane that was not an ancestor.

Source

Navigating Large Spaces

2006-06-15T23:49:00.000-04:00

This example demonstrates one method of providing a navigational element for traversing a large, scrolled component. Like Apple's Expose, it's entirely out of the way until you need it.

This implementation combines several effects. First, a ComponentIcon class renders any given target component as an icon. Second, a ScaledIcon is used to resize the ComponentIcon to fit within the desired space. The Panner composes the two icons and paints a border, indicates the visible sub-rectangle, and responds to navigational input (mouse events). Finally the PannerHandler handles showing, hiding, and resizing the panner in response to user input.

ComponentIcon
This is pretty simple. The main thing to watch out for is that you need to turn off double buffering on the target component, or the rendering ends up having odd side effects on the rest of the display. The underlying component's "isShowing" method must return true, otherwise Swing will short-circuit its painting (there are other methods for getting a component to paint which is not currently in the visible hierarchy).

ScaledIcon
This class takes any other icon, scales and translates the Graphics object so that the delegate icon fits within its allotted size, then delegates to the other Icon to paint. Aspect ratio is preserved by default, but that can be turned off if you want to stretch to fit the available space.

Panner
This is a lightweight component with optional transparency (so that you can optionally position it over the panned component and have the underlying component show through). It passes through the "preserveAspectRatio" property to the ScaledIcon.

PannerHandler
This class takes care of the details of deciding where and when to show the panner. It also sets the size appropriately (the example uses a percent value against the size of the panned component, and a fixed offset from the UL corner). Essentially this is the class responsible for configuring all the other classes and hooking them together. It installs a ComponentListener to update the panner size and position whenever the panned component is resized or moves (i.e. is scrolled).

It's possible to attach the panner itself to the panned component (so you get a thumbnail in a corner of the pane) or have it appear in its own window. The panner size can span the entire visible viewport or some fraction thereof. You can also indicate which corner of the visible viewport to use as anchor if the panner is smaller than the visible viewport.

Context-sensitive Edit Menu

2006-05-26T23:01:00.000-04:00

Most applications have an "Edit" menu where our friends "Cut", "Copy", and "Paste" hange out. In any non-trivial application, there are certainly more than one thing to which those operations might apply. How can we hook up these friendly edit operations without having to know beforehand everything that might be Cut or every component that might accept a Paste?

Permission is required in order to access the system clipboard.

Let's take a simple example, which displays two JLists. The JList supports a copy action (via its LAF TransferHandler, if you're curious). You can retrieve the action from its ActionMap. The ActionMap is supported by all JComponents, and is basically a pool of all Actions that the component supports. How best to make Edit->Copy (or any other menu item, for that matter) invoke the corresponding action from the appropriate JList? Note that handling a keyboard shortcut is already taken care of by the JList's InputMap, which maps keystrokes to actions in the ActionMap.

First, let's define context to be what component has focus. This may not always be true, but given that keyboard input goes where the focus is, it's reasonable to assume that focus indicates the proper current context.

If all we wanted to do was support mapping a keyboard shortcut to an action, we'd have nothing to do, but we'd like to actually make Edit->Copy do the same thing as that keyboard shortcut. A quick and dirty hack might be to have the menu item generate a fake keystroke sent to the currently focused component, but that only works if the target action has a keystroke associated with it. But that's kind of indirect and doesn't smell very good.

What if the Edit->Copy menu item reflected a sort of delegating action, whose actionPerformed logic simply called some other action. Whenever the context (i.e. focus) changes, we check the focused component's ActionMap for a copy action. Whatever we find, we set as the delegate of the delegating action. If there is no copy action, then the delegating action sets itself disabled.


public class DelegatingAction {
    public DelegatingAction(String name) { super(name); }
    public void setDelegate(Action a) { 
        delegate = a; 
        setEnabled(delegate != null);
    }
    public void actionPerformed(ActionEvent e) {
        if (delegate != null) { delegate.actionPerformed(e); }
    }
}

To actually look up the delegates, we can store one or more keys which can be used to identify the actions in the target components. For custom-defined actions, you can set your action keys to whatever is appropriate. In order to handle Swing built-in edit actions, we have to account for a few variations. TransferHandler uses hard-coded strings "cut", "copy" and "paste", while text components use a few string constants defined in DefaultEditorKit, which are different from the TransferHandler strings (e.g. "copy-to-clipboard"). Since these variants exist, we need to check for all of them, since they all correspond to the same Edit menu items.

To know when to update the delegate's mapping, we can install a property change listener to the keyboard focus manager (available in 1.4+ JREs). We only want to look at permanent focus changes, so listen to "permanentFocusOwner".

There's an unexpected glitch caused by the fact that the TransferHandler edit actions are singletons shared across all transfer handlers. As such, they expect to deduce the target of the edit operatoin from the ActionEvent source. In order to work around this, the delegating action must also keep track of the current component context so that it can reformat the ActionEvent to have the proper source.

The singleton implementation also means that the actions' enabled state doesn't reflect whether the target component can actually process the action. Copy should be disabled if nothing is selected, and paste disabled if the component is not editable. Leave that to a future article...

In practice I use a system that's a little more general (it can auto-populate dynamic menus and submenus, and listens for changes on a per-menubar basis instead of per-action, which makes GC a little easier).

Source is here.

Animated Tree Update

2006-05-25T17:29:00.000-04:00

I've fixed a few bugs and enabled horizontal drags to change the depth in the hierarchy where the drop target is ambiguous. Children now slide out from under the parent on expansion, rather than over the parent.

Other things that might be nice to do:

Handle drags from outside the component
Auto-expand collapsed folders
Animate canceled drops
Smooth horizontal transitions

My Drag Image is Better than Yours

2006-05-23T16:43:00.000-04:00

While tinkering with getting suitable ghosted drag images to show up on w32 and linux, I thought I'd whip out the old component decorator yet again, not just to display the drag image, but to display it over any java window that might be receiving a drop. The effect isn't required on OSX (since it already knows how to display a drag image anywhere on the display), but in all cases the same drag handler method is used for generating the actual drag image.

I got started in this drag/drop business because I needed to display different animations and/or decorations under the cursor on a tree table. You know, highlight the folder if you can drop in the folder, show an insertion line to insert between two things. The AbstractComponentDecorator was born to handle the highlighting/decoration without having to subclass or otherwise modify the underlying drop target.

The built-in swing drag and drop makes some things easier, but also hides some of the power of raw DnD. Its drop target highlighting (temporarily changing the selection) is just a programming shortcut, not a real design for marking a drop target area. the TransferHandler system used for Swing DnD solves a particular problem in a specific way, but for practical purposes, is not extensible. It does a nice job of consolidating some drag/drop and clipboard support, but it is really hard to change its behavior.

Fundamentally, you don't really need to specify much to define a drag and drop operation:

Indicate the types of actions supported (based on a drag gesture and drag location)
Identify a Transferable (data to be dragged) based on a drag gesture and drag location
Provide a drag image/image offset for feedback while dragging
Indicate the types of actions and data (DataFlavor) supported for drop, possibly refined by actual drop target location
Provide drop target feedback based on current drop target location and effective action

The base implementation should handle the following, allowing modification of the default behavior if necessary:

Detect drag gesture and user-requested action, if any
Provide a drag image under the cursor for feedback
Determine the effective action based on the user, source, and target
Set/update cursor to standard platform cursors based on the effective action
Invoke methods to update the state as the effective action changes, handle drop, etc.

Basic DnD leaves you to perform all of these tasks, while Swing DnD performs most of them but doesn't allow you to override the behavior. I wrote a pair of classes to hide the complexity but leave the base DnD functionality available if needed. The simplicity is that based on a drag location, you just provide a Transferable and optionally an Icon to represent the item being dragged (which can be the whole component or some small part of it). The supported drag actions are indicated in the constructor. The primary methods to be defined on the DragHandler follow:


    protected boolean canDrag(DragGestureEvent e);

    /** Override to provide an appropriate {@link Transferable}.
     */
    protected abstract Transferable getTransferable(DragGestureEvent e);

    /** Override this to provide a custom image. 
     * @param offset set this to be the offset from the drag source origin 
     * to the image origin.  If unchanged, the image is assumed to have the
     * same origin as the drag source.
     */
    protected Icon getDragIcon(DragGestureEvent e, Point offset);

For the DropHandler, just a few methods are required. Painting the drop target is optional and does nothing if not overridden, but that allows you to paint insertion lines, tint the target, or anything else that might be appropriate (decorators are useful for this purpose):


    protected abstract boolean isSupported(List flavors); 
    /** Update the appearance of the target component.  Normally the decoration
     * should be painted if the event is an instance of 
     * {@link DropTargetDragEvent} and cleared otherwise.
     */
    protected void paintDropTarget(DropTargetEvent e, int action); 
    /** Indicate whether the drop is acceptable. */ 
    protected boolean canDrop(DropTargetDropEvent e, int action);
    /** Handle an incoming drop.  */
    protected void drop(DropTargetDropEvent e, int action);

I also needed more control and feedback over user modifiers. Basic DnD simply performs a logical AND of the source, user, and drop target actions. In our app, we support moves, copies, and links. If the user is requesting a link by holding a modifier, you most definitely don't want to move or copy just because link is unsupported but move or copy is (which is the default drag/drop behavior, BTW). In addition, if the user doesn't use any modifiers, the application should be free to select the most appropriate drop operation based on the context. The cursors are automatically set to whichever appropriate for the platform, although you can still easily change that behavior if necessary.

Finally, drag image ghosting has been done to death (see Java Tip 114), but I wanted to have the drag image appear not just in the drag source, but every possible (java) drop target. I managed to get pretty close, probably as close as you can without resorting to native code (see the demo).

Source here. The main class was derived from the JUnit tests for these classes, so it looks a bit crufty.

Smooth Tree Drop Animation

2006-05-07T23:21:00.000-04:00

Here's an updated tree drop animation demo. The base class can be applied to any tree, and if you're using a DefaultTreeModel with MutableTreeNodes, you don't even have to subclass. Web Start demo:

This starts to get complicated, what with having multiple possible targets and behavior for a dragged node, so I started a JUnit test case around the main class. Note that none of the tests actually requires displaying the UI. I usually keep around a testReveal() method though, since often it's nice to do exploratory testing, or simply to get a feel for the component's response.

The horizontal drop location now reflects the appropriate indentation level based on the target parent node. Still needs to track horizontal drag motion, since currently if you're at the end of a few nested nodes, you can't insert at the end of the parent node of your choice.

I started to implement spring-loaded non-leaf nodes (so when you drag over a non-leaf it auto-expands), but the actual implementation has some details to consider, such as whether to collapse auto-expanded nodes and if so, non-disruptively. If you collapse anything above where the user is dragging, the whole tree shifts upward, effectively dragging the tree under the cursor.

A nice side effect of handling expansions is that now when you expand a tree node, the children sort of slide out of the parent in a pleasing manner.

Source for smooth tree drop animation and tests.

Of Swing Frameworks and threaded Actions

2006-05-05T12:18:00.000-04:00

I've been trying to come up with an implementation that properly encapsulates the most common cases of triggering, tracking, and responding to the results of a long-running operation from a Swing UI. If the JSR for a Swing app framework produces nothing else, it should address this issue, given its ubiquitousness with AWT's single-thread model.

Basically, you have this:

User trigger (button, menu, drop)
Collect information from the UI
Switch to another thread
Perform processing
Update the UI (success or failure)

Ideally, I'd like to just write straight code:


public void actionPerformed(ActionEvent e) {
    Object[] o = list.getSelectedItems();
    try {
        Object result = processObjects(o);
         list.setSelectedItem(result);
    }
    catch(CanceledException e) {
         // ignore the results
    }
    catch(Exception e) {
        list.setSelectedItem(null);
        status.setText("Error: " + e.getMessage());
    }
}

Which makes it very clear what's going on. However, as anyone who has used Swing for more than five minutes is aware, this makes your UI freeze for the duration of the operation.

I'd prefer an idiom that looks as close as possible to the original code, perhaps an "executor" block:

public void actionPerformed(ActionEvent e) {
    Object[] o = list.getSelectedItems();
   try {
       Object result = null;
       Handle handle = execute-off-edt {
           result = processObjects(o);
       }
        list.setSelectedItem(result);
    }
    catch(CanceledException e) {
       // ignore the results
    }
    catch(Exception e) {
       list.setSelectedItem(null);
       status.setText("Error: " + e.getMessage());
    }
}

This idiom would let me transparently collect inputs and pass them to a threaded invocation without a lot of messy assignments (which do absolutely nothing to communicate what the code is trying to do). The handle would give me some sort of control over the spawned thread. And when the thing is done or fails, I don't have to do messy assignments to get its results. It's the sort of thing that Java's anonymous inner classes overcome; it's syntactic sugar, but it sure as hell simplifies how the code looks.

Spinplays some neat tricks with interfaces and proxies to let you use something close to this idiom (as do FoxTrot and SwingWorker, albeit less elegantly), but it has some unfortunate restrictions . For instance, if you start a Spin invocation from a mouse press event handler, the mouse release event is likely to be processed during your long-running method, and the rest of the mouse press handling will happen after the mouse release handling.

The reason the idiom above can'tbe used as is, is that in order for the event dispatch processing to continue, the current method needs to return immediately. This is the Spin issue. If you don't return, then you may have event handlers that haven't run yet, and end up running out of turn. I doubt that part of AWT is going to change, so I have to look at variations of the idiom instead.

So I've been playing around with a code pattern that handles the before/during/after pattern, including thread-hopping, cancelation and failure. It's probably not universal, since there are some situations it fits much better than others. I've put it in the form of a javax.swing.Action, since that's a pretty common method of triggering actions in Swing.


abstract class AsynchronousAction {
    public void actionPerformed(final ActionEvent e) {
        preInvoke(e);
        // could use Executor here; implement the before/during/after pattern
      // so you don't have to reimplement it on every action
        new Thread() {
            public void run() {
                Throwable failure = null;
                try {
                    invoke(e);
                }
                catch(Throwable e) {
                     failure = e;
                }
                   SwingUtilities.invokeLater(new Runnable() {
                         public void run() {
                        postInvoke(failure);
                         }
                   });
            }
        }.start();
    }
    /** Change/update UI state here, collect input */
    protected abstract void preInvoke(ActionEvent e);
    /** Invoked from a non-UI thread. */
    protected abstract void invoke(ActionEvent e);
  /** Invoked when everything happens normally. */
    protected abstract void postInvoke();
    protected void handleFailure(Throwable failure) { }
    protected abstract void postInvoke(Throwable failure) {
        if (failure == null) postInvoke();
        else {
           handleFailure(failure);
        }
     }
  }

I've left out the "cancel" functionality (and automatic disabling while the action is active) for clarity (using thread local variables, the spawned thread can check whether it should bother continuing or reporting its results).

So this works pretty well for, say, a "navigate" method which loads some data from a remote source and displays it. I can cancel the current one and invoke it with a different target. Any canceled action never reaches the postInvoke() method, so I don't have to explicitly add and remove listeners to yet another listener interface. It gets a bit clunky when there's a lot of data to pass to the invoke() method. Where you'd like to just pass parameters, you have to store in member data, which introduces synchronization problems when dealing with multiple invocations.

And now on a tree...

2006-05-01T07:22:00.000-04:00

Here's a quick edit of the smooth list drop applied to a JTree. It doesn't actually handle the drop - it still needs to implement changes to the tree model.

It looks best with a LAF that displays vertical lines, since the lines get stretched as space is made for the insert (OSX doesn't draw connector lines :().

Web Start.

(There was a race condition in the animator in the first posting which would sometimes lock up; thanks to ploiku for the stack trace).

A full implementation for the tree would need to have a few abstract methods defined:


boolean canMove(TreePath src);
boolean canMove(TreePath src, TreePath newParent, int index);
void move(TreePath src, TreePath newParent, int index);

You'd probably want to collapse a non-leaf when dragging it, allow drops onto collapsed nodes, auto-expand collapsed nodes after a delay, and probably a few other things I haven't thought of. Too much for one afternoon, drat.

Smooth JList Drop Target Animation

2006-04-30T10:48:00.000-04:00

Web Start and source.

I ran across this nice effect for indicating a drop target in a JList. The ghosted image of an item dragged from the list appears to push aside other entries as it moves through the list of items. A very simple method results in very smooth animation that can span several cells at once. The basic idea is to maintain a list of current positions for all cells, and gradually adjust those positions to match what their final positions would be with a proposed insertion. The animation consists of moving half the distance from the current to the final position (rounding up the final pixel difference). The problem with the sample implementation is that it requires tweaks to both the list model and its LAF UI.

I thought it would be nice to be able to apply this effect to any list without having to replace the LAF UI. Since lists render themselves cell by cell anyway, it shouldn't be that hard to just trick the list into painting each cell where we want it, instead of in its default location.

I focused on just handling an internal drag, but the API on the smoother could easily be tweaked to accept native drags from external sources.

First, to separate the functionality from user triggers, I decided to put the mouse event handling into the demo code. I've found that in UI testing, it's almost always beneficial to be able to drive bits of the UI from direct programmatic methods (would that Swing followed this pattern, so it would be easier to test). The mouse listener decides when to start, update, and end the drag, and calls in to the smoother's corresponding methods.

The smoother itself is a decorator which performs the painting of individual cells by having the original list paint itself fully and then clipping out the unwanted stuff. This could be optimized by just asking for the rendering components, but that potentially omits additional decoration provided by the LAF. So I locate the cell I want within the full list as painted by the LAF, and copy that image to its "floating" location.

    // Paint the background for the insertion point
  Rectangle b = getDecorationBounds();
  g.setColor(list.getBackground());
  g.fillRect(b.x, b.y, b.width, b.height);
  for (int i=0;i < list.getModel().getSize();i++) {
      if (i == draggedIndex)
           continue;
      Rectangle r = getCurrentCellBounds(i);
      Graphics g2 = g.create(r.x, r.y, r.width, r.height);
      Rectangle r2 = list.getCellBounds(i, i);
      ((Graphics2D)g2).translate(0, -r2.y);
      list.paint(g2);
  }

The Graphics object is set up to paint only in the desired area, then translated such that the JList will paint the desired cell into that area. We skip the index being dragged, since we want to handle that separately.

To draw the ghosted image, I simply used another decorator that uses the JList to render the dragged item. As the insertion location is updated by the mouse listener, the ghost image adjusts its vertical drawing position (being careful to clamp the vertical bounds to the start and end of the list).

The insertion point could use something more fancy if needed, like using the cell renderer or explicitly painting the rectangle. Just leaving the background exposed works well in this case, though.

A timer task periodically moves each cell's current location toward its final location, and triggers a repaint if any of the locations actually changes. This should be optimized to track a smaller range of cells (like only those visible).

The basic calculation of a cell's desired position simply calculates its normal position, then adjusts for any preceding dragged item (to be removed) and any preceding insertion point (to be inserted). The current locations start off with no dragged item or insertion point, and gradually float to their final positions based on a dragged item and possibly changing insertion point. Note that if you rapidly drag across several items, they all will float smoothly even as their destination changes.

Matisse First Impressions

2006-04-28T08:48:00.000-04:00

My compliments to the Matisse crew (and a hat tip to those who have walked this path before). This is truly what a layout editor should look like. Thanks for examining prior art and learning from it. I now have a few projects that now have a netbeans project folder and extra .form files.

That said, here are a few bumps I've run into so far...

Custom Component Creation
Rather than inline code in the XML form, initComponents should either take arguments or simply rely on field contents. Putting the code in XML makes it infeasible to automatically refactor. For example, I have a filename text field that provides a browsing action synched to the editability/enabled state of the text field. So to create the button, I need

new JButton(field.getBrowseAction())

I'd rather just create the component myself prior to initComponents(), and have initComponents() know that that field has already been initialized. Perhaps split between initializing and doing the layout?

Changing Component Names
If you edit the member field name for a component, you don't get a corresponding refactor of the code.

Alternate Components in Layout
I'm trying to figure out the best way to swap out two different panels. One has just a password, one has a filename and a password. I'd like to swap between the two and have the layout still work, but the layout assumes that the component hierarchy is static. I'll probably just set up a container panel with the appropriate resizing attributes, then add/remove the alternates as needed.

Strings
I should be able to substitute a string lookup for a hard-coded string, whether in labels or text fields or whatever. Granted, I can override whatever happens in initComponents, but then I'm maintaining the same string twice - once in my string/properties tables, and again in the UI designer.

Cross-Panel alignment
Sometimes I'd like to operate on a number of components as a group (resize the right edge, for instance) and this doesn't seem possible. It'd be nice if the alignment lines could be inferred and then themselves could be draggable. Putting things into sub-panels has the unfortunate side-effect that you can only align with other things in that panel.

Grid Size/Spacing
I'm surprised this one got through. I'm stuck with 10 pixel margins that I can't change. So my choices are 10 or 0 pixels. Ugh. There's a preference for Grid X/Grid Y, but it doesn't seem to have any effect.

Decorator/Overpainter Update

2006-04-17T12:50:00.002-04:00

I've updated the decorator to handle most LAF backgrounds. You can now modify the background on just about anything that relies on a parent to paint its background.

The selection marquee is also no longer clipped to its parent component.

Now you might say "I can just paint on my glass pane" and you'd be right except that:
* Your glass pane eats all user input events once it's visible unless you explicitly redirect them
* You glass pane doesn't know anything about what's under it
* It always paints *above* everything else

The AbstractComponentDecorator is a bit more flexible in that you can target all or part of a specific component or a specific area of your window.

Decorating/Overpainting Swing Components

2006-04-08T09:53:00.004-04:00

Have you ever wanted to change the way an existing component appears, just a little, without having to go and rewrite it or subclass it?

The image at right demonstrates several implementations of an abstract base class which puts an arbitrary decoration over an existing component. This technique allows you to do any of the following:

Put labels on a scrolled component which stay fixed relative to the scroll pane rather than the scrolled component (useful for labeling horizontal lines on a panned display).
Put an icon badge anywhere on a component, such as a stop sign over invalid text in a text field
Put tooltips on a component that you didn't write (like adding annotations to someone else's work).
Dim the entire painted image to gray, or fade it into the background color to make the component look disabled.
Change the appearance of component's background (gradients, stripes, or polka-dots).
Apply animation effects to the component.
Marching ants/Rubber band selection rectangle (xor is so Seventies).
Highlight all or part of an existing component to indicate the effective target of a drop operation (changing the selection isn't always the best solution).

to see a few of these decorations in action.

Note that the code for each of the following decorations consists of the painting logic and optionally positioning logic, which is all you should be concerned about.

The implementation for drawing a badge:


class Warning extends AbstractComponentDecorator {
    private final int SIZE = 16;
    public Warning(JTextField f) {
        super(f);
    }
    /** Position the badge at the right-most edge. */
    public Rectangle getDecorationBounds() {
        Rectangle r = super.getDecorationBounds();
        Insets insets = getComponent().getInsets();
        r.x += r.width - SIZE - 1;
        r.y += (r.height - SIZE) / 2;
        if (insets != null) {
            r.x -= insets.right;
        }
        return r;
    }
    public void paint(Graphics graphics) {
        Rectangle r = getDecorationBounds();
        Graphics2D g = (Graphics2D)graphics;
        GeneralPath triangle = new GeneralPath();
        triangle.moveTo(r.x + SIZE/2, r.y);
        triangle.lineTo(r.x + SIZE-1, r.y + SIZE-1);
        triangle.lineTo(r.x, r.y + SIZE-1);
        triangle.closePath();
        g.setColor(Color.yellow);
        g.fill(triangle);
        g.setColor(Color.black);
        g.draw(triangle);
        g.drawLine(r.x + SIZE/2, r.y + 3, r.x + SIZE/2, r.y + SIZE*3/4 - 2);
        g.drawLine(r.x + SIZE/2, r.y + SIZE*3/4+1, r.x + SIZE/2, r.y + SIZE - 4);
    }
}

The implementation for dimming:


class Dimmer extends AbstractComponentDecorator {
    public Dimmer(JComponent target) {
        super(target);
    }
    /** Paint using a transparent version of the bg color. */
    public void paint(Graphics g) {
        Color bg = getComponent().getBackground();
        g.setColor(new Color(bg.getRed(), bg.getGreen(), bg.getBlue(), 200));
        Rectangle r = getDecorationBounds();
        g.fillRect(r.x, r.y, r.width, r.height);
    }
}

The implementation for semi-scrolling labels:


   private static final int SIZE = 1000;
   private static final int BLOCK = 20;
   private static final int LINE = 20;

   private static class Labeler extends AbstractComponentDecorator {
       public Labeler(JComponent target) {
           super(target);
       }
       /** Ensure the label stays at the left-most visible
        * edge of the component.
        */
       public Rectangle getDecorationBounds() {
           Rectangle r = super.getDecorationBounds();
           Rectangle visible = getComponent().getVisibleRect();
           if (r.x < visible.x)
              r.x = visible.x;
           return r;
       }
       public void paint(Graphics g) {
           Rectangle r = getDecorationBounds();
           for (int i=0;i < SIZE;i+= LINE) {
               g.drawString("label " + (i/LINE + 1),
                            r.x, r.y + i + g.getFontMetrics().getAscent() + 2);
           }
       }
   }

This class started out as a way to highlight different drop targets in a tree or table, and a method for the Costello editor to highlight areas of a component to be captured as an image (without actually setting the target component's background). I've subsequently used it for other decorations as noted above.

The whole idea would be trivial if Swing provided a hook into a component's paint method. There is no such explicit hook, and no implicit ones either without getting into a lot of complexity (perhaps by writing your own repaint manager). Since writing a repaint manager seems totally orthogonal to decorating a single component, we take a different tack.

My first implementation was to simply add a sibling or child component into the hierarchy on top of the first (and indeed, that implementation is still in use by the Costello editor). Unfortunately, the normal component hierarchy doesn't really consider z ordering, so the results are not always consistent. You might get things painted properly 90% of the time, but occasionally have your decoration occluded by a scroll pane, or the fact that there's an extra component in the hierarchy causes the layout manager to occasionally freak out. So it's okay for a proof of concept, but kinda lame in practice.

There is, however, a Swing component that knows about z ordering. Most Swing components will reside somewhere below a JLayeredPane (see the javadoc for javax.swing.RootPaneContainer for details). This little component has the capability of painting things in layers, which is just the capability we're looking for. The JLayeredPane even has predefined layers and was explicitly designed for stacking components in a known Z order (it also has a sub-layer ordering referred to as "position", but this doesn't seem to work).

So the basic idea is that for any decoration, we establish a painting component as a child of the JLayeredPane which is positioned in a layer above the decorated component. The Swing painting mechanism will automatically ensure that our decoration gets painted whenever the decorated component is painted, and that the decoration happens after the target component is painted.

A few details to note:

The decorator must maintain proper position and size with respect to the target component. If the decoration is in the lower right corner of the component, it should stay there if the component grows.
The decorator must clip its painting according to how much of the target component is visible. If the component is partially obscured within a scroll pane, the decorator should be clipped in a similar fashion.
The decorator needs to track the target component's visibility. If the component is on a tabbed pane and a different tab is displayed, the decoration needs to be hidden.
Painting under the decorated component is a bit more tricky. The current implementation for decorating component backgrounds assumes the current LAF doesn't change how ComponentUI paints the default background (gtk/synth probably won't work well). I haven't really looked into this much.
It's possible to composite with the existing graphics (so you could, for instance, paint only where there's already a blue pixel), but this capability varies by platform and VM version.

Full source for the demo and AbstractComponentDecorator class.

Automatic email support for Java

2004-07-29T21:14:00.000-04:00

I got tired of asking for more information in bug reports in the Costello editor, so I figured I'd put in a link to automatically post to the mailing list with the user's environment info. It would also help direct all traffic of that sort to the proper place, rather than having some people post to forums, some to the mailing list, or others filing bug reports or RFEs (even when they're just asking a question).

You'd think that eons after the introduction of email and bug reports and that sort of thing it'd take no more than a line of code, but alas, not so for java. And I certainly don't want to introduce yet another library dependency. So I says to meself, how hard can it be? I mean, OSX already gives you a nice "open" command to launch something appropriate for whatever argument you give it (so much faster than digging through folders, too). Windows has the "start" command, and it's easy enough to pass an arbitrary script to /bin/sh for any *nix variants. So I set off to get my Runtime.exec on...

Check out the landscape

First off, someone on the Apple java-dev list suggested throwing a mailto: URL at the "open" command.

% open mailto:abbot-users@lists.sf.net

Cool, that works, now what about subject and body? Quick google for proper mailto: syntax, reveals

% open 'mailto:abbot-users@lists.sf.net?subject=bug report&body=java version'

open[]: No such file mailto:abbot-users@lists.sf.net?subject=bug report

Bummer, doesn't quite work, must be those spaces. Duh, can you say URL encoding. Try again...
(For you *nix newbies, an ampersand is normally interpreted by the shell as direction to start the preceding command as a background process, thus the single quotes are required. When we stuff this into Runtime.exec, we can drop the quotes because Runtime.exec doesn't use the shell)

% open 'mailto:abbot-users@lists.sf.net?subject=bug%20report&body=java%20version'

Aha, note to self: make sure you URL-encode the subject and body, but make sure the encoder uses %20 and not '+', b/c the pluses won't get converted back into spaces.

Over to w32 now, and see if "start" works the same way. I normally use bash on windows, but this test wants to be in the Windows command shell.

% cmd.exe

c:\> start mailto:abbot-users@lists.sf.net?subject=bug%20report&body=java%20version

'body' is not recognized as an internal or external command,

operable program or batch file.

Somehow I didn't feel quite so insulted when OSX said it. A quick look at the cmd.exe "man page" (actually not so quick. the MSDN page was way down the google search, and fourth even on the MSDN search). Seems some characters are special. We won't tell you all of them, but here are some of them. Oh great. In this case, seems like the ampersand. Well, let's just try it with quotes (supposedly you can escape individual characters with '^', but then things start getting nasty).

c:\> start "mailto:abbot-users@lists.sf.net?subject=bug%20report&body=java%20version"

What the @#$%! I get a new command prompt with the title set. Let's try

c:> start /help

@#$%!

c:> start /?

Ah, there it is. If you pass the first argument in quotes, it becomes the title of whatever you "start". Try again

c:> start "title" "mailto:abbot-users@lists.sf.net?subject=bug%20report&body=java%20version"

Ah, finally. Up comes some flavor of Outlook. Good enough. What about *nix? Probably as easy as just picking a few popular mail programs and seeing if they exist. I'm sure *nix programs can handle a silly little mailto URL. Actually, most of the lame bug reports I get are from w32 users. The *nix and OSX users usually have much more esoteric problems. So off to the java code to provide some minimal automatic bug reporting.

Write up a TestCase

I'd previously written a simple exec handler that would capture all the program output and error streams, so I'll use that here. I'm not concerned with the output (I don't expect any) and only want to throw up an error if the command somehow fails. So write up a little JUnit test case for it, let's call it the LauncherTest. I've rigged the test to only run if I invoke it manually; since it requires user interaction to get rid of the launched processes, I'd rather it not run with the rest of the automated suite. Writing the test case makes me think about exactly how I'd like to use this thing. Namely, I just want to send a post to the support mailing list with a prepared body. And to make sure I don't get any lame "Help!" subject lines, might as well fill that in as well. I just want to invoke a single line of code to preformat an email. Fill in the target address, subject, and sample body. No need for a complex API.

package abbot.util;



import junit.framework.*;



public class LauncherTest extends TestCase {



    // only run these tests manually, since we can't control the launched apps automatically        

    private static boolean run = false;



    public void testMailTo() throws Exception {

        if (!run)

            return;

        String SUBJECT = "subject";

        String BODY = "body";

        Launcher.mail("abbot-users@lists.sf.net", SUBJECT, BODY);

    }



    public static void main(String[] args) {

        run = true;

        junit.textui.TestRunner.main(new String[] { "-c", LauncherTest.class.getName() });

    }

}

Make the TestCase work

Now, whipping out my trusty Runtime.exec wrapper, I simply wrap up the tricks I was playing in the console.

package abbot.util;



import java.net.URLEncoder;

import java.util.ArrayList;

import java.util.Arrays;

import java.io.IOException;

import abbot.Log;

import abbot.Platform;



/** Mail and browser launcher which augments Runtime.exec()        

 * functions.  Provides for built-in email and web browser support.             

 */

public class Launcher {



    /** Sort of URL-encode the given string.  */

    public static String encode(String s) {

        // simple implementation for now

        return s;

    }



    /** Format a message to the given user with the given subject and message   

        body, including CC and BCC lists. */

    public static void mail(String user, String subject, String body) throws IOException {

        StringBuffer mailto = new StringBuffer("mailto:" + user + "?");



        mailto.append("Subject=" + encode(subject)

                      + "&" + "Body=" + encode(body) + "");

        open(mailto.toString());

    }

    

    /** Use the given command/program to open the given target. */

    public static void open(String command, String target) throws IOException {

        ArrayList args = new ArrayList();

        if (Platform.isOSX()) {

            args.add("open");

        }

        else if (Platform.isWindows()) {

            // Probably won't work on win9x, but just in case                           

            args.add(Platform.isWindows9X()

                     ? "command.com" : "cmd.exe");

            args.add("/c");

            args.add("start");

            args.add("\"Title\"");

            // Always quote the argument, just in case                      

            // See MS docs for cmd.exe; &, |, and () must be escaped with   

            // ^ or double-quoted.  semicolon and comma are command         

            // argument separators, and probably require quoting as well.   

            target = "\"" + target + "\"";

        }

        else {

            throw new Error("Not done yet!");

        }

        args.add(target);



        String[] cmd = (String[])args.toArray(new String[args.size()]);

        String output = ProcessOutputHandler.exec(cmd);

    }

}

The windows version actually required a bit of trial and error to get the argument accepted properly. I know I'm going to have to encode the subject and body, but I don't know all the details yet. So true to TDD form, I start with a very basic encoding implementation. Running the unit test on OSX brings up the Mail app, and running it on w32 brings up Outlook.

Add just the features I need

So far, so good. Now I want a little more complex subject and body. First, adjust the test to use more representative values:

    String SUBJECT = "with spaces";

    String BODY = "with spaces and <[special % characters]>";

I already know I need some flavor of URL encoding, so I'll take a slight shortcut and throw that in immediately:

    public static String encode(String s) {

        return URLEncoder.encode(s);

    }

Running the test we find that OSX's Mail will decode %20 but not '+', and URLEncoder.encode(String) turns spaces into '+'. So we need to pre-escape spaces, then replace them with the proper %20 encoding. What about w32? Outlook won't handle either encoding, but it will accept the spaces directly. So we immediately add a test for the encoding:

    public void testEncoding() {

        String[][] strings = {

            { "with space", Platform.isOSX() ? "with%20space" : "with space" },

            //TODO check encoding of other characters

        };

        for(int i=0;i < strings.length;i++) {

            assertEquals("Wrong string encoding for '" + strings[i][0] + "'", strings[i][1], Launcher.encode(strings[i][0]));

        }

    }

Now that the testEncoding() test properly fails, on we go to code up a proper solution.

    public static String encode(String s) {

        StringBuffer buf = new StringBuffer(s);

        // Avoid URLEncoder.encode for spaces; it replaces them with plus       

        // signs, which remain pluses when decoded.                             

        String SPACE = "--SPACE--";

        for (int idx = buf.toString().indexOf(" ");

             idx != -1;idx = buf.toString().indexOf(" ")) {

            Buf.replace(idx, idx+1, SPACE);

        }

        buf = new StringBuffer(URLEncoder.encode(buf.toString()));

        for (int idx = buf.toString().indexOf(SPACE);

             idx != -1;idx = buf.toString().indexOf(SPACE)) {

            if (Platform.isOSX()) {

                // The "open" command parses spaces                             

                buf.replace(idx, idx + SPACE.length(), "%20");

            }

            else {

                buf.replace(idx, idx + SPACE.length(), " ");

            }

        }

        return buf.toString();

    }

You can stop coding now

Hoo-rah. Success on both OSX and Windows. The subject and body show up with exactly the strings I passed in. Now I just do the Launcher.mail invocation in response to a menu selection, and no more asking for more basic information!

I'll publish the finished Launcher code in the next installment.

Next: Do it on *nix, please.

I want my username

2004-07-13T08:35:00.000-04:00

Back in the day you could choose whatever username you wanted, and it had a lot more meaning than a display name that could be changed at a whim. Nowadays, your username is something like outtawhack2356 and good luck getting anything much recognizable.

Maybe it's no big deal, just set your nickname to whatever you want and ignore the username. If more people recognize your nickname you might be less likely to change it.

Still, there's not the kind of tight binding from username to user like I remember. Nobody says "yeah, that outtawhack2356, he's a real funny guy".

Mustn't be late, mustn't be late...

2004-07-08T10:24:00.000-04:00