Anyone who was there knows we promised to post our slides and demo source code. So here you go:

• LimeWire: Swing for the Masses.pdf
• Guice-Demo.zip
• GlazedLists-Demo.zip
• JXLayer-Demo.zip
• Painting-Demo.zip

If you’d like to see slides from other talks, all of the slides from JavaOne can be found here.

LimeWire is also open source. So if you would like to see more complex examples of everything done in the demos, be sure to checkout our cvs.

From their talk, you’ll get information on:
• SwingX painters - These help customize widget rendering.
• AppFramework - @Resource helps easily change icons and colors.
• Wireframes - Developing a wireframe before adding paint is good.
• Layers - JXLayer or JLayeredPane make great additions.
• Light weight versus heavy weight - Sometimes mixing is a necessary evil.

Hear how the Lime Wire team planned a new interface, fleshed it out and made it all pretty. (We’ll provide links to the slides and demo code here after the presentation.)

Here’s LimeWire 5 from the paper prototype through our latest beta:

In order to create this range slider, we need a new Swing component because the existing JSlider component only displays a single thumb to adjust the slider value.  (Interestingly, even though JSlider only allows you to update a single value, its data model actually provides support for two values that define an internal range within the minimum and maximum bounds. )

The internal range is defined by the slider value and an “extent”, which is the length of the inner range that begins at the slider value.  In DefaultBoundedRangeModel, the default “extent” is zero and not normally used for anything.  We add it to the slider value to define the upper value of the selected range.

public void setUpperValue(int value) {
    // Compute new extent.
    int lowerValue = getValue();
    // Set extent to set upper value.int
    newExtent = Math.min(Math.max(0, value - lowerValue),
    getMaximum() - lowerValue);
    setExtent(newExtent);
}

Our new dual-thumb slider component takes advantage of the built-in definition for DefaultBoundedRangeModel, and is implemented with just two classes:

-> RangeSlider extends JSlider to install a UI delegate and provide value change methods, and

-> RangeSliderUI extends BasicSliderUI to paint the two thumbs and handle user events.

RangeSlider provides methods to set the lower and upper values in the selected range.  We define the existing slider value as the lower value, and the upper value as the lower value plus the extent.  To access these values, we override some methods, and add a couple of our own.

-> We add setUpperValue(int) to calculate the extent based on the current lower value.  We apply limits to ensure that the upper value is bounded by the lower value and the maximum.

-> We override setValue(int) to calculate the extent to ensure that the upper value does not change.  We apply limits to ensure that the lower value stays bounded by the minimum and the upper value.

-> We override updateUI() to install a custom UI delegate to render the two thumbs.

RangeSliderUI provides a customized rendering of the two thumbs and handles user events to update their values.  This is somewhat involved so we will only highlight the primary aspects of this code.  (Here’s the source: Range Slider Demo code.)

The main tasks are: (1) calculating the thumb sizes and locations, (2) painting the thumbs, and (3) handling mouse and keyboard input events on the thumbs.

Step 1: thumb sizes and locations

To calculate the thumb sizes and locations, we need to override several UI delegate methods.

-> We override installUI(JComponent) to initialize a new upperThumbRect attribute, which we use to store the size and position of the upper thumb.

-> We override calculateThumbSize() to update the size of the upper thumb, which is defined to be the same as the lower thumb.

-> We override calculateThumbLocation() to update the location of the upper thumb, which is based on the upper value stored in the slider component.  The thumb is always positioned to be centered over its value on the track.  The logic is essentially copied from the superclass method and applied to upperThumbRect.

-> We override getThumbSize() to return the dimensions of the thumb.  In LimeWire, we use custom images for our thumbs, although any shape will do.

Step 2: paint

To paint the slider component, we need to override the default implementations of various paint methods in the UI delegate, and add a few of our own.

-> We override paintThumb(Graphics) to do nothing.  This is called by the superclass paint() to draw the single thumb, and we want to replace this with our own logic for two thumbs.

-> We override paint(Graphics, JComponent) to draw the two thumbs as needed.  We define an upperThumbSelected indicator to keep track of which thumb was last selected, so we can draw the unselected thumb first, and draw the selected one on top of it.

-> We add paintLowerThumb(Graphics) and paintLowerThumb(Graphics).  The two methods are similar - they draw a thumb in the appropriate rectangular region.  (The sample code uses a colored shape for the thumb.)

-> We override paintTrack(Graphics) to draw the slider track, and highlight the selected range.

