Thumbnails: Formatting Thumbnails

This article discusses how to tastefully format/decorate a thumbnail. Previous articles discuss how to scale images efficiently, including bmps, jpgs and pngs, and how to extract existing thumbnails from large jpg images, but this article focuses on the question: and then what?

Context

Why do we need to decorate thumbnails? We don't need to, I guess. This is a matter of taste. For comparison, here are a few examples of what other people are doing:

	Mac OS Finder This is a set of thumbnails when I browse a folder of images in the Finder on Mac 10.7. This is one of the most complicated formatting I've found: it includes a shadow, a white border, and then a thin dark border.
	iTunes In iTunes: the thumbnails only have a light shadow. Here you might be able to make more assumptions about the content of the thumbnail: it is probably a very brightly colored image with lots of eye-catching patterns and texture. (That is: an artist specifically composed this thumbnail to fill every pixel.)
	Woot.com Woot.com doesn't bother with shadows, but they still add some very distinct borders around certain thumbnails. In this case: the borders help identify what is the "clickable area" for these thumbnails.
	Amazon These non-rectangular thumbnails from Amazon.com have no shadows or borders at all. These are also the largest thumbnails in this set of examples: they occupy so much space that they are visually distinct without any help from formatting. Microsoft.com also appears to follow this model (using large, undecorated thumbnails).

The decision regarding when and how to decorate a thumbnail might be better left to graphic designers than to software engineers, but for now my point is simply: this is an established convention that you may sometimes want to follow.

Overview

My most immediate goal is to create a file browsing UI, so I want to emulate the first example shown above: photo thumbnails in the Mac Finder. There are three basic elements in this image: the drop shadow, the border, and the thumbnail itself.

This applet demonstrates these 3 layers:

This jar (including source code) is available here.

This applet demonstrates the BasicThumbnail class and its ability to format a thumbnail image. The default options displayed are the preset options that resemble the Mac OS thumbnail (simply referred to by the static field BasicThumbnail.Aqua).

Each layer of the thumbnail (shadow, border, image) is a separate object with its own concept of padding (insets). They are painted in the order shown in the list (from left to right), so that each layer overlaps all the previous layers. To modify a layer: click that layer in the list and use the controls in the inspector.

All layers support varying amounts of curvature for the corners. A curvature of zero is a sharp (rectangular) corner, and a high curvature is a very rounded corner.

Shadow

In this model a shadow is just a series of strokes of increasing thickness. (That is: a shadow of 1 pixel, then 3 pixels, then 5 pixels, etc.) Each stroke is solid black with a very light opacity (usually less than 20 out of 255).

Since this can be several pixels thick: you have control of both the inner and outer curvature.

Border

A border is a solid-color frame. Technically this can use any color, but the UI here restricts it to a shade of gray for simplicity's sake. Like the shadow: this supports an inner and outer curvature.

Image

This layer contains the actual thumbnail. It also contains an optional background color, and one curvature control to apply rounded edges.

In the applet above: selecting the image layer lets you control the rotation. The rotation is technically a property of the entire BasicThumbnail (it applies to all layers), however it was placed in the image's inspector for convenience when modeling the GUI.

Layer Controls

The top row of the applet contains a set of buttons to add, remove, and reorder layers. Also the "<>" button displays the source code used to represent the thumbnail in the editor.

Usage & Implementation

Once a BasicThumbnail is constructed, you can simply call:

BufferedImage img = thumbnail.create( sourceImage, maxSize);

Where "sourceImage" is an Image, URL, or File, and "maxSize" is a java.awt.Dimension object. The returned thumbnail will be either the width or height of the argument dimensions, with the other dimension scaled proportionately as needed.

The actual scaling is handled abstract by the parent class Thumbnail: this is where the logic lives that accepts a file, URL or image and scales it. The subclasses (such as the BasicThumbnail) are responsible for calculating exactly what dimensions to scale the source to, and then how to render that scaled image.

If a rotation has been supplied: then a binary search is used to calculate the exact scaling factor required to fit the source image inside the thumbnail with all the specified decorations.

Conclusion

My final thumbnail formatting is not a perfect replica of Apple's formatting, but it is sufficiently close for my needs. (Also Apple can modify this formatting at any time, so maintaining an exact copy is a very ambitious ideal.) What I have now is a strong improvement over a plain (undecorated) thumbnail, so I am happy with the result.

I encountered a few thorny issues along the way; the main two both had to do with adding rotation, and subtle rendering bugs I had to hunt down. In hindsight the rotation feature may have been more trouble than it was worth, but I'm happy with the finished result.