Step 3: handle input

To handle mouse drag events on the thumbs, we define a RangeTrackListener inner class that extends the TrackListener class in BasicSliderUI.  We also override createTrackListener(JSlider) to return a new instance of the class.  In RangeTrackListener, we implement several methods.

-> We override mousePressed(MouseEvent) to detect which thumb is being pressed.

-> We override mouseDragged(MouseEvent) to adjust the appropriate slider value as the thumb is dragged.

-> We override mouseReleased(MouseEvent) to reset indicators.

-> We add moveLowerThumb() and moveUpperThumb() to update the slider values and repaint the thumbs.

Finally, to handle keyboard events on the thumbs, such as the arrow keys, we override a pair of methods used to move the slider by increments.

-> We override scrollByBlock(int) to move the selected thumb by a block increment.  This is called when the Page Up or Page Down key is pressed.

-> We override scrollByUnit(int) to move the selected thumb by a unit increment.  This is called when one of the arrow keys is pressed.

Summary

The dual-thumb slider component allows you to select a range by adjusting its lower and upper bounds.  And by implementing our own UI delegate, we can adjust the appearance of the component to suit our needs.  (This can be very useful when working with visual designers who are creating a unique vision.)

Check out the Range Slider Demo code which contains a complete example of RangeSlider and RangeSliderUI, minus the custom images we use for the thumbs in LimeWire.

1)  Most images are poorly named. Digital cameras have not helped this at all; it’s impossible to remember that the photo from last night of you and your friend is named IMG_00101.

2) This can result in inadvertent file sharing which is something we tried to prevent in the newest LimeWire. Try remembering if you wanted to share IMG_00101 or was it IMG_001101.

3)  This is just a bad user experience. Images are meant to be seen.

There have been some very good articles  and books that discuss the proper way to load and scale images. They especially point out the fact that you should never use Image.getScaledInstance(). So I will reiterate that point, don’t use Image.getScaledInstance(). For details on why and the alternative methods follow one of the links above which give very good explanations and alternatives for scaling images.

For the thumbnails in LimeWire 5, we use a modified version of the getFasterScaledInstance() in the book, Filthy Rich Clients. This creates high quality thumbnails in a relatively short period of time. I was occasionally running into three different problems,

1) the thumbnails were being created relatively fast but not quite fast enough. This became more noticeable as the file size of the image increased (the solution was going to be write the thumbnails to disk for future use).

2) large images were occasionally failing to load. This was occurring very randomly where the same set of images would fail 20% of the time, and

3) when creating large numbers of thumbnails Out Of Memory exceptions would start happening.

After reading many articles and forums, I came to a solution that solved all three of these problems. The solution we use is to perform subsampling on large images. Subsampling is a process of reading every nth pixel in every nth line. The technique alone is a bit crude for creating thumbnails. All you can specify is the number of lines to skip in an image. So a subsampling factor of 1 will read every line, a subSampling factor of 2 will read every other line, etc. Alone this technique doesn’t produce very nice results, however used in combination with the getFasterScaledInstance(), it creates high quality thumbnails very fast and all the failed image loads and OOM exceptions nicely disappeared.

Below is the code that we use to read an image into a BufferedImage prior to calling getFasterScaledInstance() to create the final thumbnail.

private static final float subSamplingFactor = ThumbnailManager.WIDTH * 4.20f;
/**
 * Loads a file into a BufferedImage. If the image is longer than a subSamplingFactor,
 * rows are sampled out to reduce the size of the BufferedImage. This can go a long way
 * towards reducing OutOfMemoryExceptions when loading large compressed images.
 */
private BufferedImage getSubSampleImage(File file) throws FileNotFoundException, IOException {
    BufferedImage image;
    ImageInputStream imageInputStream = null;
    try {
        final ImageReader imgReader = ImageIO.getImageReadersBySuffix(FileUtils.getFileExtension(file)).next();
        imageInputStream = ImageIO.createImageInputStream(new BufferedInputStream(new FileInputStream(file)));
        imgReader.setInput(ImageInputStream);
        int longEdge = (Math.max(imgReader.getHeight(0), imgReader.getWidth(0)));
        int subSample = (int)(longEdge/subSamplingFactor);
        final ImageReadParam readParam = imgReader.getDefaultReadParam();
        // subSample the image
        if(subSample > 1) {
            readParam.setSourceSubsampling(subSample, subSample, 0, 0);
        }
        image = imgReader.read(0, readParam);
    } finally {
        if(imageInputStream != null)
            imageInputStream.close();
    }
    return image;
}

Using this technique, we ensure that all images we read and pass to the getFasterScaledInstance() will always be a reasonable size. Our subSamplingFactor works on a sliding scale so as the image gets larger, more and more lines are skipped when first being read. Using this two step process allows enough information to be left in the original BufferedImage for getFasterScaledInstance() to produce a crisp image.

Now suppose we wanted to add a floating component over top of these. The idea is this floating component would be centered both vertically and horizontally regardless of how big the parent grew.

There are a few different ways to achieve this effect.

GlassPane: One way would be to use the GlassPane. Position the first three components using BorderLayout and then add the floating component in the GlassPane. This works but fails if the three components don’t fill the entire screen. It also prevents you from using the GlassPane for something else (like ghost dragging for example).

JXLayer: Another approach would be to use the JXLayer. This certainly works but is a bit code heavy for simple uses.

StackLayout : A third approach might be to use the StackLayout found in the SwingX jar. This is a relatively simple solution but has the downside of still needing to use three layout managers, one for the first three components, one for the floating component and finally the StackLayout to put the two together. This of course creates excess components for the sake of laying out components, something we would like to avoid.

Let’s solve this problem using MigLayout. As I mentioned in a previous post, MigLayout allows us to mix different types of layouts in the same manager. So we will use the docking layout to layout the top and left components, the grid layout for the center component, then relative positioning to layout the floating component. Here’s how the code looks:

 setLayout(new MigLayout("gap 0, insets 0, fill"));
 add(createFloatingPanel(), "pos 0.50al 0.5al");
 add(createPanel("Top", Color.yellow), "dock north");
 add(createPanel("Left", Color.red), "dock west");
 add(createPanel("Center", Color.green), "grow");

That’s all it takes, five lines of code and no extra components.  The most important features in the constructor is the use of the keyword “fill” which ensures that we take up all the space in the parent.

Let’s look at the docking components. Using the keyword “dock” along with “north” & “west” act like BorderLayout. Adding the north component first ensures that it fills the horizontal space rather than the west component filling the vertical space. We then add the center component using the generic grid layout with the keyword “grow”. This ensures that the center component will fill any remaining space.

The most interesting thing here is the pos .5al .5al. This tells the floating panel to ignore the grid positioning. Instead it aligns it 50% vertically and 50% horizontally within the parent container.

Five lines of code to again achieve a pretty impressive layout. Two important things to note here:

1) Notice that the floating panel is added first. If it’s added after the other components, it will be drawn behind them.

2) This technique won’t always work. If one of the components behind the floating panel is a JTable or JList which contains cell Renderers, then this layout method will fail.

In LW 5, we use this miglayout technique whenever there isn’t a table or list behind a floating component and use JXLayer to achieve the same effect when there is a table or list.

See you at JavaOne!.

Some things That Went Right

The LimeWire client team has some amazing people on it. Every single person on the team cares about the quality of the product, code, and the other people. It’s easy to find someone who just cares about one of those three things — but it’s incredibly hard to build a team of people who care about all of them.

There’s no way that LimeWire 5 could exist without the work that every person on the team put forward. I think back to what each individual worked on, how hard they worked, and I can’t help but be bewildered at the incredibly ease with which LimeWire 5 came together. What follows are just small tidbits of what each person worked on, but they highlight how a distributed effort came together seamlessly.

David worked on rewriting the “search” logic so that a keyword search could apply to all metadata. That single piece of code enabled a simple single search box. Tim worked on integrating XMPP code. Once 5 took shape, the XMPP code became the fundamental basis for all friend features. Felix started using event listeners in a new way … suddenly the entire UI and much of the core became event-based and loosely coupled in a way that pushed development at a faster pace. I spent a weekend and wrote the frame & code framework for the new UI and another weekend giving it some rudimentary paint, shortly afterward progress on the UI skyrocketed. Peter tackled every odd & end you can imagine, getting drag & drop working, fixing file associations, adding system notifications, and much more. Matt was the first person actively start working on 5. He located and integrated the MozSwing browser, which is why LimeWire can integrate so nicely with webpages. Mario figured out how to do crazy tricks so that search results can be shown in a highly interactive list view. Dan worked tirelessly to reproduce bugs and QA our fixes. Mike E rewrote the way LimeWire handles file management, creating multiple “file lists” instead of a single “shared with gnutella” list, ultimately paving the way for sharing with friends. Michael R dove into the XMPP code and made sure it worked with arbitrary servers, letting us add an “Other” option that actually works. Michael T became our “master painter” and learned all about ways to make Swing look pretty. Mike S spent insane amounts of time writing UI specifications and gauging user feedback. Ernie spent his first week here writing the advanced panels, so people can still get the look and feel of the old LimeWire. Peng continued studying the DHT to see if there were ways to improve LimeWire’s use of it. Anthony designed mock screenshot after mock screenshot as templates for the developers. Jorge developed a ton of new icons to keep the look and feel fresh.