This applet has a more carefully crafted UI than usual. This has the unfortunate side-effect of bloating the jar's file size (because it includes the UI for the angle dial, the grayscale slider, and the pixel-magnification-panel, among other things)... but I think this bloat is worth it: this applet generates copy-and-paste-able code! On a personal/selfish level: practicing UI design here is very useful, even if it comes at a cost of inconveniencing other developers with a larger jar than necessary.

Most aesthetic layouts probably only contain only 1 or 2 layers. Maybe 3. So I have mixed feelings about this applet starting out with a 5-layer demo. This complicated demo is probably the exception rather than the rule, but I wanted to demonstrate what this architecture is capable of. In most cases, though: you probably only need about 2 layers to make a subtle-but-significant improvement in appearance.

Lists: An Observable List for UIs

This article discusses combining the java.util.List interface with the javax.swing.ListModel interface. That is: suppose you want a list that you can easily interact with, but also that plugs into UI elements.

The Simple Solution

The simplest solution is to implement these two interfaces in one object:

public class MyList implements java.util.List, javax.swing.ListModel {
    ...
}

Several years ago I wrote the WatchableVector with this approach in mind: this class extends the java.util.Stack, so all the data structure logic is built-in. All this class has to do is add support for the listeners.

This list can be plugged directly into a JList, and at the same time you can treat it like it a traditional java.util.List. For example, now if you call java.util.Collections.sort( myList ), the UI will automatically update.

Shortcomings

After working with this class for several years, I started to identify shortcomings in this implementation:

Recursive Listeners. In theory a a observable/observer contract is simple: when a change occurs, then notify the listeners. But in the world of UI: it is my experience that listeners spiral out of control very quickly. Here is a simplified/approximated stack trace diagram of a potential listener problem:

Here the list is represented in blue, and two separate listeners are represented in orange and green. The first listener (orange) is notified that a new file is added to a list, but it knows the list needs to always be alphabetized: so it resorts the list. This ends up triggering the first (orange) listener a second time before the second (green) listener ever hears about the first event. If the second listener actually listens to the described event: it will be confused that elements are being reordered that it doesn't even know exist yet.

This is a contrived example showing a simplified chain reaction. In the real world the first listener might have interacted with a separate data structure, and that structure interacted with another, and another, and as a result: a series of listeners that seemed minimally simple (even elegant?) on paper turn into a nightmare of events. I refer to this as "cascading listeners", but a coworker refers to it as "listener hell".

The Event Dispatch Thread. My ListModel is plugged into a Swing component: so it needs to only ever be updated on the event dispatch thread. But my List is the same as my ListModel: so complex (potentially time-consuming) operations on my list now need to occur on the EDT, or ambiguous "bad things" may happen (in a hard-to-pin-down kind of way).

Multithreading. Consider the illustrated example above: all this is occurring in the event dispatch thread. What happens if another thread wants to access this list? It has to wait, because the call to WatchableVector.add(..) is synchronized, as is the call the WatchableVector.get(index). The operation itself may be relatively fast, but the synchronization lock isn't released until all the listeners have been notified. (Including the potentially recursive listener chain reactions...). If you think of this as an IO-model: there's no reason other threads have to wait to read data from this list while other listeners spin their wheels -- but we should prevent them from write operations.

This weekend I wrote a new class to address these issues: the ObservableList.

Addressing Listener Recursion

The ObservableList continues to support the ListDataListener, but it separates listeners into two categories: synchronized and unsynchronized.

Synchronized Listeners. These listeners are not allowed to modify the list. Because of this contract: it is guaranteed that the ListDataEvent each synchronized listener receives reflects the current state of the list. If both listeners in the previous example were added as synchronized listeners, then the flow of execution will look like the diagram on the right.

Even if the first listener doesn't catch the RecursiveListenerModificationException: the loop that iterates over the listeners will catch it and call e.printStackTrace(), so all the subsequent listeners are guaranteed to carry on as usual.

The downside of this approach is: in a complex environment calls that modify this list should be wrapped with a try/catch clause to catch potential RecursiveListenerModificationExceptions. This will be easy to forget. Hopefully violations will be consistent and easy to identify early in testing. But the positive side is: all the other listeners are protected.