Every single person worked on things so disparate, all with a common purpose. We had a few things going for us: the code was designed so that UI developers could work against interfaces instead of directly against the core and for rapid development, we created a “mock core” and reused it during usability tests.

Still, the best code design in the world is nothing without great people. I’m proud of the team, and proud that we worked together and in an amazing display of cooperation.

LW 5 Needs Fixing tasks

10/16:

11/12:

12/29:

Some things That Went Right

Who’s your audience and what do they want?

I’ve read about it, seen the tire swing cartoon and heard co-workers mention the customer is key, but it was always lip service everywhere I worked. At least until the user experience guy brought in over 50 people for usability tests.

He interviewed power users who saw the Internet as a requirement in their life, people who used LW all the time, and users who never heard of LW. He asked them what they liked about software in general, what they thought about new software versions, what they wanted from programs. Then he asked them to perform a series of steps in front of a computer while staffers took notes to see what was confusing.

The interviews came at all stages of development … before a single decision about LW 5 was made, before any software was coded (we had paper prototypes where people had to simulate clicking or typing and I acted like a chose your own adventure book flipping to the proper next page), throughout code development and before launching.

LW 5 changed after each usability test. Originally there were two search bars but since no one used the one on the left, it was zapped. At first there were icons galore that some liked, but most found it was too much, so we tapered. Also, people had trouble finding how to sign into Friends. Some didn’t like the colors and expected it to be more limey … others didn’t like the download status on the left and wanted it more like the old version across the bottom of the UI.

In addition to the usability tests, the LimeWire forums gave a lot of feedback, helped find edge cases we missed, and steered LW 5 to be a product they wanted to use. More feedback is coming daily and the team is listening and responding …

LimeWire 5 and its UI evolved as we received user feedback.

Paper prototype, two search boxes:

Downloads on the side:

Too many icons and not limey enough:

Friends sign in hard to find:

Getting there … but it’s sure to evolve.

The next few blog posts are about the gritty details of taking LimeWire, the 9 year old product that 60 million users have come to love, and having a hard look at it. We’ll talk about how we did a complete redesign of the user’s experience and front-end code, integrated social features, and reworked the way we develop software. What went right and how it couldn’t have gone better … and how when something went wrong … it really went wrong.

Some things That Went Right

Iterative design in development, by Mike S

“Redoing this UI has been a pipe dream for me”, Sam said.

Two year ago, the LimeWire team was 4 developers. One year later (when I first started), the team grew to about 6 developers, 1 technical writer and 1 user experience designer. Currently, we have a team of 17 people: 6 network developers, 4 core developers, 2 UI developers, 2 visual designers, a user experience designer, a technical writer and a product manager.

The point isn’t that more people build a better product, but getting people of varying skills help make the best product possible. Developers constantly questioned one another about the best way to code something, I questioned when the visual design was excessively “artsy”, the developers questioned things I came up with wanting more power, and Anthony, our visual designer, told me I am over thinking the solution to a problem. There was a checks and balances system in place and even though there were countless arguments and disagreements (and there still are — even after the release), just having different people thinking about different things helped make sure that we weren’t doing one thing that just one person really wanted.

For this release, we tried to give focus to answer the question, “What is LimeWire?” Once we did some initial user research, surveys, scenarios, requirements, we started wire-frames, doing paper prototype usability tests, and then eventually building a flash prototype that we tested with users. All before any front-end swing code was written. In the meantime, the developers tested front-end toolkits and made all the back-end changes that were needed to get this design up and running. Once we were ready to integrate, I wrote interaction spec documents that got handed off to the developers. While they were doing that, Anthony wrote visual spec documents. By the time he finished those, the developers were done with my specs and they started on his. We got into a great circular flow between the developers and designers.

Why MigLayout?

There are dozens of layout managers so why is this one so special? There are three main reasons:

1) it’s extremely powerful. You can easily mimic everything from Gridbag Layout to BorderLayout to FlowLayout to Absolute Layout.

2) it’s extremely simple. There’s a handful of keywords and concepts to learn and most of the API can be committed to memory very quickly.

3) you don’t need any special plugins to layout or modify the code and you can use it virtually everywhere you need a layout manager.

Quick Overview

There are essentially three different ways to arrange components in MigLayout:

1) The default and most common usage is to treat the space as a grid with columns and rows. Components can be added to rows and columns and can span multiple rows and columns.

2) You can also mimic BorderLayout with docking components to the north, south, center, etc.

3) You can use absolute positioning. This allows you to place components in relation to the parent container or in relation to other components in the container.

The best part is you can combine all of these arrangements in a single component. You could, for instance, dock a component to the top, then use the grid to layout the remaining components below that. For a much more detailed overview, check out the tutorials at http://www.miglayout.com/.

Docking with MigLayout

This code mimics BorderLayout. The main difference is MigLayout allows you to add multiple components to the same area. In this case there are two components added using “dock north”. This is extremely useful since it allows you to perform complex layouts without wrapping components inside of a JPanel for the sake of laying out components. Notice that the order in which components are added effects how they are displayed, the first “North” panel fills the entire X-axis while the “North 2″ panel is bookmarked between “West” and “East” since it was added after those components.

//it’s important to note the order in which the components are added
//effects their width and height in relation to other components
setLayout(new MigLayout(”fill”));
add(createPanel(”North”), “dock north”);
add(createPanel(”East”), “dock east”);
add(createPanel(”West”), “dock west”);
add(createPanel(”North 2″), “dock north”);
add(createPanel(”Center”), “dock center”);

Flow Layout

This code mimics Flow Layout in both the horizontal and vertical direction. The only difference between vertical and horizontal is we add the keyword “wrap”. The “wrap” keyword tells the next component added to begin on a new row in the layout grid.

setLayout(new MigLayout(”fill”));
//grow tells the component to fill its entire grid space
add(createPanel(”Item 1″), “grow”);
add(createPanel(”Item 2″), “grow”);
add(createPanel(”Item 3″));
add(createPanel(”Item 4″), “grow”);
add(createPanel(”Item 5″), “grow”);

//wrap set on the constructor will put each
//component added on its own row in the grid
setLayout(new MigLayout(”fill, wrap”));
add(createPanel(”Item 1″), “grow”);
add(createPanel(”Item 2″), “grow”);
add(createPanel(”Item 3″));
add(createPanel(”Item 4″), “grow”);
add(createPanel(”Item 5″), “grow”);

More Complicated Layouts

These are rather trivial uses of MigLayout. The real power comes when you want to layout something a bit more complex. Typically you’d find Gridbag Layout being used for this or nested Border Layouts. The result usually ends up being very verbose and hard to maintain. If you notice, I add 7 components to the container and have only 7 lines of code. MigLayout provides a very clean, readable, and easily modified code base while laying out a rather complex component.

// fill entire space provided, 2 pixel gap between components and
// 10 pixel insets from all edges
setLayout(new MigLayout(” fill, insets 10, gap 2″));
// first line
// span all the columns, wrap: put next component on the next row
add(createLabel(”Login”), “span, wrap”);
// second line
// textfield should fill the remaining horizontal space
add(createLabel(”User Name”));
add(createTextField(), “growx, wrap”);
// third line
// passfield should fill the remaining horizontal space
add(createLabel(”Password”));
add(createPasswordField(), “growx, wrap”);
// fourth line
// ok skips first column, split puts ok/cancel button in same cell
// using tag: ok/cancel allows miglayout to swap their order based on the OS preference
add(createButton(”Ok”), “skip 1, split, alignx right, tag ok”);
add(createButton(”Cancel”), “tag cancel”);

Finally, adding the keyword “debug” to the constructor, allows you to visually see what’s going on internally. The red lines outline each cell in the grid, while the blue lines outline how that particular component fills its cell. Here you can see there are four rows and two columns. Comparing it to the code, you can see the login label spans two columns, the ok/cancel are put into the same cell and skip the first column, you can also see the 2 pixel gap between rows/columns and the 10 pixel inset. This is such an amazing feature and has saved me countless hours while trying to figure out complex layouts.

Hopefully it gave you a feel for how powerful MigLayout is while also having very clean and readable code. Here’s the source code for the demos: miglayout-demo-src.zip