Unsynchronized Listeners. These listeners are allowed to modify the source list, so when you use an unsynchronized listener: you have to accept that the ListDataEvent you receive may be inaccurate. (For example: you may be notified that an element was removed, but in fact a previous listener re-added it! You'll receive that event, too, but probably not in the order you would expect.)

You have the option when adding an unsynchronized listener to also prohibit modification from within that thread. This is intended largely as a safeguard for developers to detect unintended chain reactions.

Addressing Synchronization

My original data structure relied on the synchronized keyword to protect the integrity of the list. But it also kept listener notification inside the synchronization block, so if one thread made a call to modify the list and a second thread later wanted to read from the list: then the second thread could not obtain the synchronization lock until all the listeners had completed.

Here is a crude sequence diagram of what that would look like:

When working with complicated UI elements: sometimes listeners (especially a chain reaction of listeners) can involve very expensive operations. We're blocking thread #2 for no real reason: the actual doAdd() operation is complete, so the list is stable again.

The ObservableList uses Semaphores and not the synchronized keyword. The basic format for all operations that modify the list resemble this:

public Object execute(...) {
 readSemaphore.acquireUninterruptibly( 1 );
 try {
  [ evaluate if this is a null-op, if so: return ]
  readSemaphore.acquireUninterruptibly( MAX-1 );
  try {
   [ do operation ]
  } finally {
   readSemaphore.release( MAX-1 );
  }
  fireSynchronizedEvent(...);
 } finally {
  readSemaphore.release();
 }
 fireUnsynchronizedEvent(...);
 return returnValue;
}

And the format for all operations that retrieve (but do not modify) data from this list resemble:

public Object getSomething() {
 readSemaphore.acquireUninterruptibly();
 try {
  return returnValue;
 } finally {
  readSemaphore.release();
 }
}

Since we already (separately) established that a synchronized listener is forbidden to further modify this list: this provides a safe model for concurrent read operations on this list (including while listeners are being notified). The sequence diagram for the previous example now looks like this:

Now suppose thread #2 is the event dispatch thread, and one of the listeners in thread #1 called: SwingUtilities.invokeAndWait(..). (That is: thread #1 is forcing something to run on the EDT.) In the first model using the synchronized keyword: you will have a deadlock. The EDT is waiting to synchronize against the list, and the thread with that lock is waiting for the EDT. In the second model: there is no deadlock.

Addressing The Event Dispatch Thread

There's probably a reason the java.util.List and javax.swing.ListModel were kept separate: when one class implements both, it's very tempting to forget that object (which may have been pledged to the UI) should never be modified on different threads.

So the ObservableList is designated only as List and not a ListModel. But it has two methods to help UI development:

getListModelEDTMirror(): this returns a separate object that mirrors this list. This object will only be updated in the EDT.

As a result: it may (briefly) be the case that the UI mirror has outdated information, so just because you remove an element from this list doesn't mean it's safe to completely dispose of it. Also if the original list is several thousand elements long: maintaining a copy may be expensive.

getListModelView(): this returns a ListModel with direct access to the parent ObservableList. This is basically the "old-fashioned" solution I previously described. If you use this method: it is your responsibility to only ever modify the ObservableList in the EDT. In most cases: you should not rely on this method, but in some (simple) cases it may be safe.

Other Convenient Features

Here are a few additional features the ObservableList list offers:

Detailed events. The ListDataEvent involves specific list indices to describe operations that occurred.

However sometimes calculating a precise event to describe an operation is as expensive as the operation itself, and sometimes your listener really doesn't care about specific indices.

When you add a listener: you pass an argument indicating whether you want a high level of detail or not. If none of the registered listeners have asked for a high level of detail (or if there simply are no listeners): then an oversimplified CONTENTS_CHANGED events may be used to save time.

ChangeListeners. If you aren't really interested in specifics about ListDataEvents, then it can be cumbersome to add the 3 methods of a ListDataListener. You can instead add a ChangeListener: it has only one method to implement.

The setAll( List ) Method. This is equivalent to calling list.clear() followed by list.addAll( otherList ). However those calls will trigger 2 listener notifications indicating that everything has changed, when it might be the case that a single ListDataEvent.INTERVAL_ADDED event is needed because only 1 element was added. In short: this method can streamline the notifications the listeners receive.

Supplemental Methods with Argument Arrays. Every method that takes a java.util.Collection or java.util.List as an argument now has a supplemental method that accepts an array of elements.

Delegating to an Abstract List. The ObservableList wraps around another java.util.List object. The default constructor creates an ArrayList underneath, but you're welcome to use any other list you prefer.

Conclusion

Usually I try to include an applet with my blog articles to keep your attention, but that really isn't possible with this project. Instead all I can link to this time is the ObservableList itself and the related unit tests.

After years of dealing with (self-inflicted) lessons learned from UI development: I think this list implementation satisfies the need for listeners with safety and efficiency.

Of course I'm not the first person to work on an observable list. Here are some other related efforts that might suit your needs better:

There is an Apache version of the ObservableList, but as far as I can tell it's not optimized for multithreading/safety.

JavaFX has its own ObservableList. They also have a setAll(..) method. (In fact my original implementation named this method "replaceAll(..)", and I changed it based on their example.) But I don't have access to the source for this implementation, so I don't know how optimized it is. Also I don't want to start bundling parts of JavaFX in my apps yet.

The JDesktop project has a static method: ObservableCollections.observableList(java.util.List list). But this implementation does not have a setAll(..) method, and I'm unclear how this is implemented under the hood.

One thing all these approaches do that I appreciate is: they use their own (new) type of listener. The ListDataListener can be a little bit constraining sometimes. (For example: try to describe a List.retainAll( Collection ) operation in terms of a ListDataEvent.) But this listener is how the javax.swing.JList wants to be communicated with, so it's acceptable for my usage.

ListUIs: Adding Decorations to Cells

This is a follow-up to my previous article: TreeUI's: Adding Decorations to Cells.

What is a "Decoration" again?

A decoration is a UI component overlayed inside or on top of another component.

Muted-color minimal buttons/decorations are becoming increasingly common in modern UIs. This is great way to add extra functionality for power users without adding too much visual clutter.

Here is a screenshot of part of my current Firefox window. There are 6 decorations showing:

The star bookmarks a page.

The down arrow presents a list of recent URLs.

The circular arrow refreshes the page.

The left side of the search field lets me change search engines.

The word "Google" is also a decoration indicating what search engine is being used.

The right side of the search field commits my search.

... but there are only 3 non-decorative UI elements showing: the URL field, the history button, and the search field. The decorations add a lot of subtle controls in a small space.

As an accessibility side-note: it's worth mentioning that decorations usually do not receive keyboard focus as you navigate the interface with the tab key. They are second-class citizens when it comes to your window hierarchy. You probably need to provide alternate ways to access these features (menu shortcuts, for example) to help reach a wider target audience.

List Decorations

The section above talked about decorations in general, but what are some examples of decorations for list elements?

Above are search results in a recent youtube query: when you mouse over a thumbnail there is an optional button to add a video to your queue.

Also you could provide buttons to delete list elements, reload, or show progress indicators.

On the right is a new-ish decoration for sound files observed on Mac OS 10.7. When you mouse over the graphic: a play button fades in. When you click the play button: the outer ring appears, and the gray arc proceeds clockwise representing the playback of your sound.

The same playback controls are used for movies, however for movies the controls fade away as soon as you mouse out of the preview area.

(Traditionally these controls have been presented with a thin horizontal row of controls along the bottom of a sound/movie. I'm not trying to argue that Apple's new circular timeline is any better than a horizontal timeline: both could be presented with overlayed controls.)

Implementation

In Swing, JLists (and JTrees) use renderers, where one component is rubber stamped for every element in the list/tree.

This is a great scalable model (because tens of thousands of elements can safely be rendered without too much overhead), but it lacks mouse input. To implement decorations on a list, I developed the DecoratedListUI. This UI manages multiple ListDecorations, which are rubber-stamp overlays to your existing ListCellRenderers.

All you have to do is invoke the following:

ListDecoration[] arrayOfDecorations;
...
myList.setUI( new DecoratedListUI() );
myList.putClientProperty( DecoratedListUI.KEY_DECORATIONS, arrayOfDecorations);

Example

Here is an example that emulates the Mac playback controls with a list of 5 sounds:

You can download this jar (source included) here.

(Note: usually I make an effort to keep my jars small in file size so you can easily plug them in to other projects, but in this case: I ended up bundling several megabytes of wav files inside the jar. So while this jar is nearly 2 MB, the code you need is probably less than 100 KB. Sorry for the inconvenience.)

In this applet: each sound file is an element of a JList. When you select a sound file: decorations appears to play/pause and delete the sound.

In theory you could make some decorations always visible (this might be especially useful for a loading indicator, or a warning indicator?), but personally I want actionable buttons to be limited in number to keep the interface simple.

Also, in case you were wondering: the music file icon is a scalable javax.swing.Icon. I noticed in some contexts on my Mac the background had a sort of plastic glazed look and not a radial gradient, but I decided not to fixate on that level of detail. My replicas are never intended to be pixel-perfect copies, just reasonable likenesses.

And if anyone knows how to reduce the flickering observed in this (and other) applets: please let me know! This does not reproduce when launched as a desktop application, so I'm not sure exactly how to debug this.

TreeUIs: Adding Decorations to Cells

This article discusses a modified TreeUI that lets you add decorations on the right side of your tree. (See this other article for a similar discussion focusing on JLists.)

What do I mean by "Decoration"?

The short answer is, "I'm not exactly sure." It's similar to a button or a label (depending on which one you want), and that's how most users will perceive it, but it is not actually a JComponent, and it does not exist in the Swing hierarchy of your window.

In a JTree: every cell is rendered via a TreeCellRenderer. The same renderer is consulted for every row in the tree, so the intended usage is for one component to be used to display potentially thousands of different values. This is referred to as "stamping", because the renderer is repeatedly painting to the tree without actually belonging to it.

This is a wonderful design regarding memory use, but it becomes difficult to add functionality to trees the same way you can add functionality to text fields and other Swing components -- because you don't have a solid grasp on the hierarchy of elements involved.

The decoration model partially addresses this issue. Swing components are (usually) very well suited to this kind of augmentation. There is nothing sacred about the current implementation of the JTree and how it renders: these components are designed to flexible and, when possible, improved to meet your needs.

Examples

To help paint a better picture of what I'm describing, here is an applet demonstrating tree decorations:

This applet (source code included) is available here. Here is a summary of each decoration:

Progress Indicator: the root node takes a few seconds to load. While it is loading: a progress indicator appears on the right side of the tree. As soon as the tree is fully loaded: the indicator is hidden.

Refresh Button: Once the progress indicator is dismissed, the root node will show a refresh button when it is selected. (When clicked, the node re-loads like it did before.)

Play/Pause Buttons: when the "Playable" node is selected a play/pause toggle is present. (In this demo nothing actually plays, but this was designed with audio playback in mind.)

Warning Indicator: this node shows a pulsing warning icon when selected. (Thanks to the Silk icon set for the image!)

Rating Stars: this node shows 5 rating stars when selected. This is a good demonstration of the current limits of the decoration implementation: clicking and dragging does not work like I would want it to.

Delete Button: this removes the selected node from the list.

The delete button is actually the original motivation for this project: I didn't want the user to have to click a tree node and then navigate somewhere else in the UI to the delete button. In my case this saved several pixels, cleaned up the layout, and made the user's task more efficient. Also because the button is adjacent to what it modifies: there is little room for confusion about which object the user is acting on.

However I am also worried that this model can introduce too much visual clutter (aka "over-stimulation"). To limit the amount of controls the user needs to process I made most of the decorations only appear in a row when that row is selected. Also this helps guard against accidentally clicking the wrong button, which becomes increasingly important when your controls become smaller. Restraining the number of decorations is just a suggestion, though: you can make all your decorations visible all the time if you want to. (For example: if you're always dealing with very advanced users, or if your tree is usually going to be relatively small.)

And lastly: as a personal preference I added an option to highlight the width of the entire row. By default the BasicTreeUI only highlights the text of the tree node when it is selected, but this tree is a kind of hybrid between a tree and a list (or a tree and a table?): so highlighting the entire row seemed like a good idea.

Implementation

The DecoratedTreeUI is an extension of the BasicTreeUI, so it inherits most of the standard tree functionality.

It takes the existing TreeCellRenderer (that the JTree stores) and places it inside its own renderer. On the right side of that renderer it adds all the appropriate decorations as JLabels. As the demo above shows: different tree nodes can have different decorations.

The decoration object you need to supply is represented with three methods:

public abstract static class TreeDecoration {
 public abstract Icon getIcon(JTree tree, Object value, boolean selected, boolean expanded, 
  boolean leaf, int row, boolean isRollover,boolean isPressed);
  
 public abstract boolean isVisible(JTree tree, Object value, boolean selected, boolean expanded, 
   boolean leaf, int row, boolean hasFocus);
  
 public abstract ActionListener getActionListener(JTree tree, Object value, boolean selected, boolean expanded, 
   boolean leaf, int row, boolean hasFocus);
}

These are the only methods you need to implement to add decorations to your tree. And there is also built-in support for the BasicTreeDecoration (for simple labels/buttons) and RepaintingTreeDecoration (for decorations that continually need to repaint).

To install decorations, call:

myTree.setUI(new DecoratedTreeUI());
myTree.putClientProperty( DecoratedTreeUI.KEY_DECORATIONS, myArrayOfDecorations );

Also to give you complete control over how the icons are positioned: there is no padding between decorations. That's not because I think zero padding is a good idea (it's not), but this lets you pad your icons with however many pixels you think is appropriate (instead of an arbitrary amount I made up).

The rest of the implementation is probably relatively boring: the hard parts included identifying the simplest methods I needed to override to add the functionality I wanted, and adding a simple model to arm/disarm the decorations so they really behaved like buttons. As of this writing: the final implementation is about 500 lines of code (not counting comments), so it's not that daunting in the end.